> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing

> Configure tracing for agents, teams, and workflows in AgentOS.

Set `tracing=True` on `AgentOS` to record agent, team, workflow, model, and tool spans in a database. View stored traces in the [AgentOS UI](https://os.agno.com/traces).

<Note>
  For a comprehensive introduction to Agno Tracing concepts (traces, spans, and what gets captured), see the [Tracing Overview](/tracing/overview).
</Note>

## Prerequisites

Install the required packages:

```bash theme={null}
uv pip install -U "agno[os]" openai opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno ddgs
export OPENAI_API_KEY=***
```

## Database Configuration

How you configure tracing depends on your database setup:

| Scenario               | Configuration             | Where Traces Are Stored                |
| ---------------------- | ------------------------- | -------------------------------------- |
| Single shared database | `tracing=True`            | The shared database                    |
| Multiple databases     | `tracing=True` + `db=...` | The dedicated `db`                     |
| No `db` specified      | `tracing=True`            | First database found (not recommended) |

<Note>
  We recommend a separate, dedicated database for traces. It keeps them all in one place, which makes them easier to query and analyze.
</Note>

## Single Database Setup

If all your agents and teams share the **same database instance**, enabling tracing is simple:

```python theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

# Single shared database for everything
db = SqliteDb(db_file="tmp/agno.db")

agent = Agent(
    name="Research Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,  # Uses shared db
)

# Enable tracing - traces stored in the shared db
agent_os = AgentOS(
    agents=[agent],
    db=db,
    tracing=True,  # Traces go to the shared db
)

app = agent_os.get_app()
```

In this setup, traces are automatically stored in the shared database alongside sessions and other data.

## Multiple Databases Setup

<Warning>
  When agents or teams have **different databases**, it is highly recommended that you specify a dedicated `db` to ensure all traces are stored in one central location.
</Warning>

If you have multiple agents with their own databases, traces need a dedicated database:

```python theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tools.hackernews import HackerNewsTools
from agno.tools.websearch import WebSearchTools

# Each agent has its own database
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 traces (separate from agent databases)
db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Agent 1 with its own database
hackernews_agent = Agent(
    name="HackerNews Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    db=agent1_db,
)

# Agent 2 with its own database
search_agent = Agent(
    name="Search Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[WebSearchTools()],
    db=agent2_db,
)

# AgentOS with dedicated tracing database
agent_os = AgentOS(
    agents=[hackernews_agent, search_agent],
    tracing=True,
    db=db,  # All traces go here
)

app = agent_os.get_app()
```

### Why Use a Dedicated Tracing Database?

Without `db`, AgentOS stores all traces in the **first database it finds** from your agents, teams, or workflows. The selected database depends on component order.

With a dedicated `db`:

* **Unified observability**: All traces in one queryable location
* **Cross-agent analysis**: Compare performance across agents
* **Independent scaling**: Traces don't affect agent data storage
* **Predictable behavior**: You control exactly where traces go

## Using setup\_tracing() with AgentOS

You can also use `setup_tracing()` for more control over tracing configuration. In this case, you still need to ensure the tracing database is available to AgentOS:

```python theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.tracing import setup_tracing

# Agent databases
agent1_db = SqliteDb(db_file="tmp/agent1.db", id="agent1_db")
agent2_db = SqliteDb(db_file="tmp/agent2.db", id="agent2_db")

# Dedicated tracing database
db = SqliteDb(db_file="tmp/traces.db", id="traces_db")

# Set up tracing with custom configuration
setup_tracing(
    db=db,
    batch_processing=True,
    max_queue_size=2048,
    schedule_delay_millis=3000,
)

# Create agents
agent1 = Agent(name="Agent 1", model=OpenAIResponses(id="gpt-5.2"), db=agent1_db)
agent2 = Agent(name="Agent 2", model=OpenAIResponses(id="gpt-5.2"), db=agent2_db)

# Pass db to AgentOS for trace querying via API
agent_os = AgentOS(
    agents=[agent1, agent2],
    db=db,  # Makes traces queryable via AgentOS API
)

app = agent_os.get_app()
```

<Note>
  Even when using `setup_tracing()`, pass `db` to AgentOS so traces are accessible through the AgentOS API and UI.
</Note>

<Tip>
  Use a dedicated `db` when traces need separate retention, access, or scaling policies.
</Tip>