> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pandaprobe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing and context

> Decorators, trace and span contexts, session propagation, and trace capture

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](#spancontext), [TraceCapture](#tracecapture), [TraceContext](#tracecontext), [get\_current\_session\_id](#get_current_session_id), [get\_current\_trace](#get_current_trace), [get\_current\_user\_id](#get_current_user_id), [get\_span\_stack](#get_span_stack), [reset\_current\_session\_id](#reset_current_session_id), [reset\_current\_user\_id](#reset_current_user_id), [session](#session), [set\_current\_session\_id](#set_current_session_id), [set\_current\_user\_id](#set_current_user_id), [set\_session](#set_session), [set\_user](#set_user), [span](#span), [start\_trace](#start_trace), [trace](#trace), [user](#user).

## Example

```python theme={null}
import pandaprobe
from pandaprobe import Client

client = Client()
try:
    with pandaprobe.session("customer-42"), pandaprobe.user("user-7"):
        with client.capture_traces() as capture:
            with client.trace("lookup") as trace:
                with trace.span("policy", kind="TOOL") as span:
                    span.set_input({"order_id": "ORDER-101"})
                    span.set_output({"refundable": "merchandise"})
        print(capture.trace_ids)  # Submission IDs, not a persistence confirmation.
finally:
    client.shutdown()
```

## `SpanContext`

```python theme={null}
from pandaprobe.tracing import SpanContext
```

Context manager for an individual span.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/span.py#L20)

### Constructor

```text theme={null}
SpanContext(
  trace_ctx: TraceContext,
  name: str,
  *,
  kind: SpanKind=SpanKind.OTHER,
  model: str | None=None,
  metadata: dict[str, Any] | None=None,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `trace_ctx` | `TraceContext` | Required |
| `name` | `str` | Required |
| `kind` | `SpanKind` | `SpanKind.OTHER`; keyword only |
| `model` | `str \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `span_id` | `str` | Instance value; read-only; Read-only property. |

### Methods

> [accordion] set\_input
>
> Sets the recorded input. Trace and LLM inputs use the messages schema; other span kinds may use domain values.
>
> ```text theme={null}
> set_input(input: Any) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `input` | `Any` | Required |

> [accordion] set\_output
>
> Sets the recorded output. Trace and LLM outputs use the messages schema; other span kinds may use domain values.
>
> ```text theme={null}
> set_output(output: Any) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `output` | `Any` | Required |

> [accordion] set\_token\_usage
>
> Records supplied token counts and additional numeric usage. This setter does not measure token use itself.
>
> ```text theme={null}
> set_token_usage(*, prompt_tokens: int=0, completion_tokens: int=0, **extra: int) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `prompt_tokens` | `int` | `0`; keyword only |
> | `completion_tokens` | `int` | `0`; keyword only |
> | `extra` | `int` | Additional arguments |

> [accordion] set\_model
>
> Records the model identifier for this span.
>
> ```text theme={null}
> set_model(model: str) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `model` | `str` | Required |

> [accordion] set\_model\_parameters
>
> Records the supplied model invocation parameters.
>
> ```text theme={null}
> set_model_parameters(params: dict[str, Any]) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `params` | `dict[str, Any]` | Required |

> [accordion] set\_cost
>
> Records supplied total cost and any additional named cost components. It does not look up provider prices.
>
> ```text theme={null}
> set_cost(*, total: float, **extra: float) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `total` | `float` | Required; keyword only |
> | `extra` | `float` | Additional arguments |

> [accordion] set\_completion\_start\_time
>
> Records the time completion output began, such as the first streamed token.
>
> ```text theme={null}
> set_completion_start_time(ts: datetime) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `ts` | `datetime` | Required |

> [accordion] set\_error
>
> Records an error message and sets the span status to ERROR.
>
> ```text theme={null}
> set_error(error: str) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `error` | `str` | Required |

> [accordion] set\_metadata
>
> Merges metadata into the current record; existing keys with the same name are replaced.
>
> ```text theme={null}
> set_metadata(metadata: dict[str, Any]) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `metadata` | `dict[str, Any]` | Required |

## `TraceCapture`

```python theme={null}
from pandaprobe.tracing.capture import TraceCapture
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/capture.py#L18)

### Constructor

```text theme={null}
TraceCapture(
  variable: ContextVar,
  *,
  metadata: dict[str, Any] | None=None,
  session_id: str | None=None,
  max_traces: int=1000,
  on_submit: Callable[[dict[str, Any]], None] | None=None,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `variable` | `ContextVar` | Required |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |
| `session_id` | `str \| None` | `None`; keyword only |
| `max_traces` | `int` | `1000`; keyword only |
| `on_submit` | `Callable[[dict[str, Any]], None] \| None` | `None`; keyword only |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `trace_ids` | `list[str]` | Instance value; Instance attribute. |
| `overflow` | `Not annotated` | Instance value; Instance attribute. |
| `closed` | `Not annotated` | Instance value; Instance attribute. |

## `TraceContext`

```python theme={null}
from pandaprobe.tracing import TraceContext
```

Context manager that wraps a trace lifecycle.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/context.py#L35)

### Constructor

```text theme={null}
TraceContext(
  client: Client,
  name: str,
  *,
  input: Any=None,
  session_id: str | None=None,
  user_id: str | None=None,
  tags: list[str] | None=None,
  metadata: dict[str, Any] | None=None,
  **kwargs: Any,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `Client` | Required |
| `name` | `str` | Required |
| `input` | `Any` | `None`; keyword only |
| `session_id` | `str \| None` | `None`; keyword only |
| `user_id` | `str \| None` | `None`; keyword only |
| `tags` | `list[str] \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |
| `kwargs` | `Any` | Additional arguments |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `trace_id` | `str` | Instance value; read-only; Read-only property. |

### Methods

> [accordion] span
>
> ```text theme={null}
> span(
>   name: str,
>   *,
>   kind: str | SpanKind=SpanKind.OTHER,
>   model: str | None=None,
>   metadata: dict[str, Any] | None=None,
> ) -> SpanContext
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `name` | `str` | Required |
> | `kind` | `str \| SpanKind` | `SpanKind.OTHER`; keyword only |
> | `model` | `str \| None` | `None`; keyword only |
> | `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

> [accordion] set\_output
>
> Sets the recorded output. Trace and LLM outputs use the messages schema; other span kinds may use domain values.
>
> ```text theme={null}
> set_output(output: Any) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `output` | `Any` | Required |

> [accordion] set\_input
>
> Sets the recorded input. Trace and LLM inputs use the messages schema; other span kinds may use domain values.
>
> ```text theme={null}
> set_input(input: Any) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `input` | `Any` | Required |

> [accordion] set\_metadata
>
> Merges metadata into the current record; existing keys with the same name are replaced.
>
> ```text theme={null}
> set_metadata(metadata: dict[str, Any]) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `metadata` | `dict[str, Any]` | Required |

> [accordion] set\_status
>
> Sets the trace status using a supported TraceStatus value.
>
> ```text theme={null}
> set_status(status: TraceStatus | str) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `status` | `TraceStatus \| str` | Required |

> [accordion] add\_span\_data
>
> ```text theme={null}
> add_span_data(span_data) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `span_data` | `Not annotated` | Required |

## `get_current_session_id`

```python theme={null}
from pandaprobe.tracing.session import get_current_session_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L19)

```text theme={null}
get_current_session_id() -> str | None
```

## `get_current_trace`

```python theme={null}
from pandaprobe.tracing.context import get_current_trace
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/context.py#L27)

```text theme={null}
get_current_trace() -> TraceContext | None
```

## `get_current_user_id`

```python theme={null}
from pandaprobe.tracing.session import get_current_user_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L41)

```text theme={null}
get_current_user_id() -> str | None
```

## `get_span_stack`

```python theme={null}
from pandaprobe.tracing.context import get_span_stack
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/context.py#L31)

```text theme={null}
get_span_stack() -> list[str]
```

## `reset_current_session_id`

```python theme={null}
from pandaprobe.tracing.session import reset_current_session_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L29)

```text theme={null}
reset_current_session_id(token: Token[str | None]) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `token` | `Token[str \| None]` | Required |

## `reset_current_user_id`

```python theme={null}
from pandaprobe.tracing.session import reset_current_user_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L51)

```text theme={null}
reset_current_user_id(token: Token[str | None]) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `token` | `Token[str \| None]` | Required |

## `session`

```python theme={null}
from pandaprobe import session
```

Context manager that sets a session ID for its scope.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/__init__.py#L150)

```text theme={null}
session(session_id: str)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `session_id` | `str` | Required |

## `set_current_session_id`

```python theme={null}
from pandaprobe.tracing.session import set_current_session_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L24)

```text theme={null}
set_current_session_id(session_id: str | None) -> Token[str | None]
```

| Parameter | Type | Default / passing |
| - | - | - |
| `session_id` | `str \| None` | Required |

## `set_current_user_id`

```python theme={null}
from pandaprobe.tracing.session import set_current_user_id
```

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

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/tracing/session.py#L46)

```text theme={null}
set_current_user_id(user_id: str | None) -> Token[str | None]
```

| Parameter | Type | Default / passing |
| - | - | - |
| `user_id` | `str \| None` | Required |

## `set_session`

```python theme={null}
from pandaprobe import set_session
```

Set the session ID for the current context.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/__init__.py#L140)

```text theme={null}
set_session(session_id: str) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `session_id` | `str` | Required |

## `set_user`

```python theme={null}
from pandaprobe import set_user
```

Set the user ID for the current context.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/__init__.py#L171)

```text theme={null}
set_user(user_id: str) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `user_id` | `str` | Required |

## `span`

```python theme={null}
from pandaprobe import span
```

Decorator that wraps a function in a `SpanContext`.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/decorators.py#L115)

```text theme={null}
span(
  _fn: Callable[..., Any] | None=None,
  *,
  name: str | None=None,
  kind: str | SpanKind=SpanKind.OTHER,
  model: str | None=None,
  metadata: dict[str, Any] | None=None,
) -> Any
```

| Parameter | Type | Default / passing |
| - | - | - |
| `_fn` | `Callable[..., Any] \| None` | `None` |
| `name` | `str \| None` | `None`; keyword only |
| `kind` | `str \| SpanKind` | `SpanKind.OTHER`; keyword only |
| `model` | `str \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

## `start_trace`

```python theme={null}
from pandaprobe import start_trace
```

Start a new trace and return a `TraceContext` context manager.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/__init__.py#L86)

```text theme={null}
start_trace(
  name: str,
  *,
  input: Any=None,
  session_id: str | None=None,
  user_id: str | None=None,
  tags: list[str] | None=None,
  metadata: dict[str, Any] | None=None,
  **kwargs: Any,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `name` | `str` | Required |
| `input` | `Any` | `None`; keyword only |
| `session_id` | `str \| None` | `None`; keyword only |
| `user_id` | `str \| None` | `None`; keyword only |
| `tags` | `list[str] \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |
| `kwargs` | `Any` | Additional arguments |

## `trace`

```python theme={null}
from pandaprobe import trace
```

Decorator that wraps a function in a `TraceContext`.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/decorators.py#L29)

```text theme={null}
trace(
  _fn: Callable[..., Any] | None=None,
  *,
  name: str | None=None,
  session_id: str | None=None,
  user_id: str | None=None,
  tags: list[str] | None=None,
  metadata: dict[str, Any] | None=None,
) -> Any
```

| Parameter | Type | Default / passing |
| - | - | - |
| `_fn` | `Callable[..., Any] \| None` | `None` |
| `name` | `str \| None` | `None`; keyword only |
| `session_id` | `str \| None` | `None`; keyword only |
| `user_id` | `str \| None` | `None`; keyword only |
| `tags` | `list[str] \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

## `user`

```python theme={null}
from pandaprobe import user
```

Context manager that sets a user ID for its scope.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/__init__.py#L181)

```text theme={null}
user(user_id: str)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `user_id` | `str` | Required |

***

Signatures and fields are generated from the [SDK source](https://github.com/chirpz-ai/pandaprobe-sdk/tree/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python). See the [import index](https://docs.pandaprobe.com/reference/python/overview.md#public-import-index) for available entry points.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.