Open a trace when aggregate views are not enough. A trace shows the exact request path: spans, timing, model input and output, tool calls, metadata, evaluator results, and IDs.
Open the trace viewer
From the Traces table, select a row. The trace viewer opens in a side sheet. You can resize or maximize the sheet when you need more space.
The viewer header shows:
- Trace name.
- Span count.
- Status.
- Total latency.
- Previous and next trace controls.
Use arrow-key navigation when reviewing many traces in a filtered result set.
Use tree view
Tree view is best for understanding structure. It shows parent-child relationships between model calls, tools, retrieval, guardrails, orchestration, and custom spans.
Use tree view to answer:
- Which span failed?
- Which span produced the final output?
- Did the model call the expected tool?
- Did a tool response arrive before the assistant answered?
- Were evaluator results attached to the relevant span?
- Which spans belong to the prompt or Behavior you are investigating?
When a trace is opened from a prompt filter, matching prompt spans can be visually highlighted so you can see which part of a larger trace matched the filter.
Use waterfall view
Waterfall view is best for timing. It shows how spans overlap and where time is spent.
Use waterfall view to answer:
- Is the request slow because of one span or many spans?
- Are tool calls happening in sequence or parallel?
- Is retrieval dominating the request?
- Is model latency the primary issue?
- Did retries or fallbacks add time?
For latency incidents, inspect waterfall view before editing a prompt. A prompt change may not help if the slow path is a backend tool or retrieval service.
Inspect span details
Select a span to inspect details. Depending on the span type, details can include:
- Input and output content.
- Provider and model.
- Cost and token usage.
- Tool arguments and responses.
- Retrieval context.
- Tags and attributes.
- Status and timing.
- Evaluator scores and reasons.
- Prompt and deployment context when available.
Read span details in context. A model output can look wrong because the input was missing context, a tool returned stale data, or an upstream router selected the wrong path.
Use trace IDs and span IDs
Trace IDs and span IDs are useful when you need exact reproduction, API lookup, support handoff, or dataset creation.
- Use a trace ID when the entire request matters.
- Use a span ID when one model, tool, retrieval, or guardrail step matters.
- Preserve IDs in incident notes only when your data policy allows it.
Decide what to do next
| What you find | Next step |
|---|
| A single important failed model span | Add the span to a dataset and create evaluator coverage. |
| A repeated user or assistant pattern | Open Behaviors and check whether the pattern is clustered. |
| Tool arguments are wrong | Fix tool schema or prompt tool-use instructions. |
| Tool response is wrong or slow | Debug the tool or backend service. |
| Prompt output is wrong despite good context | Start Improve or edit the prompt. |
| Evaluator reason is wrong | Fix evaluator criteria or dataset labels. |
| Deployment caused the behavior | Compare deployments and roll back if needed. |
Privacy check
Trace details can include production user content and application metadata. Before sharing a trace screenshot or export, remove emails, raw IDs, secrets, API keys, tokens, and private customer data.
When a trace is useful enough to discuss twice, turn it into durable evidence: a dataset row, evaluator case, Behavior investigation, or Improve focus.
