> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.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](https://agno-v2.mintlify.site/tracing/overview.md) |
| Filter stored traces | [Filter Options](https://agno-v2.mintlify.site/agent-os/tracing/filter-options.md) |
| Trace an agent | [Basic Agent Tracing](https://agno-v2.mintlify.site/agent-os/tracing/usage/basic-agent-tracing.md) |
| Trace a team | [Basic Team Tracing](https://agno-v2.mintlify.site/agent-os/tracing/usage/basic-team-tracing.md) |
| Trace a workflow | [Basic Workflow Tracing](https://agno-v2.mintlify.site/agent-os/tracing/usage/basic-workflow-tracing.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.