> ## 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.

# Quick Start

Install the packages:

```bash theme={"dark"}
pnpm add @m4trix/tracing @m4trix/trace-viewer
```

Create a filesystem-backed trace store:

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

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

  return Tracer.from(traceStore);
}
```

## Attach the Tracer

Pass the tracer through LangGraph or LangChain callback options:

```ts theme={"dark"}
import { createTracer } from './tracing';
import { toLangGraph } from '@m4trix/tracing';

const tracer = createTracer('./tmp/traces');
const lgTracer = tracer.adapt(toLangGraph);

await graph.invoke(
  { messages: [{ role: 'user', content: 'Summarize this ticket.' }] },
  {
    callbacks: [lgTracer],
    metadata: {
      projectId: 'support-agent',
      env: 'dev',
    },
  },
);

await lgTracer.flush();
```

`flush()` waits for in-flight callback writes, batches pending runs, and writes the final trace snapshots. Call it before your script exits or before you expect the trace viewer to show the latest run.

## Run the Viewer

Start the local viewer against the same trace root:

```bash theme={"dark"}
pnpm exec m4trix-trace-viewer --adapter fs --path ./tmp/traces --port 4319
```

Open `http://127.0.0.1:4319`.

The viewer lists traces, shows the run tree, and lazy-loads input/output payloads when you select a run.

## Try the Repository Example

From the repository root:

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

The example builds a mock LangGraph workflow with planner, researcher, lookup, summarizer, and reviewer nodes so the viewer has a nested trace tree to inspect.