> ## 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. # Debug a trace > Diagnose why a trace failed using evidence from spans, tool calls, and model outputs, or summarize a long agent trace into the work it performed. export const feature_0 = "The Debugger" export const verb_0 = "is" A long agent trace can span dozens of LLM and tool calls, which makes reading it end to end impractical. Braintrust offers two [Loop](/docs/loop)-powered analyses for this: the **Debugger**, which diagnoses why a trace went wrong, and **Analyze trace**, which explains what a trace did. Both are available on traces in your project logs. They don't appear on experiment or dataset traces, or in embedded and human review contexts. {feature_0} {verb_0} in [public preview](/docs/feature-lifecycle) and can change before reaching general availability. ## Diagnose a failure Use the **Debugger** when you know a trace went wrong but not why, and the trace is too long to read span by span. Loop identifies the failure modes it considers likely and cites the evidence behind each one, so you start from something concrete instead of scrolling. Open a trace from the [** Logs**](https://www.braintrust.dev/app/~/logs) page and select the **Debugger** layout. Click **Run debugger**. If a report already exists for the trace, the button reads **Run again**. While Loop works, a **Debugger progress** panel shows the steps completed so far and the elapsed time, and its menu offers **View in Loop** and **Run again**. See [What's in a report](#whats-in-a-report) for how it's organized. Select any evidence item to jump to that span in the trace, scrolled to the field it came from with the supporting phrase highlighted. To take a diagnosis further, click **Continue in Loop** on the report and ask follow-up questions against the full project. See [Analyze traces](/docs/loop/capabilities#analyze-traces). A run is recorded on the trace rather than in the browser tab that started it, so it survives a reload or a switch to another tab, and a teammate who opens the same trace sees it in progress. If the last run didn't produce a report, whether it failed or it ended without writing one, the Debugger says so in a banner above **Run debugger**, with the error when there is one. Re-run the Debugger after you've changed the underlying behavior and logged a new trace, or when you want a second pass on the same one.

What's in a report

A report from the Debugger opens with a **Summary** of what Loop found, followed by one entry per failure mode. The tab shows a count once findings exist. Each finding carries a title, a severity of **critical**, **high**, **medium**, or **low**, and a short label for the area it relates to, such as `infrastructure`, `evaluation`, or `tool_call`. Severity is **medium** when Loop doesn't specify one, so treat that level as unranked rather than as a deliberate judgment. Within a finding: * **Hypothesis** is what Loop believes went wrong. * **Potential root cause** is why it believes that happened. * **Evidence** lists the spans, tool calls, and model outputs behind the finding. * **Next steps**, when Loop has something specific to suggest, are the smallest useful actions to take. When Loop has actions that cut across findings rather than belonging to any one of them, the report ends with its own **Next steps** list. A finding that relates to a recorded [pattern](/docs/observe/patterns) also shows a badge with the pattern's name. Select it to open the pattern and see the other traces behind it. That finding's **Next steps** carries the pattern's **Suggested fix**. Treat the Debugger's findings as a starting hypothesis with evidence attached, not a verdict. Each finding points at the spans it came from so you can check the reasoning yourself. ## Summarize what a trace did Use **Analyze trace** when you want to understand an unfamiliar trace rather than diagnose it, and answer "what happened here" before deciding whether anything went wrong. 1. Open a trace from the [** Logs**](https://www.braintrust.dev/app/~/logs) page and select the **Timeline** () layout. 2. Click **Analyze trace** in the timeline header. If the trace has already been analyzed, the button reads **Reanalyze**. 3. Review the **Work sections**. Loop groups the meaningful LLM and tool spans into the work the trace performed and explains what each one contributed. ## Where the Debugger fits The Debugger also runs underneath [Patterns](/docs/observe/patterns). When a scheduled Loop automation investigates your project, it uses the same analysis to inspect individual traces closely enough to support a finding. The two connect in both directions. Selecting a trace from a pattern's evidence opens it in the Debugger, scrolled to the span the evidence came from with the quoted terms highlighted. Going the other way, a Debugger report includes findings from any pattern that cites the debugged trace as evidence, each linking back to the pattern it came from. A finding that appears in the report may therefore come from an earlier investigation rather than from the run you just triggered. ## Next steps * [Examine traces](/docs/observe/examine-traces) to navigate spans, timelines, and threads by hand. * [Review and act on patterns](/docs/observe/patterns/review) to see the same analysis applied across your project. * [What Loop can do](/docs/loop/capabilities) for the rest of Loop's trace analysis tools.