Recording-Tracer

RecordingTracer ist das Test-Pendant zu otelTracer. Anstatt Spans zu exportieren, speichert er sie im Speicher — Tests asserten auf die aufgezeichneten Spans.

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

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

// ... Actor ausführen ...
ref.tell({ kind: 'process' });
await probe.expectMessage(...);

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

Was er aufzeichnet

Jeder 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>;
};

Du siehst, welche Attribute gesetzt wurden, wann der Span gestartet + beendet wurde, seine Art, seinen Parent (zum Verifizieren von Kausalitätsketten) und seinen Endstatus.

Die API

class RecordingTracer implements Tracer {
  // ... volles Tracer-Interface ...

  recorded(): ReadonlyArray<RecordedSpan>;  // Schnappschuss jedes beendeten Spans
  reset(): void;                            // aufgezeichneten Zustand leeren
}

recorded gibt einen Schnappschuss jedes Spans zurück, der beendet wurde — ein Span wird erst bei end() erfasst, sodass einer, der gestartet, aber nie beendet wurde, nie auftaucht.

Übliche Assertion-Muster

„Hat das Framework die Nachricht dieses Actors auto-gespan’d?”

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');

„Hat mein Custom-Span mit den richtigen Attributen gefeuert?”

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);

„Haben sich die Spans korrekt verkettet?”

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);

Nützlich zum Verifizieren der Trace-Kausalität — Parent- Kontext korrekt an Child-Spans propagiert.

Zwischen Tests zurücksetzen

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

Ohne Reset akkumulieren aufgezeichnete Spans über Tests hinweg. Reset bei jedem Test, um Assertions nur auf die Spans des aktuellen Tests zu halten.

Performance

Aufzeichnen ist billig — Anhängen an ein Array. Aber Spans akkumulieren im Speicher. Bei langen Test-Läufen periodisch reset, um Speicher-Wachstum zu vermeiden.

Wann NICHT nutzen

// RecordingTracer serialisiert Kontext nicht wirklich Cross-Wire

In Single-Process-MultiNodeSpec-Tests funktioniert der Recording-Tracer — jeder Node teilt sich denselben Prozess. Für Cross-Process-/Cross-Node-Tracing-Tests bräuchtest du eine echte OTel-Pipeline.

Wo es weitergeht

Tracer-API — das Interface, das dies implementiert.
OTel-Adapter — die Produktions-Alternative.
Actor-Tracing — was das Framework auto-span’d, beobachtbar via diesen Tracer.
TestKit — kombiniere mit dem Recording-Tracer für assertions-freundliche Tests.

Die RecordingTracer-API- Referenz deckt die volle Oberfläche ab.