Skip to content
Opswald Docs

Traces Overview

You’ll learn what traces are, what data they capture, and how to use them to understand your agent’s behavior end to end.

What is a Trace?

A trace is the complete record of a single agent execution. When a user sends a message and your agent processes it — calling LLMs, invoking tools, making decisions — the trace captures everything that happened from start to finish.

import opswald


with opswald.trace('support-ticket-handler') as t:
    # Everything here is captured in one trace
    intent = classify(user_message)
    response = generate_response(intent)
    send_reply(response)

What Traces Capture

FieldDescription
NameIdentifier for the agent run (e.g., support-ticket-handler)
Trace IDUnique UUID assigned automatically
Start/End TimeWhen the trace began and completed
DurationTotal execution time
SpansAll individual steps within the trace
StatusSuccess, error, or in progress
MetadataCustom key-value pairs you attach

Creating Traces

# Context manager (recommended)
with opswald.trace('my-agent-run') as t:
    ...


# Decorator
@opswald.trace_function
def my_agent(user_input):
    ...

Grouping Spans

Traces automatically group all spans created within their scope. Spans nest to form a tree:

Trace: "support-ticket-handler"
├── Span: "classify-intent" (llm_call, 230ms)
├── Span: "fetch-context" (tool_call, 45ms)
├── Span: "generate-response" (llm_call, 890ms)
│   ├── Span: "retrieve-policy" (tool_call, 120ms)
│   └── Span: "format-reply" (custom, 5ms)
└── Span: "send-reply" (custom, 15ms)

This hierarchy shows both what happened and how the steps relate to each other.

Viewing Traces in the Dashboard

In the Opswald dashboard, traces appear as rows in the Traces list. Click any trace to see:

  1. Timeline view — All spans on a horizontal timeline showing duration and overlap
  2. Tree view — Nested span hierarchy
  3. Detail panel — Click any span to see its inputs, outputs, tokens, and metadata

Filtering Traces

Use the dashboard filters to find specific traces:

  • By name — Search for traces by their name
  • By time range — Filter to a specific time window
  • By status — Show only errors or successful runs
  • By duration — Find slow traces that need optimization

See Dashboard Filters for the full filtering reference.

Next Steps