Trace Context Probe

Pre-export trace diagnostics

Catch the exact hop that dropped your trace.

A tiny Node.js test helper for proving context lineage across queues, callbacks, streams, timers, and framework edges—before misleading spans reach your backend.

npm i -D trace-context-probe
Try the five break tests Read the 60-second setup
  • No SDK internals
  • Zero runtime dependencies
  • No payload capture
Paper-cut diorama of a teal trace thread crossing layered async portals before a torn gap
The first torn edge is the useful one.

Executable proof

Five ways context disappears. Five exact answers.

This local simulation runs the same comparison engine as the npm package. Each fixture breaks a different boundary and checks whether the first reported name is exact.

Fixture suite async-loss.spec.ts
No probe run yet

Run the fixture suite to inspect each first broken boundary.

Observe, don’t interfere

One expectation. One observation. No patched internals.

  1. Mark the known-good span

    Capture only its public trace ID and span ID.

  2. Wrap the boundary

    The wrapper observes when the real callback runs. It never binds context for you.

  3. Export the first tear

    Get JSON for CI, DOT for tooling, or a standalone HTML graph for a bug report.

60-second setup

Put the proof beside the boundary.

The stable core accepts your own context reader. The optional adapter uses only OpenTelemetry’s public API.

See complete usage and CLI exits
worker.ts
import { createOpenTelemetryProbe } from
  'trace-context-probe/opentelemetry';

const probe = createOpenTelemetryProbe({
  name: 'checkout-worker'
});

const request = probe.mark('http.request');
queue.consume(probe.wrap(
  'queue.consume', { expect: request }, handler
));

const report = probe.report();
// report.firstBrokenBoundary?.name

Explicit compatibility

Small surface. Boring dependencies.

Use the core with any tracer, or add the optional public OpenTelemetry adapter. Exporters and vendors stay out of the diagnostic path.

Supported runtime and API versions
ComponentSupported
Node.js18 · 20 · 22 · 24
TypeScript5.2 and newer
OpenTelemetry API1.7–1.x (optional)
Package formatsESM · CommonJS · .d.ts

Vendor-neutral · MIT licensed

Fix the first break.
Trust everything after it.

npm i -D trace-context-probe