Skip to main content
A trace represents one application invocation; spans record work inside it. Use a trace’s span factory or decorators so parentage and context are established automatically. Exceptions from traced application code propagate after recording an error. Trace input contains the current turn’s user message; trace output contains the final assistant message. LLM spans can contain the full model message history. Session and user scopes propagate attribution; they do not store an agent conversation. Trace capture observes IDs submitted by existing instrumentation. It does not create traces or wait for export/persistence. Consume streams inside the capture/execution boundary. A capture is single-use; late descendant work retains attribution but is no longer added to the closed capture’s ID list. Trace/span contexts support both with and async with. Function decorators support synchronous and asynchronous functions; span without an active trace simply executes the original function. start_trace raises if no global client is available. For capture, use with client.capture_traces(...) as capture.

On this page

SpanContext, TraceCapture, TraceContext, get_current_session_id, get_current_trace, get_current_user_id, get_span_stack, reset_current_session_id, reset_current_user_id, session, set_current_session_id, set_current_user_id, set_session, set_user, span, start_trace, trace, user.

Example

SpanContext

Context manager for an individual span. Source declaration

Constructor

Fields and properties

Methods

Sets the recorded input. Trace and LLM inputs use the messages schema; other span kinds may use domain values.
Sets the recorded output. Trace and LLM outputs use the messages schema; other span kinds may use domain values.
Records supplied token counts and additional numeric usage. This setter does not measure token use itself.
Records the model identifier for this span.
Records the supplied model invocation parameters.
Records supplied total cost and any additional named cost components. It does not look up provider prices.
Records the time completion output began, such as the first streamed token.
Records an error message and sets the span status to ERROR.
Merges metadata into the current record; existing keys with the same name are replaced.

TraceCapture

Source declaration

Constructor

Fields and properties

TraceContext

Context manager that wraps a trace lifecycle. Source declaration

Constructor

Fields and properties

Methods

Sets the recorded output. Trace and LLM outputs use the messages schema; other span kinds may use domain values.
Sets the recorded input. Trace and LLM inputs use the messages schema; other span kinds may use domain values.
Merges metadata into the current record; existing keys with the same name are replaced.
Sets the trace status using a supported TraceStatus value.

get_current_session_id

Return the session ID set in the current context, or None. Source declaration

get_current_trace

Source declaration

get_current_user_id

Return the user ID set in the current context, or None. Source declaration

get_span_stack

Source declaration

reset_current_session_id

Reset the session ID to its previous value using the given token. Source declaration

reset_current_user_id

Reset the user ID to its previous value using the given token. Source declaration

session

Context manager that sets a session ID for its scope. Source declaration

set_current_session_id

Set the session ID for the current context. Returns a reset token. Source declaration

set_current_user_id

Set the user ID for the current context. Returns a reset token. Source declaration

set_session

Set the session ID for the current context. Source declaration

set_user

Set the user ID for the current context. Source declaration

span

Decorator that wraps a function in a SpanContext. Source declaration

start_trace

Start a new trace and return a TraceContext context manager. Source declaration

trace

Decorator that wraps a function in a TraceContext. Source declaration

user

Context manager that sets a user ID for its scope. Source declaration

Signatures and fields are generated from the SDK source. See the import index for available entry points.