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

# 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:

```bash theme={null}
uv pip install -U opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno
```

<Note>
  These packages provide the OpenTelemetry instrumentation infrastructure and the Agno-specific instrumentation logic.
</Note>

## 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()`:

```python theme={null}
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?")
```

<Warning>
  Call `setup_tracing()` **before** creating your agents. This ensures the instrumentation is active when agents are initialized.
</Warning>

### Option 2: Using tracing with AgentOS

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

```python theme={null}
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,
)
```

<Tip>
  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.

  ```python theme={null}
  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.
</Tip>

For detailed AgentOS tracing configuration including multi-database setups, see [Tracing in AgentOS](/agent-os/tracing/overview).

## Dedicated Traces Database

<Warning>
  **Recommended**: Use a separate database for storing traces, especially when you have multiple agents or teams with their own databases.
</Warning>

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

<Accordion title="Example: Multiple Agents with Shared Tracing">
  ```python theme={null}
  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")
  ```
</Accordion>

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.

<Frame caption="Traces stored in SQLite database viewed with TablePlus">
  <img src="https://mintcdn.com/phidatainc-agui/z86_O3EeJ5wD0p21/images/traces-in-db.png?fit=max&auto=format&n=z86_O3EeJ5wD0p21&q=85&s=c8e16f8237db031b06ba4d72e96f501e" alt="Database view showing agno_spans table with trace data including span_id, trace_id, parent_span_id, and operation names" width="2038" height="480" data-path="images/traces-in-db.png" />
</Frame>

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:

```python theme={null}
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:

```python theme={null}
setup_tracing(
    db=db,
    batch_processing=False
)
```

**Pros:**

* Traces appear immediately
* No memory buffering

**Cons:**

* More database writes
* Slight performance overhead

<Tip>
  Use **batch processing** in production and **simple processing** for development/debugging when you need immediate trace visibility.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="DB Functions" icon="database" href="/tracing/db-functions">
    Query traces and spans from your database
  </Card>
</CardGroup>