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

# Viewing Traces

> Inspect a single call's spans in the trace viewer, and see where runs fail with Transition Hotspots.

Once Coval is receiving traces — whether you [instrumented your agent](/concepts/simulations/traces/opentelemetry) or [imported them from a platform](/concepts/simulations/traces/imports) — you can inspect a single call span by span, or step back and see where a whole run fails. To search across many calls at once, see [Trace Search](/concepts/conversations/trace-search).

## Viewing traces in Coval

After a simulation completes or conversation traces are received, an **OTel Traces** card automatically appears in the metric grid on the result page when trace data is available. The card shows the total span count and a **View Traces** button that navigates directly to the trace viewer.

To view traces: open a run or conversation result, click into a result, and click the OTel Traces card. You can also navigate directly via URL:

```
https://app.coval.dev/<org-slug>/runs/<run-id>/results/<simulation-output-id>/traces
```

Traces appear within a few seconds of the simulation completing or being submitted.

### Trace viewer features

The trace viewer has two visualization modes you can switch between using the toggle in the header:

**Waterfall view** — Shows spans as horizontal bars on a timeline, nested by parent-child relationships. Use the collapse/expand controls to focus on specific parts of the call hierarchy. You can filter by span type using the color-coded legend pills in the header.

**Flame graph view** — Shows all spans stacked by depth, giving a birds-eye view of where time is spent. Interactions include:

* **Scroll** to pan the timeline left/right
* **Ctrl/Cmd + scroll** to zoom in and out
* **Drag-select** a region to zoom into that time range
* **Double-click** a span to zoom to fit that span's duration
* **Press F** to reset the view to fit the full trace
* A **mini-map** above the flame graph shows the full trace with your current viewport highlighted — drag it to pan quickly

In both views, clicking any span opens a **detail panel** on the right showing the span's attributes, timing, status, and parent chain. When no span is selected, the detail panel shows a **trace summary** with total spans, duration, span type breakdown with time percentages, slowest spans, and any error spans.

## Transition Hotspots

Transition Hotspots give you a run-level view of how conversations flow through your agent's states — and where they fail. Rather than inspecting individual simulations one by one, you can see the full distribution of state-to-state transitions across an entire run at a glance.

### Walkthrough

<iframe className="w-full aspect-video rounded-xl" src="https://www.loom.com/embed/22d81a41276340f4b7fb42609dc455bc" title="Loom Video" frameBorder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

### Accessing Transition Hotspots

The **Hotspots** tab appears on the run results page when at least one simulation in the run has OTel trace data. Navigate to a run, then click the **Hotspots** tab. If the tab is not visible, the run does not contain any traced simulations.

You can also access it directly via the `?view=hotspots` query parameter on the run results URL.

### Reading the heatmap

The Hotspots view displays a heatmap matrix where:

* **Rows** represent the origin state of a transition (the "from" state)
* **Columns** represent the destination state (the "to" state)
* **Each cell** represents a pair of states — for example, "greeting → account\_lookup"

Toggle between two views using the buttons in the header:

| View             | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| **Counts**       | Each cell shows how many times that state-to-state transition occurred across all simulations in the run |
| **Failure Rate** | Each cell shows the percentage of simulations that failed when hitting that transition                   |

Darker cells indicate higher counts or higher failure rates, depending on the active view.

### Drilling down

Click any cell in the heatmap to open a detail panel showing:

* The total count and failure count for that transition
* **Exemplar simulations** — individual simulations that passed through that state transition, with direct links to review them

Use exemplars to understand why a particular transition has a high failure rate: open a failing simulation and inspect the transcript and trace together.

### Top Hotspots sidebar

The **Top Hotspots** sidebar ranks state transitions by failure count, making it easy to find the most impactful problems without scanning the full matrix. The top-ranked transitions are the ones where the most simulations failed.

### Span filters

Use the **span type filters** to include or exclude specific span types from the transition analysis. Wrapper spans — such as `conversation`, `pipeline`, `transport`, and `session:*` spans — are automatically collapsed and filtered by default, so the heatmap focuses on the meaningful transitions within your agent's processing logic.

<Tip>
  Start with the **Failure Rate** view to find which transitions are most problematic, then switch to **Counts** to understand the volume. A transition with a 100% failure rate but only 1 occurrence is less concerning than one with a 30% failure rate across 50 simulations.
</Tip>

## See also

* [Trace Search](/concepts/conversations/trace-search) — search and filter across every traced call, not just one.
* [Trace metrics](/concepts/metrics/types/trace) — turn span data into metrics.