> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing

> Store AgentOS traces to inspect run behavior, latency, errors, model calls, and tool calls.

Engineering teams use tracing to diagnose failed runs, slow tools, and unexpected model behavior. Set `tracing=True` to record AgentOS execution spans in a database.

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

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

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    agents=[research_agent],
    db=db,
    tracing=True,
)

app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="traced_agent_os:app", reload=True)
```

The AgentOS database stores the agent's sessions and its traces. View traces in the [AgentOS Control Plane](https://os.agno.com/traces) or query them through the AgentOS API.

## What Tracing Captures

| Span                           | What you can inspect                                  |
| ------------------------------ | ----------------------------------------------------- |
| Agent, team, and workflow runs | Input, output, status, duration, and child operations |
| Model calls                    | Model execution within a run                          |
| Tool calls                     | Tool name, execution timing, result, and errors       |
| Team coordination              | Calls made while the team delegates or coordinates    |
| Workflow steps                 | Execution order and duration for each step            |

AgentOS uses OpenTelemetry instrumentation and stores the resulting traces in an Agno database.

## Choose a Trace Database

| Runtime setup                     | Configuration                | Trace location                      |
| --------------------------------- | ---------------------------- | ----------------------------------- |
| Components share one database     | `db=shared_db, tracing=True` | Shared AgentOS database             |
| Components use separate databases | `db=trace_db, tracing=True`  | Dedicated AgentOS database          |
| AgentOS has no `db`               | `tracing=True`               | First component database discovered |

Set `db` explicitly when the runtime contains components with different databases. Component order determines the fallback database when AgentOS has no database of its own.

## Use a Dedicated Trace Database

Give each component its application database and pass the trace database 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

agent_db = SqliteDb(db_file="tmp/agent.db", id="agent-db")
trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
    db=agent_db,
)

agent_os = AgentOS(
    agents=[research_agent],
    db=trace_db,
    tracing=True,
)

app = agent_os.get_app()
```

This layout gives traces their own retention and access policy while the agent keeps its application data in `agent_db`.

## Configure the Span Processor

Use `setup_tracing()` when you need batched writes or explicit queue settings:

```python custom_tracing.py 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

trace_db = SqliteDb(db_file="tmp/traces.db", id="trace-db")

setup_tracing(
    db=trace_db,
    batch_processing=True,
    max_queue_size=2048,
    max_export_batch_size=512,
    schedule_delay_millis=3000,
)

research_agent = Agent(
    id="research-agent",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    agents=[research_agent],
    db=trace_db,
)

app = agent_os.get_app()
```

`setup_tracing()` configures tracing globally, so call it before creating agents and omit `tracing=True` from AgentOS. Pass the same database to AgentOS so its API and Control Plane can read the stored traces.

## Install Dependencies

The AgentOS extra includes the tracing packages:

```bash theme={null}
uv pip install -U "agno[os]" openai
```

## Next Steps

| Task                        | Guide                                                                    |
| --------------------------- | ------------------------------------------------------------------------ |
| Understand traces and spans | [Tracing concepts](/tracing/overview)                                    |
| Filter stored traces        | [Filter Options](/agent-os/tracing/filter-options)                       |
| Trace an agent              | [Basic Agent Tracing](/agent-os/tracing/usage/basic-agent-tracing)       |
| Trace a team                | [Basic Team Tracing](/agent-os/tracing/usage/basic-team-tracing)         |
| Trace a workflow            | [Basic Workflow Tracing](/agent-os/tracing/usage/basic-workflow-tracing) |