Skip to content

Traces

Stable

Covered by the 1.0 API freeze (proposal 0029): no breaking change before 2.0.

One record per tool call, redacted by default. See traces for how to use them.

Tracer

Tracer(sinks: TraceSink | Iterable[TraceSink], *, arguments: bool = False, principals: PrincipalMode = 'hash', key: bytes | None = None)

Builds redacted traces and sends them to sinks. A failing sink never fails a call.

CallTrace dataclass

CallTrace(tool: str, outcome: Outcome, started_at: float, duration_ms: float, result_tokens: int, tokenizer: str, budget: int | None = None, truncated: bool = False, attempts: int = 1, effect: str | None = None, error_category: str | None = None, error_code: str | None = None, principal: str | None = None, parent: str | None = None, resolved_by: str | None = None, replayed: bool = False, truncation: Mapping[str, Any] | None = None, arguments: Mapping[str, Any] | None = None, trace_id: str = (lambda: secrets.token_hex(8))())

One tool call as the server handled it.

TraceSink

Bases: Protocol

MemorySink

MemorySink(max_traces: int = 1000)

Keeps the most recent traces in memory (tests, ouncemcp dev).

JsonlSink

JsonlSink(path: str | Path)

Appends one JSON object per call to a file.

LoggingSink

LoggingSink(level: int = logging.INFO)

Logs one line per call to the ouncemcp.trace logger.

CallbackSink

CallbackSink(callback: Callable[[CallTrace], None])

Calls a function with each trace.

redact_text

redact_text(text: str) -> str

errors.redact plus personal data: email addresses and phone numbers.

redact_value

redact_value(value: Any, depth: int = 0) -> Any

A copy of value that is safe to keep in a trace.