Python SDK

The Python SDK mirrors the TypeScript one. It lives in packages/sdk-python, has no third-party dependencies, and supports Python 3.9+. It is not published to PyPI yet: pip install -e packages/sdk-python.

import os
from tracemason import Tracemason

scope = Tracemason(api_key=os.environ["TRACEMASON_API_KEY"])

session = scope.start_session(agent="research-agent", environment="staging")

session.record_event(
    type="tool.execution",
    tool="database.query",
    metadata={"operation": "SELECT", "resource": "analytics"},
)

session.end()
scope.shutdown()

Timing tool calls

with session.tool("database.query", category="database.query"):
    rows = db.execute(sql)

The block is timed; an exception is recorded as tool.failed (type only) and re-raised.

asyncio

session = await scope.astart_session("research-agent")
await session.arecord_event("tool.execution", tool="http.get", hosts=["api.example.com"])
await session.aend()
await scope.ashutdown()

Recording is non-blocking in both styles; the async flush methods run delivery in a worker thread.

Behaviour

  • Events are queued and delivered by a daemon thread every 2 seconds or when 100 are waiting. The thread never keeps your process alive, and atexit flushes on normal exit.
  • Network errors, 429 and 5xx are retried with exponential backoff and jitter; 401 and other 4xx are not.
  • The queue is bounded (5,000 by default). Overflow drops the oldest events and counts them in scope.stats().
  • Recording never raises. Pass on_error=callable to be told about delivery problems.
  • Events go to the hosted service at https://app.tracemason.com. Pass endpoint= (or set TRACEMASON_ENDPOINT) only for a self-hosted server; it must be https, except localhost.
  • Tracemason(enabled=False) is a no-op, for tests.

Options

Tracemason(api_key, endpoint=None, *, allow_metadata_keys=(), flush_interval=2.0, max_batch_size=100, max_queue_size=5000, max_retries=5, on_error=None, enabled=True, timeout=10.0)

scope.start_session(agent, *, agent_type="custom", model=None, environment=None, repository=None, branch=None)

session.record_event(type, *, tool=None, category=None, outcome=None, duration_ms=None, error_type=None, files=None, hosts=None, usage=None, metadata=None)

session.report_error(exc), session.trace_context(), scope.continue_session(context), scope.flush(), scope.stats().

Redaction

Same rules as everywhere else: metadata keys are allowlisted, values are scanned for credential patterns, nested values are never sent. Extend the allowlist with allow_metadata_keys=[...].