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. Use withTrace/withSpan for callback functions or trace/span for native class-method decorators (legacy and Stage 3 forms). A TraceContext can own a callback with run, or be explicitly entered and ended. Always finish explicit contexts. Session/user callback scopes use AsyncLocalStorage. TraceCapture is a type-only root export: obtain it from client.captureTraces(...) and call run(...).

On this page

SpanContext, SpanContextOptions, SpanDecoratorOptions, TraceCapture, TraceCaptureOptions, TraceContext, TraceContextOptions, TraceDecoratorOptions, WithSpanOptions, WithTraceOptions, getCurrentTrace, getSpanStack, session, setSession, setUser, span, startTrace, trace, user, withSpan, withTrace.

Example

SpanContext

Source declaration

Constructor

Fields and properties

Methods

The output recorded on this span (used to mirror it onto standalone traces).
The trace this span belongs to (used to attach sibling/child tool spans).
Enter the span: record start time, set parent, push onto the trace’s stack.
End the span: record end time/status, finalize, pop from the trace’s stack.
Run fn within this span (callback form).
Wrap a sync-or-async invocation in this span (decorator form). Sets the given input, captures the return value as output, and preserves the original return type (sync stays sync, async stays async).
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.

SpanContextOptions

Source declaration

Fields and properties

SpanDecoratorOptions

Source declaration

Fields and properties

TraceCapture

Observes submissions, without creating traces or guaranteeing persistence. Source declaration

Constructor

Fields and properties

Methods

TraceCaptureOptions

Source declaration

Fields and properties

TraceContext

Source declaration

Constructor

Fields and properties

Methods

Enter the trace context imperatively. Pair with end().
End the trace, finalize, and restore the previous ambient context.
Run fn within this trace’s context (callback form).
Wrap a sync-or-async invocation in this trace’s context (decorator form).
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.

TraceContextOptions

Source declaration

Fields and properties

TraceDecoratorOptions

Source declaration

Fields and properties

WithSpanOptions

Source declaration

Fields and properties

WithTraceOptions

Source declaration

Fields and properties

getCurrentTrace

Source declaration

getSpanStack

The span stack of the active trace (each trace owns its own stack). Source declaration

session

Run fn with a session ID set for its scope (the callback analog of Python’s with pandaprobe.session(id):). Type parameters: T. Source declaration

setSession

Set the session ID for the current context. Source declaration

setUser

Set the user ID for the current context. Source declaration

span

Method decorator that wraps a class method in a SpanContext. Source declaration

startTrace

Start a new trace and return its TraceContext, already entered. Source declaration

trace

Method decorator that wraps a class method in a TraceContext. Source declaration

user

Run fn with a user ID set for its scope (concurrency-safe, run-based). Type parameters: T. Source declaration

withSpan

Run fn inside a span on the active trace (callback form). Type parameters: T. Source declaration

withTrace

Run fn inside a new trace (callback form). Type parameters: T. Source declaration

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