Tracing

​

Why is Observability Important?

• Debugging: See exactly what went wrong when an agent fails
• Performance: Identify bottlenecks in agent execution
• Cost Tracking: Monitor token usage and API calls
• Behavior Analysis: Understand decision-making patterns
• Audit Trail: Track what agents did and why

​

Understanding Traces and Spans

​

Trace

​

Span

• What happened: Operation name (e.g., agent.run, model.response)
• When: Start and end timestamps
• Context: Input arguments, outputs, token usage
• Relationships: Parent span, child spans
• Metadata: Agent ID, session ID, run ID

​

What Gets Traced

​

Key Features

• Zero-Code Instrumentation: No need to modify your agent code
• Database Storage: Traces stored in your Agno database (SQLite, PostgreSQL, etc.)
• Flexible Querying: Filter by agent, session, run, or time range
• OpenTelemetry Standard: Export to external tools like Arize Phoenix, Langfuse, and The Context Company
• Low Overhead: Set batch_processing=True to batch and export traces in the background
• Configurable: Adjust batch sizes and processing for your needs

​

Quick Start

uv pip install -U openai agno sqlalchemy opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno

from agno.tracing import setup_tracing
from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="tmp/traces.db")
setup_tracing(db=db) # Call this once at startup

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

agent = Agent(
    name="My Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions="You are a helpful assistant",
)

agent.run("Hello!")  # Automatically traced!

traces, total = db.get_traces(agent_id=agent.id, limit=10)
for trace in traces:
    print(f"{trace.name}: {trace.duration_ms}ms")

​

Guides