Recording tracer

RecordingTracer is the test counterpart to otelTracer. Instead of exporting spans, it stores them in memory — tests assert on the recorded spans.

import { TestKit, RecordingTracer, TracingExtensionId } from 'actor-ts';

const tracer = new RecordingTracer();
const tk = TestKit.create();
tk.system.extension(TracingExtensionId).enable(tracer);

// ... run the actor ...
ref.tell({ kind: 'process' });
await probe.expectMessage(...);

// Assert on recorded spans:
const spans = tracer.recorded();
expect(spans).toHaveLength(1);
expect(spans[0].name).toBe('actor.receive');
expect(spans[0].attributes['actor.path']).toContain('worker');

What it records

Each RecordedSpan:

type RecordedSpan = {
  name:           string;
  kind:           SpanKind;
  context:        SpanContext;
  parent:         SpanContext | null;
  startTimeMs:    number;
  endTimeMs:      number;
  attributes:     Record<string, AttributeValue>;
  status:         SpanStatus;              // 'unset' | 'ok' | 'error'
  statusMessage?: string;
  exceptions:     ReadonlyArray<Error>;
};

You see what attributes were set, when the span started + ended, its kind, its parent (for verifying causality chains), and its final status.

The API

class RecordingTracer implements Tracer {
  // ... full Tracer interface ...

  recorded(): ReadonlyArray<RecordedSpan>;  // snapshot of every ended span
  reset(): void;                            // clear recorded state
}

recorded returns a snapshot of every span that ended — a span is captured only when end() is called, so one that was started but never ended never shows up.

Common assertion patterns

”Did the framework auto-span this actor’s message?"

ref.tell({ kind: 'work' });
await probe.expectMessage(...);

const spans = tracer.recorded();
const receive = spans.find(s => s.name === 'actor.receive' && s.attributes['actor.path']?.includes('worker'));
expect(receive).toBeDefined();
expect(receive!.status).toBe('ok');

"Did my custom span fire with the right attributes?"

const orderSpan = tracer.recorded().find(s => s.name === 'place-order');
expect(orderSpan).toBeDefined();
expect(orderSpan!.attributes['order.id']).toBe('o-1');
expect(orderSpan!.attributes['order.amount']).toBe(42);

"Did spans link up correctly?”

const spans = tracer.recorded();
const parent = spans.find(s => s.name === 'http-request');
const child  = spans.find(s => s.name === 'db-query');

expect(child!.parent?.traceId).toBe(parent!.context.traceId);

Useful for verifying trace causality — parent context correctly propagated to child spans.

Resetting between tests

beforeEach(() => tracer.reset());

Without reset, recorded spans accumulate across tests. Reset on each test to keep assertions on the current test’s spans only.

Performance

Recording is cheap — appending to an array. But spans accumulate in memory. For long test runs, periodically reset to avoid memory growth.

When NOT to use it

Production

// RecordingTracer keeps every span forever in memory

Memory grows unbounded. This is a test-only tracer. For production, use the OTel adapter.

Cross-cluster context

// RecordingTracer doesn't actually serialize context cross-wire

In single-process MultiNodeSpec tests, the recording tracer works — every node shares the same process. For cross-process / cross-node tracing tests, you’d need a real OTel pipeline.

Where to next

• Tracer API — the interface this implements.
• OTel adapter — the production alternative.
• Actor tracing — what the framework auto-spans, observable via this tracer.
• TestKit — pair with the recording tracer for assertion-friendly tests.

The RecordingTracer API reference covers the full surface.