Basic Setup

Configure and enable tracing for your Agno agents

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:

uv 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 tracing with SDK

For standalone scripts, notebooks, or custom applications use setup_tracing():

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

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

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

# Create and run agents - they're automatically traced!
agent = Agent(
    name="Research Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    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 tracing with AgentOS

When deploying agents with AgentOS, you can enable tracing with a simple parameter:

from agno.os import AgentOS
from agno.db.sqlite import SqliteDb

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

agent_os = AgentOS(
    agents=[my_agent],
    tracing=True,  # Enable tracing
    db=db,
)

You can also use setup_tracing() to configure tracing for AgentOS but make sure to pass the db to AgentOS so traces are accessible through the AgentOS API and UI.

from agno.os import AgentOS
from agno.tracing import setup_tracing

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

agent_os = AgentOS(
    agents=[my_agent],
    db=db, # <-- Pass the db to AgentOS so traces are accessible through the AgentOS API and UI.
)

db is required in AgentOS to ensure traces are accessible through the AgentOS API and UI.

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

Example: Multiple Agents with Shared Tracing

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.tracing import setup_tracing
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)
db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Enable tracing to the dedicated database
setup_tracing(
    db=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=OpenAIResponses(id="gpt-5.2"),
    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=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    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 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 = 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.

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

Batch processing collects traces in memory and writes them in batches. This is more efficient and recommended for production:

setup_tracing(
    db=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 (Default)

Simple processing writes each trace immediately:

setup_tracing(
    db=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