TraceRoot: an open-source observability layer that turns production agent failures into fix PRs

The problem TraceRoot targets: traces you never read

Agent systems emit more telemetry than a team can review. TraceRoot's README states the case bluntly: traces alone do not scale, and manually sifting through every trace is unsustainable. The project's answer is not better filtering in a dashboard. It is a detector that screens incoming traces for hallucinations, tool failures, logic errors and safety violations, surfaces findings, and auto-triggers root cause analysis with email and Slack alerts. The intended user is a team already running agents in production, with Python or TypeScript instrumentation in place, that has hit the point where a failure report arrives before anyone knows which line caused it. TraceRoot is not a general APM product with an LLM tab bolted on. The unit of work is a failing agent trace, and the output is a diagnosis plus a pull request.

How the loop works: detectors, a code sandbox, and a fix PR

The architecture visible in the README has four moving parts. Tracing captures LLM calls, agent actions and tool usage through an OpenTelemetry-compatible SDK, so the ingestion path is OTLP rather than a proprietary agent protocol. Detectors run an LLM-as-judge evaluator over incoming traces and classify failures into hallucination, tool or logic failure, safety violation and intent drift. When a detector fires, agentic debugging takes over: an AI connects to a sandbox holding your production source code, identifies the failing line, and correlates that failure with GitHub commits, pull requests and open issues. The fourth part closes the loop. Confirmed findings become golden datasets, and offline evals run from the TraceRoot CLI or SDK inside coding agents such as Claude Code, Codex and Cursor, verifying each fix against those datasets. The data flow is therefore trace in, judgement, code-level root cause, PR out, eval against a frozen dataset. The interesting design decision is the sandbox: root cause analysis is grounded in a checkout of your code, not in the trace alone. That is what separates a plausible-sounding explanation from one that names a line.

Getting it running: make dev, make prod, or Terraform

The README gives three self-hosting paths. Developer mode clones the repository and runs make dev, which the README describes as hosting the infrastructure in Docker and the application itself locally; it points to CONTRIBUTING.md for detail. Local docker mode runs make prod after the same clone, hosting everything in Docker. The third path is the deploy/ directory, which runs TraceRoot on Kubernetes with Helm and Terraform for production hosting, and the README states plainly that this is still in an experimental stage. TraceRoot Cloud is offered as the fastest route, with storage and LLM tokens for testing and no credit card. Instrumentation comes from the traceroot-py and traceroot-ts SDKs, and framework integrations include LangChain and LangGraph, LlamaIndex, CrewAI, AutoGen, Agno, DSPy, Google ADK, Claude Agent SDK, Microsoft Agent Framework and Mastra. For LangChain the README says instrumentation works by passing a callback handler; for Mastra it is the TraceRoot OTLP exporter. Model access is bring-your-own-key, with OpenAI, Anthropic, Gemini, xAI, DeepSeek, OpenRouter, Kimi and GLM named as supported providers. Note that the README does not print the SDK install commands or the environment variable names for the API key and endpoint. Those live in the linked docs, so plan on a docs pass before your first trace lands.

Where the design costs you: sandbox access, judge quality, and eval drift

Three constraints follow directly from the described design. First, agentic debugging needs a sandbox with your production source code plus GitHub history. That is a meaningful access grant, and it is the opposite of a read-only telemetry collector. Teams with strict code egress rules will find the headline feature is the one they cannot switch on. Second, the detectors are an LLM-as-judge. Judgement quality is bounded by the judge model you bring and by the prompt behind each failure category, and the README does not describe how those prompts are tuned or how false positives are suppressed. A detector that fires on intent drift will produce findings you disagree with, and the README does not say what happens to a dismissed finding. Third, the eval loop only verifies what is in the dataset. Confirmed failures become golden datasets, which means the loop is biased toward failures you have already seen and confirmed. A fix that regresses an untested path will pass. TraceRoot is the wrong tool if you want a passive trace store with a query language, or if your agents run in an environment where source code cannot leave the perimeter.

How it differs from LangSmith and from a plain OpenTelemetry backend

The natural comparison is LangSmith, which also ingests agent traces and offers evaluation. The difference is where the loop stops. LangSmith's centre of gravity is the hosted trace and eval workspace: you inspect runs, build datasets and run evaluators, and the fix happens in your editor. TraceRoot pushes past the workspace boundary. Its agentic debugger opens a sandbox with your source, correlates the failure with GitHub commits and issues, and the README states it opens a PR to fix the failure. The second comparison is a plain OpenTelemetry backend, for example a collector writing to object storage. That gives you spans and nothing else: no judgement, no root cause, no dataset. TraceRoot is OpenTelemetry-compatible on ingestion, so it is not an either-or at the SDK level, but the value sits in the layers above the span. If you already run a LangSmith or OTLP pipeline and you are happy reading traces yourself, TraceRoot's addition is the automated triage and the PR, not the storage.

Maintenance, releases, and the licence question

The release cadence visible in the repository is fast: v0.4.0 on 16 August 2026, v0.3.9 four days earlier, v0.3.8 at the end of July, with the last push to main on 10 September 2026. Pre-1.0 with that cadence means you should expect breaking changes between minor versions and pin your SDK and server versions together. The self-hosting surface is broad: a Docker Compose path for local use, a Kubernetes path with Helm and Terraform that the README calls experimental, and a cloud option. That is three deployment stories to keep current, and the experimental label on the Terraform path is the one to take literally. On licensing, GitHub reports NOASSERTION, which means the repository's licence could not be matched to a standard identifier automatically. The README badge links to a licence file, but the identifier is not stated in the material available here. Do not assume Apache-2.0 or MIT. Read the licence file and the terms attached to any hosted component before you ship TraceRoot inside a commercial product, and if the terms matter to your legal team, treat that reading as a prerequisite rather than a formality. Nothing here is legal advice.

Editorial conclusion

Adopt TraceRoot if you already run agents in production with Python or TypeScript SDKs and you want failure triage tied to source code and GitHub history rather than a dashboard you read by hand. Do not adopt it if you need a signed-off enterprise licence today, or if you only want raw trace storage: the licence is NOASSERTION on GitHub, so read the actual licence file before you build on it. Verify first that make prod brings the whole stack up on your machine, that your model provider is covered by BYOK, and that the Terraform deployment under deploy/ is past its experimental stage for your environment.

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. traceroot-ai/traceroot on GitHub