> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Examine traces
> Open any trace to inspect its spans, inputs, outputs, and timing. Explore trace views, translate content, navigate origins, and share results.
The trace viewer is available across [** Logs**](https://www.braintrust.dev/app/~/logs), [** Experiments**](https://www.braintrust.dev/app/~/experiments), and [** Review**](https://www.braintrust.dev/app/~/review). Select any row to open a trace in a panel on the right side of your screen, showing all spans with detailed information about inputs, outputs, timing, and metadata.
Use the button to expand the trace to fullscreen or the button to open it in a separate page.
## Anatomy of a trace
A **trace** represents one end-to-end execution — a single request or interaction in logs, or a single test case run in experiments. Every trace contains one or more **spans**, each representing a unit of work with a start and end time. Spans nest inside each other to reflect your application's execution flow.
Braintrust assigns a type to each span:
| Span type | What it represents |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eval` | The root span for an evaluation run, wrapping a `task` span for your application code. One per test case — contains the input, expected output, and all child spans. |
| `task` | A unit of application logic — a workflow, pipeline step, or named operation. In logs, the root span is always a `task` span. Multiple `task` spans can appear in a single trace. |
| `llm` | A single call to an LLM. Shows the model, messages, parameters, token usage, and cost. |
| `function` | A named block of application logic — retrieval, formatting, routing, etc. |
| `tool` | A tool call made by the model — an external API, code execution, database query, etc. |
| `score` | The result of a scorer — [online](/evaluate/score-online) (in logs) or [offline](/evaluate/write-scorers) (in evaluations). Contains the score value, scorer name, and for [LLM-as-a-judge](/evaluate/llm-as-a-judge) scorers, the judge's reasoning. |
| `review` | A single reviewer's [human review](/annotate/human-review) scores for the span they reviewed. Each reviewer who scores a span produces their own review span, so multiple reviewers can score the same span independently. |
| `automation` | An [automation](/admin/automations) run against a logged trace, such as online scoring or an alert. Contains the automation function's result. |
| `preprocessor` | A [Topics](/observe/topics) step that formats a raw trace into readable text for analysis. The built-in Thread preprocessor is the default. |
| `facet` | A [Topics](/observe/topics) step that summarizes a trace through one lens, such as task, sentiment, or issues. One span per facet. |
| `classifier` | A [Topics](/observe/topics) step that matches a trace to its closest generated topic for each facet. |
Each span has an `id` that identifies it individually, while the trace as a whole is identified by its `root_span_id`. To learn how these IDs work and which to use when querying or linking, see [identify spans and traces](/observe/filter#identify-spans-and-traces).
## Inspect a trace
Select the ** Trace** tab to examine a trace's execution. Switch between three layouts to view the whole trace:
* **Spans** () — Read the trace as a nested call graph.
* **Thread** () — Follow the trace as a conversation, in order.
* **Timeline** () — See execution flow and token efficiency.
### View as a hierarchy
In the **Trace** tab, select **Spans** () to view the trace as a nested hierarchy. Each span is indented under its parent, making it useful for understanding the logical structure of your application: which function called which, how tool calls nest under LLM calls, and how sub-tasks relate to the root task. Expand and collapse branches to navigate the call graph.
Select a span to open its detail panel, which groups the span's data into tabs:
* **Messages** — Input and output messages, tool calls, and annotations. When [topics](/observe/topics) are enabled, topics and facet summaries appear at the top.
* **Details** — Metadata, metrics, parameters, and other non-message fields.
* **Review** — Expected output, [human review](/annotate/human-review) scores, and the output-versus-expected comparison.
* **Activity** — The span's audit log of changes, when audit logging is available.
* **Raw** — The complete JSON representation of the span or trace. See [View raw span data](#view-raw-span-data).
In the nested hierarchy, each span row shows inline metrics. By default, these are duration, total tokens, and estimated LLM cost. Cost is propagated from child spans to parent spans, making it easy to see which parts of a multi-step workflow are consuming the most of your cost budget. A parent span's displayed cost is the sum of its child span costs plus any `metrics.estimated_cost` logged on the parent itself. Use > **Display metric types** to toggle which metrics appear:
* **Duration** (on by default)
* **Total tokens** (on by default)
* **Time to first token**
* **Estimated LLM cost** (on by default)
* **Hit rate** (on by default)
### View as a conversation
In the **Trace** tab, select **Thread** () to view the trace as a conversation thread. This layout displays messages, tool calls, and scores in chronological order, stripping away the hierarchy to show what was said and in what order. Use it for reading agent conversations and understanding the narrative flow of multi-turn interactions.
* By default, the thread layout renders raw span data. Select to apply a preprocessor — choose the built-in **Thread** preprocessor to format the trace as a readable conversation, or select a [custom preprocessor](/observe/topics/custom-facets#create-a-facet) to control exactly how messages are rendered. When [topics](/observe/topics) are enabled, topic tags and facet outputs appear at the top of the thread layout as well.
* Use **Find** or press `Cmd/Ctrl+F` to search within the thread layout and quickly locate specific content such as message text and score rationale. Matches are highlighted in-place using your browser's native highlighting. This search is scoped to the thread layout content — use the trace's [search feature](#search-within-a-trace) to search across spans.
* Select and choose **Refresh** to reload the thread data.
### View as a timeline
In the **Trace** tab, select **Timeline** () to understand execution flow and token efficiency:
* **Timeline bars** — Each bar represents a span scaled by a metric of your choice and color-coded by span type.
* **Token distribution overview** — Breaks down LLM span token usage by type (uncached input, cached read, cache write, and output) and shows cache hit rate per span, making it easy to spot where caching is and isn't working.
To change the metric used to scale the bars and token distribution overview, select and then ** Scale by**. Available options:
* **Duration** (default) — Bar width represents wall-clock time
* **Total tokens** — Bar width represents total token usage, useful for identifying spans that consume the most context
* **Prompt tokens** — Bar width represents input token usage
* **Completion tokens** — Bar width represents output token usage
* **Estimated cost** — Bar width represents the estimated cost of each span
To show only spans of specific types in the timeline and token distribution overview, select and then ** Filter by span type**.
* Enable **Maintain hierarchy** to preserve parent-child relationships: Parent spans are kept even if they don't match the filter, as long as they have matching descendants.
To assess prompt caching effectiveness at a glance, select and then **Cached tokens view**. This filters the timeline to LLM spans only, flattens the hierarchy, and scales each bar by cached read tokens with stacked segments for the input token breakdown (uncached input, cached read, and cache write). The **Scale by** and **Filter by span type** options and **Maintain hierarchy** are unavailable while it's active.
Post-hoc scoring spans (such as AutoEval results applied to logs) run after the root span completes and extend beyond the execution timeline. By default, the timeline hides these scorer spans to focus on the root execution duration. To display scorer spans inline, select and toggle **Include score spans in timeline**. This expands the timeline axis to fit the scoring duration, making it easy to see how long evaluations take to complete on each trace.
### Change span data format
When viewing a trace, each span field (input, output, metadata, etc.) displays data in a specific format. Change how a field displays by selecting the view mode dropdown in the field's header.
Available views:
* **Pretty** - Parses objects deeply and renders values as Markdown (optimized for readability)
* **JSON** - JSON highlighting and folding
* **YAML** - YAML highlighting and folding
* **Tree** - Hierarchical tree view for nested data structures
Additional format-specific views appear automatically for certain data types:
* **LLM** - Formatted AI messages and tool calls with Markdown
* **LLM Raw** - Unformatted AI messages and tool calls
* **HTML** - Rendered HTML content
Your view mode selection is remembered per field type. To set a default view mode for all fields, go to ** Settings** > [** Profile**](https://www.braintrust.dev/app/~/configuration/personal/user) and select your preferred data view. See [Personal settings](/admin/personal-settings#default-data-display-format) for more details.
### View raw span data
When viewing a trace, select a span and then select **Raw** in the span section tabs to view the complete JSON representation. The raw data view shows all fields including metadata, inputs, outputs, and internal properties that may not be visible in other views.
The raw data view has two options:
* **This span** - Shows the complete JSON for the selected span only
* **Full trace** - Shows the complete JSON for the entire trace
Use the search bar to find specific content within the data.
Raw span data is useful when you need to:
* Inspect the complete span structure for debugging
* Find specific fields in large or deeply nested spans
* Verify exact values and data types
* Export or copy the full span for reproduction
### Search within a trace
While viewing a trace, use **Find** or press `Cmd/Ctrl+F` to search for content within the trace. A scope dropdown lets you choose where to search:
* ** This span** — Search only within the currently selected span.
* ** Full trace** — Search across all spans in the trace.
Matching spans are highlighted in the trace tree so you can quickly navigate to relevant content.
Trace search finds content within the currently open trace. To search across all traces in your project, use [filters](/observe/filter).
### Translate message content
Select on a message bubble in the **Thread** () layout, or open the context menu on any string field in the **Spans** () layout, and pick a target language. Choose from English, Spanish, French, German, Japanese, and Chinese, or type any language name.
The translated text appears inline beneath the message, with markdown and code formatting preserved. Translations are not saved to the span. They appear inline for the current session only.
Translation uses the model currently selected in the [Loop](/loop) chat picker. If no AI provider is configured, it falls back to a Braintrust-served [built-in model](/admin/ai-providers#manage-built-in-models). With built-in models also disabled, translation can't run.
## Test and apply evaluators
While viewing a trace, select **Evaluators** to test topic facets and scorers on the current trace.
* **Topic facets**: Test how preprocessors transform the trace data, test what summaries prompts extract, or apply the complete facet (preprocessor + prompt) to see the end-to-end result.
* **Scorers**: Test scorers, apply them to the trace, or configure an automation rule for online scoring.
The **Evaluators** tab is particularly useful when creating [custom facets](/observe/topics/custom-facets) or [scorers](/evaluate/write-scorers), allowing you to iterate quickly by testing against real trace data.
## Create custom trace views
While viewing a trace, select **Views** to create custom visualizations using natural language. Describe how you want to view your trace data and [** Loop**](/loop) will generate the code.
For example:
* "Create a view that renders a list of all tools available in this trace and their outputs"
* "Render the video url from the trace's metadata field and show simple thumbs up/down buttons"
By default, a custom trace view is only visible and editable by the user who created it. To share your view with all users in the project, select **Save** > **Save as new view version** > **Update**.
See [Create custom trace views](/annotate/custom-views) for detailed examples, API reference, and how to embed views in your own applications.
Self-hosted deployments: If you restrict outbound access, allowlist `https://www.braintrustsandbox.dev` to enable custom views. This domain hosts the sandboxed iframe that securely renders custom view code.
## Trace actions
Share, link to, and re-run content from a trace, or jump to where it came from. These options are available from the trace header or span context menus, regardless of the selected tab.
### Share a trace
When viewing a trace:
1. Select **Share**.
2. Choose whether to make the trace **Private** or **Public**. Making a trace public grants access only to that trace.
3. Click **Copy link** and share it with others.
### Link to a trace or span
Every trace and span has a stable URL you can share or generate programmatically.
* **Trace**: open the logs route with `r=` set to the trace's `root_span_id`:
```
https://www.braintrust.dev/app/{org}/p/{project}/logs?r=
```
The `r=` parameter is always the `root_span_id`, not a span's `id`. See [Identify spans and traces](/observe/filter#identify-spans-and-traces).
* **Single span or event**: use the object permalink with the span's `id`:
```
https://www.braintrust.dev/app/{org}/object?object_type=project_logs&object_id=&id=
```
* **From the SDK**: call [`Span.permalink()`](/instrument/advanced-tracing#deep-link-to-spans) to generate a span link without building the URL by hand.
To open a link in a specific view, append the `tvt` and `tv` parameters. See [Open trace URLs in a specific view mode](/kb/open-trace-urls-in-a-specific-view-mode). To build event permalinks from the API without the SDK, see [Creating permalinks to log events via API](/kb/creating-permalinks-to-log-events-via-api).
### Navigate to trace origins
To trace the origin of a trace that comes from a prompt or dataset:
1. Click in the trace header.
2. Choose **Go to origin prompt** or **Go to origin dataset**.
This helps you:
* Trace issues back to the original prompt or dataset
* See which dataset example led to a result
* Move efficiently between trace analysis and refining prompts or datasets
### Re-run a prompt
When viewing a prompt span in a trace:
1. Select **Run**.
2. In the **Run prompt** dialog, make changes as necessary.
3. Select **Test** to see the output.
You can also give this prompt a name and select **Save as custom prompt** to save it to your project's prompt library.
## Next steps
* [Score online](/evaluate/score-online) to apply automated scoring to production traces
* [Add to a dataset](/annotate/datasets/create#promote-traces-from-logs) to curate interesting traces into ground truth
* [Filter and search](/observe/filter) to find specific traces across logs
* [Create dashboards](/observe/dashboards) to monitor metrics at scale
* [Analyze with Loop](/loop) to query across traces with natural language
