Tracing

A final run response shows the outcome. Tracing shows the model calls, tool executions, and nested agent, team, or workflow operations that produced it. Developers use traces to investigate failures, latency, token usage, and unexpected tool behavior.

Trace an Agent

Install tracing dependencies

uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno

Configure database export

Call setup_tracing() once at application startup, before creating agents.

tracing_agent.py

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.tracing import setup_tracing

traces_db = SqliteDb(db_file="tmp/traces.db")
setup_tracing(db=traces_db)

agent = Agent(
    id="support-agent",
    model=OpenAIResponses(id="gpt-5.4-mini"),
    instructions="Answer support questions concisely.",
)

agent.run("Summarize the latest support request.")

Query stored traces

traces, total = traces_db.get_traces(agent_id="support-agent", limit=10)

for trace in traces:
    print(trace.name, trace.duration_ms)

setup_tracing(db=...) installs Agno’s DatabaseSpanExporter and instruments agents, teams, and workflows through OpenTelemetry.

Traces viewed in AgentOS — Traces stored in SQLite and viewed in AgentOS

Traces and Spans

Concept	Description
Trace	One complete execution, identified by `trace_id`
Span	One timed operation within the trace, such as an agent run, model response, or tool execution
Parent-child relationship	Connects nested operations into the execution hierarchy

What Gets Traced

Agno instrumentation captures spans for:

Operation	Examples
Agent runs	`agent.run()` and `agent.arun()`
Model calls	Model requests and responses
Tool execution	Tool calls and results
Team execution	Leader coordination and member runs
Workflow execution	Workflow runs and step execution

Spans carry timing, status, relationships, and operation attributes. Trace payloads can include application inputs and outputs. Review captured attributes before sending traces to a shared or external destination.

Choose a Trace Destination

Tracing storage follows the OpenTelemetry configuration in your application:

Configuration	Destination
`setup_tracing(db=...)`	The selected Agno database through `DatabaseSpanExporter`
`AgentOS(..., tracing=True, db=...)`	The AgentOS database, available through its API and Control Plane
A custom OpenTelemetry provider instrumented with `AgnoInstrumentor`	The backend configured by that provider’s exporter

Use Agno OpenTelemetry integrations when traces should go to an external observability backend. The exporter configuration determines where those spans are sent.

Immediate and Batch Export

setup_tracing() writes each completed span immediately by default. Set batch_processing=True to queue spans and export them in batches.

setup_tracing(
    db=traces_db,
    batch_processing=True,
    max_queue_size=2048,
    max_export_batch_size=512,
    schedule_delay_millis=5000,
)

Parameter	Default	Purpose
`batch_processing`	`False`	Use batched export instead of immediate export
`max_queue_size`	`2048`	Maximum queued spans
`max_export_batch_size`	`512`	Maximum spans in one export batch
`schedule_delay_millis`	`5000`	Delay between scheduled batch exports

Next Steps

Basic Setup

Configure SDK and AgentOS tracing.

Tracing in AgentOS

Store and inspect traces for an AgentOS runtime.

Database Functions

Query traces and spans from an Agno database.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Trace an Agent

Traces and Spans

What Gets Traced

Choose a Trace Destination

Immediate and Batch Export

Next Steps

Basic Setup

Tracing in AgentOS

Database Functions

​Trace an Agent

​Traces and Spans

​What Gets Traced

​Choose a Trace Destination

​Immediate and Batch Export

​Next Steps

Basic Setup

Tracing in AgentOS

Database Functions

Trace an Agent

Traces and Spans

What Gets Traced

Choose a Trace Destination

Immediate and Batch Export

Next Steps