Debug a trace

A long agent trace can span dozens of LLM and tool calls, which makes reading it end to end impractical. Braintrust offers two 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.

​

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. 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 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.

​

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 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. 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 to navigate spans, timelines, and threads by hand.
• Review and act on patterns to see the same analysis applied across your project.
• What Loop can do for the rest of Loop’s trace analysis tools.