Open-source agent tracing

Trace your agents. No cloud needed.

Open-source tracing for LangGraph and LangChain. Traces stay in your files or your AWS account, with a viewer you run.

Get started
The m4trix trace viewer showing a LangGraph run tree with a selected tool call, its metadata, input and output payloads.

Fits the stack you already run

  • LangGraph
  • LangChain
  • Model Context Protocol
  • Claude
  • Cursor
  • Docker
  • Kubernetes

From callback to run tree in one file

The tracer speaks the LangChain callback API, so adding it is a config change, not a rewrite.

  1. 1

    Install the package

    The root entry has no runtime dependencies.

  2. 2

    Pass the tracer as a callback

    Every chain, model, tool and retriever call lands in ./.traces. Your graph code stays as it is.

  3. 3

    Open the viewer

    One command serves the run tree, payloads and annotations on localhost.

terminalbash
pnpm add @m4trix/tracing
agent.tstypescript
import {  FsPayloadStoreAdapter,  FsStructureStoreAdapter,  TraceStore,  Tracer,  toLangGraph,} from '@m4trix/tracing';
const traceStore = TraceStore.of({  structureStoreAdapter: new FsStructureStoreAdapter({ path: './.traces' }),  payloadStoreAdapter: new FsPayloadStoreAdapter({ path: './.traces' }),});
const tracer = Tracer.from(traceStore).adapt(toLangGraph);
await graph.invoke(input, { callbacks: [tracer] });await tracer.flush();
terminalbash
npx m4trix-trace-viewer --adapter fs --path ./.traces

Read an agent run the way you read code

Small rows for lists and filters, full payloads when you open a run, and notes that stay with the trace.

Payloads that read like conversations

Profiles turn raw JSON into messages, tool calls and tables. A model drafts the mapping from samples of your traces, with your own key, straight from the browser.

The New AI profile dialog in the trace viewer, sampling the current trace and sending it to the Claude API with a key held in browser memory.

Plain files on disk

No sign-up, no API key, no upload queue. Grep it, commit a fixture, or mount it in Docker.

.traces/traces/
└─ f19bca0d…/
   ├─ trace.json
   ├─ runs.ndjson
   └─ payloads/

Split storage

Structure rows hold timing, status and tokens. Prompts and completions are blobs, fetched by ref only when you open a span.

Review in place

Annotate traces and single runs after the fact. Notes live next to the structure rows, not in another tool.

annotation: { review: 'approved' }

One store, both directions

The adapters that write a trace also serve it back through TraceViewerApi. No read replica, no sync lag.

Hand the trace to your coding agent

The viewer also runs as an MCP server. Claude Code, Cursor or any MCP client can search payloads, find the root cause of an error and diff two runs.

terminalbash
claude mcp add m4trix-traces -- \  npx m4trix-trace-viewer mcp --path "$PWD/.traces"

11 tools, read-only unless you approve a note

Find

  • list_traces
  • find_runs
  • search_payloads
  • load_trace_payloads

Inspect

  • get_trace
  • get_run
  • get_payload
  • get_conversation

Diagnose

  • analyze_trace
  • compare
  • annotate

analyze_trace flags error roots, unfinished runs, the critical path, token hotspots and loops in one call.

Start on a laptop. Ship to AWS when you need to.

Same Tracer, same viewer at every stage. Only the adapters change.

  1. On your laptop

    Filesystem adapters write to ./.traces. Open them with the viewer CLI.

    --adapter fs --path ./.traces

  2. In your cluster

    The app writes to a shared volume. A sidecar ships it, so the app needs no AWS credentials.

    m4trix-tracing-sidecar --root /traces

  3. In your AWS account

    Structure goes to DynamoDB, payloads to S3. The same viewer reads it back.

    --adapter aws-stack

Six primitives. That is the whole API.

Swap any adapter without touching the tracer or the viewer.

Drop-in LangGraph and LangChain callbacks

Tracer.from(traceStore) implements the callback surface LangGraph expects. Pass tracer.adapt(toLangGraph) to callbacks. Every chain, LLM, tool, and retriever span lands in your store without rewriting agent code.
  • Handles chain, LLM, chat model, tool, and retriever events
  • Batches pending runs on flush for efficient writes
  • Typed LangGraph adapter via toLangGraph
agent.tstypescript
import { Tracer, toLangGraph } from '@m4trix/tracing';
const tracer = Tracer.from(traceStore);const lgTracer = tracer.adapt(toLangGraph);
await graph.invoke(input, { callbacks: [lgTracer] });await lgTracer.flush();

Questions

Does anything leave my machine?

Not by default. The filesystem adapters write to a folder you choose. Data only moves if you configure the S3 and DynamoDB adapters or run the sidecar. AI profiles call the model provider directly from your browser, with your key.

Do I have to use LangGraph?

No. The Tracer implements the LangChain callback methods without importing LangChain, so anything that emits those callbacks works. LangGraph gets a typed adapter through toLangGraph.

How is this different from LangSmith or Langfuse?

Those are platforms: a hosted service, or a database and web app you operate. m4trix tracing is a library. Traces are files or rows in your own AWS account, and the viewer is a CLI you start when you need it.

Is it ready for production?

The sidecar pattern is built for it: the app writes locally and a companion container ships to S3 and DynamoDB. Sampling, PII redaction, viewer auth and retention policies are not included yet.

What does it cost?

Nothing. It is MIT licensed with no seats or usage tiers. You pay only for the storage you choose to use.

Part of the m4trix toolkit

Each package works on its own. Together they share one TypeScript model.

Add tracing before your next run

One callback, one folder, one command to open it.

Get startedStar on GitHub