A trace represents a complete execution of your AI agent, from start to finish. It captures everything that happened during that execution: LLM calls, tool invocations, decisions, and outcomes.

Trace Structure

Trace: research_agent"quantum computing"

Span: plan_research45ms

Span: search_papers

LLM Call: gpt-41.2s250 tokens

Tool: web_search340ms

Span: summarize_findings

LLM Call: gpt-42.1s890 tokens

Complete3.7s$0.045

Info

Every trace has a unique trace_id that you can use to look up the execution in the dashboard or in your logs.

What's Captured in a Trace?

Execution Timing

Start time, end time, and total duration of the trace and each span within it.

Span Hierarchy

The parent-child relationships between operations, showing the execution flow.

LLM Metadata

Model name, provider, token counts (prompt and completion), and estimated costs.

Tool Invocations

Which tools were called, how long they took, and whether they succeeded.

Status & Errors

Whether the trace completed successfully, errored, or was cancelled.

Custom Attributes

Any additional context you add via the @observe() decorator.

Creating Traces in Code

The easiest way to create a trace is with the @observe() decorator. The top-level decorated function becomes the root of your trace:

agent.py

python

from traccia import observe

@observe()  # This creates the root trace
def my_agent(query: str) -> str:
    # Everything inside becomes part of this trace
    plan = create_plan(query)
    result = execute_plan(plan)
    return result

@observe()  # This creates a child span
def create_plan(query: str) -> dict:
    # ...
    pass

@observe()  # Another child span
def execute_plan(plan: dict) -> str:
    # ...
    pass

Traces vs Spans

Trace

• Represents the entire execution
• Has a unique trace_id
• Contains one or more spans
• The "big picture" view

Span

• Represents a single operation
• Has its own span_id
• Can have parent/child relationships
• The detailed view of each step

Think of a trace like a receipt for a complex order: it shows everything that happened, while each span is a line item with specific details.

Traces

Trace Structure

What's Captured in a Trace?

Creating Traces in Code

Traces vs Spans

Trace

Span

Next Steps

Learn About Spans

OpenTelemetry Basics