> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m4trix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

`@m4trix/tracing` records LangGraph and LangChain-style callback runs into a portable trace store. Pair it with `@m4trix/trace-viewer` to inspect traces locally in a browser.

Use it when you want to:

* Debug nested agent, chain, model, tool, and retriever calls
* Keep model inputs and outputs available after a run finishes
* Attach run metadata such as project, environment, tenant, or experiment labels
* Build a custom trace backend behind the same storage interfaces
* View local filesystem traces without wiring up hosted observability first

## Core Model

Tracing is made of four pieces:

1. **Tracer** implements callback handlers and turns start/end/error events into trace runs.
2. **TraceStore** persists trace structure separately from larger JSON payloads.
3. **Adapters** decide where trace metadata and payloads are stored.
4. **TraceViewerApi** reads stored traces and returns list, tree, and payload data for a UI.

```ts theme={"dark"}
import {
  FsPayloadStoreAdapter,
  FsStructureStoreAdapter,
  TraceStore,
  Tracer,
  toLangGraph,
} from '@m4trix/tracing';

const traceStore = TraceStore.of({
  structureStoreAdapter: new FsStructureStoreAdapter({ path: './tmp/traces' }),
  payloadStoreAdapter: new FsPayloadStoreAdapter({ path: './tmp/traces' }),
});

const tracer = Tracer.from(traceStore);
const lgTracer = tracer.adapt(toLangGraph);

await graph.invoke(input, {
  callbacks: [lgTracer],
  metadata: {
    projectId: 'support-agent',
    env: 'dev',
  },
});

await lgTracer.flush();
```

## Package Exports

Import tracing primitives from `@m4trix/tracing`:

* `Tracer`
* `TracerAdapter`, `toLangGraph`, `LangGraphTracer` (LangGraph callback surface)
* `TraceStore`
* `TraceViewerApi`
* `FsStructureStoreAdapter`, `FsPayloadStoreAdapter`
* `Trace`, `TraceRun`, `TraceRunNode`
* `TraceStatus`, `TraceRunType`, `TraceTokens`, `TraceMetadata`
* `StructureStoreAdapter`, `PayloadStoreAdapter`, `ListTracesQuery`

Import viewer helpers from `@m4trix/trace-viewer`:

* `createFsTraceViewerApi`
* `startTraceViewerServer`
* `appRouter`, `AppRouter`, `TraceViewerContext`
* `parseCliArgs`, `cliHelpText`

## Example Project

The repository includes a LangGraph example at `examples/tracing-example`. It writes filesystem traces to `tmp/tracing-example` and can be inspected with the trace viewer:

```bash theme={"dark"}
pnpm --filter @examples/tracing-example example
pnpm exec m4trix-trace-viewer --adapter fs --path ./tmp/tracing-example --port 4319
```