Skip to main content

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.

Tracing stores a tree of callback runs. A top-level run becomes a trace, and child callbacks become nested runs under the same traceId.

​
Traces and Runs

A Trace is the summary record shown in trace lists:
  • traceId and rootRunId
  • name, status, startTime, optional endTime, and latencyMs
  • optional projectId, metadata, token totals, and cost
  • runCount
A TraceRun is one node in the trace tree:
  • runId, traceId, and optional parentRunId
  • type, name, status, and timing fields
  • optional inputRef, outputRef, eventsRef, tokens, error, metadata, and extra
The tracer derives the traceId from the root run. Child runs keep their own runId and point back to their parent with parentRunId.

​
Run Types

Built-in run types include:
  • agent
  • chain
  • llm
  • chat_model
  • tool
  • retriever
  • embedding
  • prompt
  • parser
The type is inferred from callback handlers where possible. Chain callbacks can also pass a supported run type as the callback runTypeOrName; otherwise they are stored as chain runs.

​
Payload References

Trace structure stays small. Inputs and outputs are written through the payload adapter, and runs store references to those payloads: 
{
  runId: 'tool-run-1',
  inputRef: 'traces/trace-1/payloads/tool-run-1/input.json',
  outputRef: 'traces/trace-1/payloads/tool-run-1/output.json',
}
The viewer uses those references to lazy-load payloads only when a run is selected.

​
Metadata and Project IDs

Callback metadata is copied onto trace records when values are strings, numbers, or booleans. projectId is treated specially: it becomes the trace-level projectId and is excluded from the generic metadata object. 
await graph.invoke(input, {
  callbacks: [tracer],
  metadata: {
    projectId: 'checkout-agent',
    env: 'staging',
    tenant: 'acme',
  },
});
Use projectId when you want viewer or API queries to filter traces by application, workflow, tenant, or experiment family.

​
Status and Errors

Runs start as running and finish as success or error. Error runs store the error message and error type: 
{
  status: 'error',
  error: {
    message: 'Model request failed',
    type: 'TimeoutError',
  },
}
A trace is marked error when any run in its tree has errored.

​
Flushing

Callback handlers write asynchronously. Tracer.flush() waits for pending callback work, batches pending run updates, and upserts pending trace summaries. Call flush() when:
  • a script is about to exit
  • a test expects traces to be available immediately
  • you are about to open the trace viewer after a short local run
Long-running servers can flush at request boundaries, job boundaries, or shutdown hooks.

​
Storage Adapters

TraceStore separates structure from payloads: 
TraceStore.of({
  structureStoreAdapter,
  payloadStoreAdapter,
});
The structure adapter stores Trace and TraceRun records and handles list/query operations. The payload adapter stores JSON payloads and optional streams. The package includes filesystem adapters for local development. Implement StructureStoreAdapter and PayloadStoreAdapter when you want to store traces in a database, object store, or hosted observability backend.