Explore traces

Find the traces, sessions, and spans your application sent, narrow them down with search and filters, and read each one step by step.

Before you start

• Your application sends traces to a project. To set that up, see Instrument your code.
• To group traces into sessions, your application sets a session ID on each trace. To set that up, see Track users and sessions.

Open a list of traces, sessions, or spans

1. Open your project, and then go to Traces. To find your project, see Create a project.

2. Select the tab for the list you want: Sessions, Traces, or Spans.
3. For Time, select a range.

The Traces list shows one row per trace, newest first. Its stats show Traces, Error rate, p95 duration, Avg duration, Tokens, and Cost.

The Sessions list shows one row per session, most recent activity first. A session groups the traces that share a session ID. Its stats show Sessions, With errors, Avg turns, p95 turns, Tokens, and Cost.

The Spans list shows the individual steps across every trace, such as model calls, tool calls, and retrievals, newest first. Its stats show Spans, Error rate, p95 duration, Avg TTFT (time to first token), Cache hits (the share of prompt tokens served from cache), and Cost.

Time offers these ranges:

• Last 15 minutes
• Last hour
• Last 24 hours (the default)
• Last 7 days
• Last 30 days
• Last 60 days
• Last 90 days

There's no "all time" option. Ranges longer than your project keeps data are unavailable and marked "beyond retention". To learn how long data is kept, see Data retention.

Choose a project on the shared Traces page

If you open Traces without a project in the link, the page asks you to pick one. It shows "Pick a project to see traces".

• For Project, choose your project.

The time range and other settings stay the same when you switch projects.

Search a list

1. In the search box, enter part of a name or ID. The list updates shortly after you stop typing.
2. To clear the search, press Esc.

Each list matches your text against different fields:

Filter a list

1. In the Filters rail, select a value in any group. Each value shows how many rows match it.
2. To see more values in a group, select Show 3 more. The number in the label is the count of values that aren't showing yet. To show fewer, select Show less.
3. To remove one filter, select the remove control on its chip above the list. To remove every filter, select Clear all.

Each list offers these filter groups:

• Traces: Trace, Span Kind, Status, Provider, Model
• Sessions: Has errors, Provider
• Spans: Step, Type, Status, Exception, Provider, Model, Tool, Finish reason, Payload, Service, Environment, Release, Agent, SDK

A No value entry matches rows that have no value for that group. Yes/no values show as yes or no.

On narrow screens, the rail starts collapsed. Select Filters to show it. The page remembers whether you showed or hid it.

Show infrastructure traces and spans

The Traces and Spans lists hide infrastructure calls by default.

• On the Traces list, clear Hide infra traces to include traces whose root is an HTTP or MCP call.
• On the Spans list, clear Hide infra spans to include HTTP and MCP spans. The stats follow this setting.

Show only items that failed a rule

1. For Rules, select Any failed rule, or select a single rule type if the list offers one. Each rule type shows how many items failed it.
2. Review the list. It now shows only items with failing checks, most recent failure first.

While this filter is on, facets and search pause, sorting is off, and the Hide infra checkboxes are hidden. The stats are replaced by a count of the items with failing checks. To learn what rules check, see Rules overview.

Sort, arrange, and page through a list

• Sort: Select a column header. Each selection cycles through descending, ascending, and the default order (newest first).
• Columns: Select Columns to show or hide columns. The label shows how many columns are visible out of the total, for example Columns 9/26. You can't hide the last visible column. Select Reset to defaults to restore the default columns. Your choices are saved in your browser for each list.
• Rows per page: For Show Rows:, select 10, 20, 50, or 100. The default is 20. Changing the page size or a filter takes you back to the first page.
• Pages: Use Go to previous page and Go to next page to move through the list.
• Refresh: Select Refresh to reload the rows and rule results.

Open a trace

1. On the Traces list, select the link in the Trace column. You can also select the link in the Trace id column if you've shown it.

To open the trace with one span already selected, select its link in the Name column on the Spans list instead.

2. Review the stat strip at the top: Message, Duration, Tokens, Spans, Documents, Errors, Rules, and Cost.

The header shows the trace ID and when the trace started. If the trace belongs to a session, a pill reads "Part of chat-4821 — open in session ›". Select it to open the session.

Rules in the stat strip shows a value such as "2 failed", "3 passed", "couldn't run", or "pending". While rules are still running, it adds "so far", as in "3 passed so far". When the trace has rule verdicts, a panel lists them. Totals on the page are calculated when you open it, so treat them as provisional.

Work with the waterfall

The waterfall lists each span with its kind, a bar on a time axis, and its duration.

• Expand rows: Rows more than two levels deep start collapsed and show how many spans they hide, for example "4 hidden". Use the arrow next to a row to expand or collapse it.
• Spot problems: Errored spans are hatched and marked "err". Retrieval spans show how many documents they returned, for example "3 docs".
• Zoom in: Select a span's bar to focus the waterfall on that span and the spans under it. To go back, select the back button in the header, such as Back to the whole trace, or press Esc.
• Find a span: In Search spans, enter part of a span name. The waterfall shows only matching rows.
• Hide span kinds: In the legend, select a kind to hide or show it. The kinds are model call, tool, retrieval, agent, chain, mcp, http, and other. Your hidden kinds carry over to other traces. Select reset to show all kinds again.
• Open a span: Select a span name to open its detail pane.

A trace with more than 2,000 spans shows only the first 2,000. Later spans aren't loaded, so the time axis ends before the trace does.

Read a span's detail

1. In the waterfall, select a span name. The span detail pane opens on the right.

2. On the Input / Output tab, review the span's fields: Type, Status, Duration, Model, Tokens (input and output), First token, Cost, and Children.
3. To share this exact view, select Copy link.
4. To close the pane, select Close span detail (✕) or press Esc.

Drag the pane's edge to resize it. If the span errored, the pane shows the exception type and the error message. Cost appears in USD and is hidden when the span has no price. To learn how cost is estimated, see Cost tracking.

The pane can also show these sections:

• System instructions: Collapsed until you open it. Instructions longer than 8,000 characters are cut short. Select Show all to see the full text, and Copy to copy it.
• Input and output: Previews are capped at 2,000 characters. If the content was truncated, redacted, or expired, a pill shows that state. To learn how withheld content appears, see Redaction overview.
• Retrieved documents: For retrieval spans, this list replaces the output. It shows each document's rank, score, source URI, and chunk ID. Text longer than 320 characters is shortened. Select Show more to see the rest. Document text is capped at 4,000 characters.

The Raw tab shows the stored values the waterfall reads for this span. It doesn't show the original OpenTelemetry span.

Read a session

1. On the Sessions list, select the link in the First message column. If you've shown the Session column, you can select its link instead. The session opens with its first turn selected.

2. Review the stat strip: First message, Traces, Duration, Tokens, Documents, Errors, Rules, and Cost.
3. In the Turns rail, select a turn. Each turn is one trace in the session.

4. In the turn's waterfall, select a span name to open its detail pane.

Each turn in the rail shows its number, its message, and its start time, duration, and token count. Errored turns are marked. The message is the turn's input preview. If there's no preview, the rail shows the root span name, and if that's missing too, the trace ID. A session with more than 500 turns shows only the first 500, with a "capped" pill. To hide the rail, select Collapse turns.

The turn's waterfall and span detail work the same way as on a trace page. For details, see Work with the waterfall.

Use the keyboard to move between turns:

The shortcuts don't work while you're typing in a box or holding a modifier key.

Troubleshooting

Next steps

• Track users and sessions
• Cost tracking
• Rules overview
• Redaction overview