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
atexitflushes on normal exit. - Network errors,
429and5xxare retried with exponential backoff and jitter;401and other4xxare 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=callableto be told about delivery problems. - Events go to the hosted service at
https://app.tracemason.com. Passendpoint=(or setTRACEMASON_ENDPOINT) only for a self-hosted server; it must behttps, exceptlocalhost. 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=[...].