Skip to main content
This guide walks you through setting up tracing for your Agno agents. Tracing is designed to be simple: install dependencies, enable tracing, and all your agents are automatically instrumented.

​
Installation

Install the required OpenTelemetry packages: 
pip install -U opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno
These packages provide the OpenTelemetry instrumentation infrastructure and the Agno-specific instrumentation logic.

​
Two Ways to Enable Tracing

There are two ways to enable tracing in Agno:
  1. setup_tracing() - Use this function for standalone scripts, notebooks, and custom applications. Provides full control over configuration options like batch processing, queue sizes, and export delays.
  2. AgentOS tracing=True - Use this parameter when deploying agents through AgentOS. Simpler setup for production deployments with sensible defaults.

​
Option 1: Using setup_tracing()

For standalone scripts, notebooks, or custom applications: 
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.tracing import setup_tracing

# Set up your tracing database
tracing_db = SqliteDb(db_file="tmp/traces.db")

# Enable tracing (call this ONCE at startup)
setup_tracing(db=tracing_db)

# Create and run agents - they're automatically traced!
agent = Agent(
    name="Research Agent",
    model=OpenAIChat(id="gpt-4o-mini"),
    instructions="You are a research assistant",
)

response = agent.run("What is quantum computing?")
Call setup_tracing() before creating your agents. This ensures the instrumentation is active when agents are initialized.

​
Option 2: Using AgentOS

When deploying agents with AgentOS, you can enable tracing with a simple parameter: 
from agno.os import AgentOS

agent_os = AgentOS(
    agents=[my_agent],
    tracing=True,  # Enable tracing
    db=tracing_db,
)
For detailed AgentOS tracing configuration including multi-database setups, see Tracing in AgentOS.

​
Dedicated Traces Database

Recommended: Use a separate database for storing traces, especially when you have multiple agents or teams with their own databases.
When agents and teams each have their own databases for sessions and memory, traces should go to a dedicated central database. This ensures:
  • Unified observability: All traces in one place for cross-agent analysis
  • Simpler querying: No need to search multiple databases
  • Independent scaling: Traces can grow independently from agent data
  • Cleaner separation: Agent data and observability data don’t mix
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.tracing import setup_tracing
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.hackernews import HackerNewsTools

# Each agent has its own database for sessions/memory
agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")

# Dedicated database for ALL traces (separate from agent databases)
tracing_db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Enable tracing to the dedicated database
setup_tracing(
    db=tracing_db,
    batch_processing=True,
    max_queue_size=1024,
    max_export_batch_size=256,
)

# Agent 1: HackerNews specialist with its own database
hackernews_agent = Agent(
    name="HackerNews Agent",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HackerNewsTools()],
    instructions="You are a hacker news agent. Answer questions concisely.",
    markdown=True,
    db=agent1_db,  # Agent's own database
)

# Agent 2: Web search specialist with its own database
search_agent = Agent(
    name="Web Search Agent",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[DuckDuckGoTools()],
    instructions="You are a web search agent. Answer questions concisely.",
    markdown=True,
    db=agent2_db,  # Agent's own database
)

# Both agents are traced to the same tracing_db
hackernews_agent.run("What's trending on HackerNews?")
search_agent.run("Latest AI news")

# Query traces for both agents from one place
traces, count = tracing_db.get_traces(limit=20)
print(f"Found {count} traces across all agents")
Once configured, traces and spans are automatically stored in your database. The tracing system creates two tables: agno_traces for high-level trace information and agno_spans for individual span details.
Database view showing agno_spans table with trace data including span_id, trace_id, parent_span_id, and operation names

Traces stored in SQLite database viewed with TablePlus

Each span record includes the trace_id to group related operations, parent_span_id for hierarchy, and the operation name (e.g., Stock_Price_Agent.run, OpenAIChat.invoke, get_current_stock_price).

​
Processing Modes

Agno supports two trace processing modes:

​
Batch Processing (Default)

Batch processing collects traces in memory and writes them in batches. This is more efficient and recommended for production: 
setup_tracing(
    db=tracing_db,
    batch_processing=True,
    max_queue_size=2048,           # Max traces in memory
    max_export_batch_size=512,     # Traces per batch write
    schedule_delay_millis=5000,    # Export every 5 seconds
)
Pros:
  • Lower database load
  • Better performance
  • Minimal impact on agent execution
Cons:
  • Slight delay before traces appear (default 5 seconds)
  • Traces in memory if application crashes before export

​
Simple Processing

Simple processing writes each trace immediately: 
setup_tracing(
    db=tracing_db,
    batch_processing=False
)
Pros:
  • Traces appear immediately
  • No memory buffering
Cons:
  • More database writes
  • Slight performance overhead
Use batch processing in production and simple processing for development/debugging when you need immediate trace visibility.

​
Next Steps

DB Functions

Query traces and spans from your database

Cookbook

Full example code