Trace Autopsy
A local analyzer for structural failures in recorded agent runs.
A failed agent run can contain thousands of events. The final error tells you where execution stopped, but may not explain why.
I built Trace Autopsy to find failure patterns in recorded traces and attach each finding to the events that support it.
- TraceRecorded events
- NormalizeShared event format
- DetectFailure patterns
- ReportFindings + evidence
One event format keeps the checks independent
The parsers accept LangGraph, LangChain, OpenTelemetry, and generic JSON. Each parser converts its input into the same event format.
The detectors inspect that format for repeated calls, cascading errors, unknown tools, and other structural failures. Adding a trace format does not require rewriting each detector.
Analysis runs locally without a language model. The command-line interface, Streamlit interface, and Model Context Protocol server share the analysis code.
Repeated calls explain the example failure
In the documented example, the agent plans once, then calls health_check eight times. Each call uses the same arguments and returns a connection-refused error.
The retry policy eventually aborts the run. The useful finding is the repeated call pattern, rather than the final abort message.
The repository includes a failed loop and a corrected example. Comparing their traces shows whether a change removed the repeated behavior.
Exit codes make findings usable in CI
The command-line interface returns 0 for a clean run, 1 when it finds a problem, and 2 for a parse or tool error.
A continuous integration job can use those codes to reject an agent regression. A separate diff command compares findings across runs.
Structural checks cannot explain every failure
A run can look structurally correct and still produce a wrong answer. These detectors cannot establish whether an answer is true.
The goal-drift check uses word overlap as a proxy for intent. Thresholds also need review for the domain being tested.
Trace Autopsy analyzes traces that already exist. The application must record the events, and analysis does not stop a live run.