Detect structural failures automatically. Alert before your users do.

AI agents fail in ways that traditional monitoring can't see.

Your API returns 200. Your logs show no exceptions. But the agent called the same tool 12 times in a row, burned $X in tokens, and gave the user a wrong answer or no answer at all.

LangSmith/Langfuse answer "what happened?" after you already know something broke. Dunetrace answers a different question: "is something breaking right now?" and if you're already running Langfuse, it can pull your trace context to explain why and suggest a fix to the root cause.

It watches the structural pattern of every run and fires a Slack alert within 15 seconds of completion.

git clone https://github.com/dunetrace/dunetrace
cd dunetrace && cp .env.example .env && docker compose build && docker compose up -d

pip install dunetrace                              # any framework
pip install 'dunetrace[langchain]'                # LangChain / LangGraph
pip install 'dunetrace[langchain,langfuse]'       # + Langfuse deep analysis

from dunetrace import Dunetrace

dt = Dunetrace()               # no api_key needed for local dev
dt.init(agent_id="my-agent")  # patches openai, anthropic, httpx, requests globally

@dt.agent()
def run_agent(query: str) -> str:
    ...                        # LLM + HTTP calls tracked automatically

To verify signals fire end-to-end, run the examples with built-in failure scenarios:

cd packages/sdk-py

python examples/basic_agent.py # No LLM calls

SCENARIO=tool_loop python examples/langchain_agent.py  # TOOL_LOOP via LangChain callback

SCENARIO=failures python examples/decorator_agent.py   # TOOL_LOOP, RETRY_STORM, RAG_EMPTY_RETRIEVAL

SCENARIO=tool_loop python examples/langfuse_agent.py   # TOOL_LOOP + Langfuse explain

Then open the dashboard: http://localhost:3000

15 structural detectors run automatically on every completed run i.e. tool loops, retry storms, context bloat, reasoning stalls, goal abandonment, prompt injection, and more. Each signal includes a plain-English explanation and a suggested fix. Alerts include rate context: whether this is a first occurrence, recurring pattern, or systemic issue affecting ≥10% of runs.

If you are running Langfuse alongside Dunetrace, click Explain + on any signal in the dashboard. Dunetrace fetches the full trace, extracts the system prompt in use, and asks an LLM for the specific root cause and fix. For behavioral failures (tool loops, goal abandonment, etc.) it also offers one-click Apply via Langfuse to create a new prompt version. Fix effectiveness is tracked automatically i.e. the dashboard shows whether recurrence dropped after the fix was applied.

→ docs/detectors.md: full detector reference, thresholds, shadow mode

Live dashboard at http://localhost:3000. Auto-refreshes every 15s.

→ docs/dashboard.md

No raw content ever leaves your agent process. Every prompt, tool argument, and model output is SHA-256 hashed before transmission.

→ docs/architecture.md

Slack and generic webhook (PagerDuty, Linear, custom).

→ docs/alerts.md

• Custom Python agent - decorator, middleware, manual
• LangChain / LangGraph
• Langfuse - connect traces for deep root-cause analysis and one-click autofix
• FastAPI / Flask / ASGI / WSGI / OpenTelemetry / Loki

Agent Code
  └─► Dunetrace SDK        (hashes content → ingest events + OTel spans)
        └─► Ingest API      (POST /v1/ingest → Postgres)
                ├─► Detector       (poll → RunState → 15 detectors → signals)
                ├─► Alerts         (poll → explain → Slack / webhook)
                └─► Customer API   (runs, signals, explanations → dashboard)
        ├─► stdout NDJSON   (emit_as_json=True → Loki / Grafana Alloy)
        └─► OTel exporter   (otel_exporter=… → Tempo / Honeycomb / Datadog)

→ docs/architecture.md

# SDK + services (no Docker required)
PYTHONPATH=packages/sdk-py:services/explainer:services/alerts:services/detector \
  python -m pytest packages/sdk-py/tests/ services/explainer/tests/ \
    services/detector/tests/ services/alerts/tests/ -q

• Python 3.11+
• Docker + Docker Compose
• PostgreSQL 16+ (included in Docker Compose)

1. Fork the repo and create a branch
2. Make your changes and add tests
3. Run the test suite
4. Open a pull request with a clear description of what and why

For larger changes (new detectors, architecture changes), open an issue first.

If Dunetrace looks useful, a GitHub star helps others find the project.

dunetrace@gmail.com

Apache 2.0