tracesage¶

Production observability for LangChain & LangGraph multi-agent systems. Drop in two lines, see live execution traces in your browser.

from tracesage import TraceSage

tracer = await TraceSage.create()                          # one-time setup

result = await graph.ainvoke(
    {"input": payload},
    config={"callbacks": [tracer.handler]},                # only line you add
)

# Open http://localhost:7842/ui to see the trace live

Get started in 5 minutes → Browse the examples →

Why tracesage¶

LangChain agents emit a rich callback stream — chain start/end, tool start/end, LLM start/end, retrieval, errors. tracesage captures all of it without changing your workflow logic, persists it locally (SQLite + gzipped blobs), and renders it in an interactive graph + timeline UI in real time.

Zero infrastructure. No Docker. No Postgres. No external services. pip install.
Two-line integration. One callback added to your existing ainvoke.
Production-grade safety. The handler never raises. The tracer never crashes your pipeline.
Interactive graph view. Custom SVG graph (no framework), auto-laid-out. Hover, click, replay any run.
MCP-aware. Tools loaded from MCP servers are attributed by source — see which tools came from which server vs. which are hardcoded. See MCP support.
Pluggable storage. SQLite today; Postgres / remote-collector / object-store backends planned.
MIT licensed. Free forever.

Where to go next¶

Quickstart

Install, run an example, open the UI. Five minutes.
Concepts

What agent, tool, llm, retriever, chain, and mcp mean — read this first if you want to interpret a topology.
Configuration

Every TRACESAGE_* env var explained.
Production

Auth, sampling, retention, monitoring, multi-tenant deployments.
Examples

30 before/after apps across popular use cases. Pick the closest match to your architecture and copy the integration.
CLI reference

tracesage serve / export / stats / runs / gc.
Extending

Adding framework adapters and storage backends.

What you'll see¶

tracesage topology graph

Once a run lands, the UI shows:

Run list — every run with status, tags, started-at, total steps, total tokens
Topology graph — agent / tool / chain / retriever relationships across runs
Timeline — chronological steps with click-to-expand full payloads
Replay — animate any completed run at 1x / 2x / 5x

Keyboard: j / k next/prev run, / focus search, t theme, Esc close, ? help.

Watch a trace stream in¶

Inspect any node¶

Click a node to open its drawer — counts, durations, errors, the tools it provides or uses, and (for MCP) its server of origin.


“Tools by source” — tools grouped by origin (MCP vs. local).	MCP server inspector — provided tools, invocations and callers.

Status¶

v0.1 — alpha. API may still shift before v1.0. Production-monitoring-ready for single-Python-process deployments; centralized multi-process / remote-collector mode is on the roadmap. See the changelog for release notes.