The trace.py module

Summary

Functions

new_trace_id	Return a new 12-character trace id.
current_trace_id	Return the trace id of the tool call running in this context.
bind_trace_id	Make trace_id the current trace id.
reset_trace_id	Restore the trace id that was current before bind_trace_id().
log_call	Log one line for a finished tool call.

Description

Per-call trace ids so host-side and server-side logs line up.

Every wrapped tool call gets a short trace id. The server logs one line per call (tool, trace id, duration, outcome); error results carry the id as trace_id; code running inside the call can read current_trace_id().

Module detail

trace.new_trace_id() → str

Return a new 12-character trace id.

Returns:

str

Random hexadecimal id.

trace.current_trace_id() → str | None

Return the trace id of the tool call running in this context.

Returns:

str | None

The trace id, or None outside a tool call.

trace.bind_trace_id(trace_id: str) → contextvars.Token[str | None]

Make trace_id the current trace id.

Parameters:

trace_idstr

Trace id of the call that is starting.

Returns:

contextvars.Token[str | None]

Token to pass to reset_trace_id() when the call ends.

trace.reset_trace_id(token: contextvars.Token[str | None]) → None

Restore the trace id that was current before bind_trace_id().

Parameters:

tokencontextvars.Token[str | None]

Token returned by bind_trace_id().

trace.log_call(tool: str, trace_id: str, duration_ms: int, outcome: str) → None

Log one line for a finished tool call.

Parameters:

toolstr

Tool name.

trace_idstr

Trace id of the call.

duration_msint

Wall time in milliseconds.

outcomestr

ok, error:, or raised.