Tracer

This guide covers the most common tracing patterns: attaching a tracer, subscribing to live events, querying recorded history, and exporting in different formats. For complete signatures, see the Tracer reference and TraceEvent reference.

Plexis includes a built-in tracing system for observing execution flow, debugging state machine logic, and capturing structured execution history.

Creating a Tracer

import { createTracer } from '@tde.io/plexis';

const tracer = createTracer({
  enabled: true,
  captureContext: 'after',
});

See TracerOptions for all available options.

Attaching a Tracer to a Domain or Pipeline

Pass the tracer in the options object when defining a domain or pipeline:

import {
  defineDomain, definePipeline,
  when, on, node, target, terminal,
  createTracer,
} from '@tde.io/plexis';

const tracer = createTracer();

const order = defineDomain('order', () => {
  when('pending', () => {
    on('submit', target('processing'));
  });
  when('processing', terminal());
  return { context: {}, initial: 'pending' } as const;
}, { tracer });

const payment = definePipeline('payment', () => {
  node('validate', terminal());
  return { initial: 'validate' };
}, { tracer });

Both domain and pipeline write events to the same tracer instance.

Trace Levels

Each event has a level identifying which subsystem emitted it:

Level	Emitted by
'domain'	follow() start/end
'phase'	Phase entry and exit
'edge'	Domain event traversal
'pipeline'	Pipeline run() start/end
'pipeline-node'	Individual node execution
'fork'	Fork condition evaluation and selection
'action'	Edge or node action execution
'guard'	Guard evaluation
'condition'	Fork condition evaluation detail

Subscribing to Events

Subscribe to live trace events as they are recorded:

const unsub = tracer.subscribe((event) => {
  console.log(`[${event.level}] ${event.type} — ${event.status}`);
});

await order.follow('submit');

unsub(); // stop listening

Querying History

// All recorded events
const events = tracer.history();

// All trace IDs (one per top-level domain.follow() or pipeline.run() call)
const ids = tracer.traces();

// Events for a specific trace
const traceEvents = tracer.byTraceId(ids[0]);

Exporting Traces

// JSON — structured array of TraceEvent objects
const json = tracer.export('json');

// Text — human-readable flat list
const text = tracer.export('text');

// Tree — nested tree grouped by trace and parent IDs
const tree = tracer.export('tree');

TraceEvent Fields

See TraceEvent for the complete field reference.

Clearing History

tracer.clear();

Removes all recorded events from memory. Does not affect active subscribers.