Tracing

Trace agent, team, and workflow runs with OpenTelemetry and store spans in a configured database or observability backend.

v2.3.5

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

1. Install tracing dependencies

   uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno
   
2. 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.")
   
3. 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 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.