Decorators

Decorators provide automatic timing, error capture, and input/output extraction with minimal boilerplate. Python decorators work on functions; TypeScript decorators work on class methods.

Python decorators

`@pandaprobe.trace`

Creates a new trace for the decorated function. Use this on your top-level entry points.

Parameter	Type	Default	Description
`name`	`str \| None`	Function name	Custom trace name
`session_id`	`str \| None`	From context	Session identifier
`user_id`	`str \| None`	From context	User identifier
`tags`	`list[str] \| None`	`None`	String tags
`metadata`	`dict \| None`	`None`	Key-value metadata

Can be used with or without parentheses:

import pandaprobe

@pandaprobe.trace
def run_agent(query: str):
    ...

import pandaprobe

@pandaprobe.trace(name="custom-name", tags=["production"])
def run_agent(query: str):
    ...

Input/output capture

Input: Automatically captured from function arguments (uses inspect.signature to build a JSON-friendly dict).
Output: Automatically captured from the return value.
At the trace level, the SDK extracts only the last user message from input and the last assistant message from output.

Why trace-level message extraction?

Trace views often focus on the conversational turn. Full structured arguments remain available in raw span data when you need deeper inspection.

`@pandaprobe.span`

Creates a new span within the current trace. Use this on inner functions.

Parameter	Type	Default	Description
`name`	`str \| None`	Function name	Custom span name
`kind`	`str \| SpanKind`	`OTHER`	Span kind (LLM, TOOL, AGENT, etc.)
`model`	`str \| None`	`None`	Model name (for LLM spans)
`metadata`	`dict \| None`	`None`	Key-value metadata

Python

@pandaprobe.span(name="retrieve-docs", kind="RETRIEVER")
def retrieve(query: str) -> list[str]:
    ...

@pandaprobe.span(name="llm-call", kind="LLM", model="gpt-5.4")
def call_llm(messages: list[dict]) -> str:
    ...

@pandaprobe.span requires an active trace context. If no trace exists (no enclosing @pandaprobe.trace or pandaprobe.start_trace()), the function runs without instrumentation.

Sync and async support

Both decorators auto-detect sync vs async functions and wrap accordingly.

Sync
Async

Python

@pandaprobe.trace(name="my-agent")
def run_agent(query: str) -> str:
    result = call_llm(query)
    return result

@pandaprobe.span(name="llm-call", kind="LLM")
def call_llm(query: str) -> str:
    ...

Python

@pandaprobe.trace(name="my-agent")
async def run_agent(query: str) -> str:
    result = await call_llm(query)
    return result

@pandaprobe.span(name="llm-call", kind="LLM")
async def call_llm(query: str) -> str:
    ...

Nesting

Python

@pandaprobe.trace(name="support-agent")
def handle_request(query: str) -> str:
    docs = retrieve_docs(query)
    answer = generate_answer(query, docs)
    return answer

@pandaprobe.span(name="retrieve", kind="RETRIEVER")
def retrieve_docs(query: str) -> list[str]:
    ...

@pandaprobe.span(name="generate", kind="LLM", model="gpt-5.4")
def generate_answer(query: str, docs: list[str]) -> str:
    ...

This produces: Trace("support-agent") → Span("retrieve", RETRIEVER) → Span("generate", LLM).

Combining with wrappers

Python

from pandaprobe.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

@pandaprobe.trace(name="my-agent")
def run_agent(query: str) -> str:
    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": query}],
    )
    return response.choices[0].message.content

The wrapper’s LLM span is automatically nested as a child of the trace.

Pair decorators with provider wrappers so LLM calls inherit hierarchy and you still get token usage and model metadata on child spans.

No-op behavior

If the SDK is disabled (PANDAPROBE_ENABLED=false) or no client is available, both decorators pass through transparently: the decorated function runs normally with no overhead.

No-op mode is intentional for local development and tests where you omit API keys or disable tracing globally.

TypeScript decorators

Import trace, span, and SpanKind from the base package. Both current Stage 3 decorators and legacy TypeScript decorator emit are supported.

TypeScript

import { SpanKind, flush, span, trace } from "pandaprobe";

interface Messages {
  messages: Array<{ role: string; content: string }>;
}

class SupportAgent {
  @span({ name: "retrieve-docs", kind: SpanKind.RETRIEVER })
  async retrieve(query: string): Promise<string[]> {
    return [`Documentation matching: ${query}`];
  }

  @span({ name: "generate", kind: SpanKind.LLM, model: "gpt-4o-mini" })
  async generate(_input: Messages): Promise<Messages> {
    return { messages: [{ role: "assistant", content: "Here is the answer." }] };
  }

  @trace({ name: "support-agent", tags: ["production"] })
  async run(input: Messages): Promise<Messages> {
    await this.retrieve(input.messages.at(-1)?.content ?? "");
    return this.generate(input);
  }
}

const result = await new SupportAgent().run({
  messages: [{ role: "user", content: "How does tracing work?" }],
});
console.log(result.messages[0]?.content);
await flush();

TypeScript trace options

Parameter	Type	Default	Description
`name`	`string`	Method name	Custom trace name
`sessionId`	`string \| null`	From async context	Session identifier
`userId`	`string \| null`	From async context	User identifier
`tags`	`string[]`	`[]`	String tags
`metadata`	`Record<string, unknown>`	`{}`	Key-value metadata

TypeScript span options

Parameter	Type	Default	Description
`name`	`string`	Method name	Custom span name
`kind`	`SpanKind`	`SpanKind.OTHER`	Span kind
`model`	`string \| null`	`null`	Model name for LLM spans
`metadata`	`Record<string, unknown>`	`{}`	Key-value metadata

For input capture, a single object argument is preserved as-is; other argument lists are stored under args. Return values become span outputs. The trace decorator extracts the last user and assistant messages when the standard messages shape is used.

TypeScript decorators can decorate class methods only. For standalone functions or inline scopes, use withTrace() and withSpan().

Like Python, @span runs without instrumentation when there is no active trace, and both decorators pass through when PandaProbe is disabled or unconfigured.

Get Started

Tracing

Python decorators

`@pandaprobe.trace`

`@pandaprobe.span`

Sync and async support

Nesting

Combining with wrappers

No-op behavior

TypeScript decorators

TypeScript trace options

TypeScript span options

​Python decorators

​@pandaprobe.trace

​@pandaprobe.span

​Sync and async support

​Nesting

​Combining with wrappers

​No-op behavior

​TypeScript decorators

​TypeScript trace options

​TypeScript span options

Python decorators

`@pandaprobe.trace`

`@pandaprobe.span`

Sync and async support

Nesting

Combining with wrappers

No-op behavior

TypeScript decorators

TypeScript trace options

TypeScript span options