Once Coval is receiving traces — whether you instrumented your agent or imported them from a platform — 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.
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
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
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 |
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.
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.
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.
See also
