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

# Tracing

Tracing gives you a detailed, step-by-step record of how your agents process requests. Each trace captures the full execution path — tool calls, LLM invocations, retrieved context, and returned outputs — so you can debug failures, measure latency, and verify that your agents are behaving as intended.

Tracing is designed for real-time and near-real-time inspection. Spans appear within seconds of execution, making it ideal for active debugging and development workflows. For aggregated, historical analysis of agent performance, see [Reports](/reports) instead.

<Note>
  Tracing captures live execution data and is best suited for debugging and testing. For trend analysis and operational reporting, use [Agent Reports](/reports) instead.
</Note>

## What tracing captures

Each trace is composed of **spans** — individual units of work performed during a single agent run. Together, spans form a tree that reflects the full lifecycle of a request.

Traces are organized into **turns**, where each turn represents one round of user input and agent response. Within a turn, you can see every model call, tool invocation, and sub-agent operation that took place.

| Span type      | What it shows                                            |
| -------------- | -------------------------------------------------------- |
| **Model**      | LLM inference steps, including token counts and latency  |
| **Tools**      | Tool calls made during the run (e.g., `search_mcp_tool`) |
| **Sub-agents** | Nested agent invocations and their outputs               |

The **Conversation Details** panel alongside each trace shows the full message history for that conversation, broken down by human messages, AI messages, and sub-agent messages.

## Reading a trace

Traces are displayed as a hierarchical span tree. The root span represents the top-level agent invocation; child spans nest beneath it in the order they were executed.

**To inspect a trace:**

1. **Select a trace** from the trace list. Traces are labeled and include a timestamp and duration.
2. **Navigate turns** using the turn selector at the top left. Each turn shows its total duration and token count.
3. **Expand spans** by clicking any row in the span tree. Child spans (model calls, tool calls) nest under their parent.
4. **View span details** in the center panel. Toggle between **Preview** (formatted) and **Metadata** (raw) views, and expand **Input** and **Output** to inspect the exact data passed to and returned from each step. Some spans may show `No data available` if input/output logging is not enabled.
5. **Copy identifiers** using the **Copy Trace ID** or **Copy Step ID** buttons for use in support requests or cross-referencing logs. You can also **Download JSON** to export the full trace payload.

## Conversation Details

The **Conversation Details** panel on the right provides a human-readable view of the conversation alongside the trace. It shows:

* **Total messages** across the conversation
* A **breakdown** of message types: human, AI, and sub-agent
* The full **Conversation Messages** thread, so you can see exactly what the user asked and how the agent responded at each turn

Use this panel to connect low-level span data to the actual user experience. If a span looks correct in the trace but the agent's response was wrong, the conversation view helps identify where the output diverged from expectations.

## Best practices

* **Use tracing during development** to confirm that tool calls are firing in the right order with the right inputs.
* **Check token counts per turn** to catch unexpectedly large context windows that may affect latency or cost.
* **Inspect failed spans** — errors surface inline in the span tree, with the failure point clearly marked.
* **Cross-reference with [Conversation Insights](/reports#conversation-insights)** when you need to connect execution-level data to customer experience outcomes like sentiment and resolution.
* **Download the JSON payload** for complex traces to analyze span timing or share with your engineering team.