traceparent.ts · Source

traceparent.tspackages/observability/src/traceparent.tsraw ← src7,314 B← Back to the app
1/**
2 * @factory/observability — W3C `traceparent` capture/resume (TASK-0135).
3 *
4 * The API→worker propagation primitive: the dispatcher stores the active
5 * `traceparent` in the BullMQ job METADATA; the processor resumes the span
6 * under it, so a job's trace continues the request that enqueued it (one
7 * trace across api → queue → worker — the spec's "job metadata carries the
8 * W3C traceparent — the dispatcher stores it, the processor resumes the
9 * span").
10 *
11 * The module is `@opentelemetry/api`-only (NO SDK dependency): it ships a
12 * minimal, spec-complete W3C trace-context propagator (version `00`, 32-hex
13 * trace-id, 16-hex span-id, 2-hex flags) that `initOtel` registers on the
14 * global propagation API. That makes capture/resume behave identically in a
15 * full SDK process and in a bare one (dev/tests, OTEL disabled — the
16 * no-op contract: `captureTraceparent()` returns `undefined`,
17 * `resumeTraceparent()` runs the callback ambient).
18 */
19import {
20  context,
21  propagation,
22  trace,
23  type Context,
24  type SpanContext,
25  type TextMapGetter,
26  type TextMapPropagator,
27  type TextMapSetter
28} from "@opentelemetry/api";
29 
30export const TRACE_HEADER = "traceparent";
31export const TRACESTATE_HEADER = "tracestate";
32 
33const HEADER_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
34 
35const INVALID_TRACE_ID = "00000000000000000000000000000000";
36const INVALID_SPAN_ID = "0000000000000000";
37 
38/** Parse a W3C `traceparent` header into its parts (or null when invalid). */
39export function parseTraceparent(tp: string): { traceId: string; spanId: string; flags: number } | null {
40  const m = HEADER_RE.exec(tp.trim());
41  if (!m) return null;
42  const traceId = m[1]!;
43  const spanId = m[2]!;
44  if (traceId === INVALID_TRACE_ID || spanId === INVALID_SPAN_ID) return null;
45  return { traceId, spanId, flags: Number.parseInt(m[3]!, 16) };
46}
47 
48/** Build a `traceparent` string from raw parts (tests / dispatcher fallback). */
49export function buildTraceparent(traceId: string, spanId: string, sampled = true): string {
50  return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
51}
52 
53/**
54 * The minimal W3C trace-context propagator (spec 00). `inject` writes
55 * `traceparent` from the active span context; `extract` parses it back into
56 * a REMOTE span context. Invalid / all-zero ids are ignored (no context is
57 * produced) — the spec's "invalid value" rule.
58 *
59 * (Self-contained by design: `@opentelemetry/core`'s propagator pulls a
60 * whole extra dependency tree, and ours has to behave identically when the
61 * SDK is NOT loaded — the no-op contract.)
62 */
63export class W3CTraceContextPropagator implements TextMapPropagator {
64  fields(): string[] {
65    return [TRACE_HEADER];
66  }
67 
68  inject(ctx: Context, carrier: Record<string, string>, _setter?: TextMapSetter<Record<string, string>>): void {
69    const sc = trace.getSpanContext(ctx);
70    if (!sc || !trace.isSpanContextValid(sc)) return;
71    carrier[TRACE_HEADER] = `00-${sc.traceId}-${sc.spanId}-${sc.traceFlags.toString(16).padStart(2, "0")}`;
72  }
73 
74  extract(
75    ctx: Context,
76    carrier: Record<string, string | string[] | undefined>,
77    _getter?: TextMapGetter<Record<string, string | string[] | undefined>>
78  ): Context {
79    const raw = headerGetter.get(carrier, TRACE_HEADER);
80    if (typeof raw !== "string") return ctx;
81    const parts = parseTraceparent(raw);
82    if (!parts) return ctx;
83    const sc: SpanContext = {
84      traceId: parts.traceId,
85      spanId: parts.spanId,
86      isRemote: true,
87      traceFlags: parts.flags
88    };
89    return trace.setSpanContext(ctx, sc);
90  }
91}
92 
93/** Reads a string-keyed carrier (single string values; joins arrays). */
94const headerGetter: TextMapGetter<Record<string, string | string[] | undefined>> = {
95  keys(carrier: Record<string, string | string[] | undefined>): string[] {
96    return Object.keys(carrier);
97  },
98  get(carrier: Record<string, string | string[] | undefined>, key: string): string | undefined {
99    const v = carrier[key];
100    return Array.isArray(v) ? v.join(",") : v;
101  }
102};
103 
104/**
105 * The singleton propagator this package uses (registered by `initOtel`).
106 * Typed with the OPTIONAL carrier helper params (the global API's
107 * `TextMapPropagator` marks them required) so call sites can use the
108 * 2-arg form — the package always injects/extracts via plain objects.
109 */
110export interface W3CPropagatorLike {
111  fields(): string[];
112  inject(ctx: Context, carrier: Record<string, string>, setter?: TextMapSetter<Record<string, string>>): void;
113  extract(
114    ctx: Context,
115    carrier: Record<string, string | string[] | undefined>,
116    getter?: TextMapGetter<Record<string, string | string[] | undefined>>
117  ): Context;
118}
119 
120export const traceparentPropagator: W3CPropagatorLike = new W3CTraceContextPropagator();
121 
122/**
123 * Make this package's propagator the global one (idempotent). `initOtel`
124 * calls it; a test can call it directly to exercise capture/resume without
125 * booting the SDK.
126 */
127export function registerTraceparentPropagator(): void {
128  propagation.setGlobalPropagator(traceparentPropagator);
129}
130 
131/**
132 * Capture the ACTIVE W3C traceparent (from whatever context is currently
133 * active). Returns `undefined` when there is no active span or no propagator
134 * is registered (dev, tests, OTEL disabled) — store that as "no trace to
135 * resume".
136 */
137export function captureTraceparent(ctx: Context = context.active()): string | undefined {
138  const carrier: Record<string, string> = {};
139  propagation.inject(ctx, carrier);
140  return carrier[TRACE_HEADER];
141}
142 
143/**
144 * Run `fn` with the parent context reconstructed from a stored
145 * `traceparent` (the worker-processor side). Missing/invalid header or no
146 * registered propagator (OTEL disabled) → runs `fn` in the ambient context
147 * (the no-op contract).
148 */
149export function resumeTraceparent<T>(tp: string | undefined, fn: (parent: Context) => T): T {
150  if (tp) {
151    const extracted = propagation.extract(context.active(), { [TRACE_HEADER]: tp });
152    if (extracted !== context.active()) {
153      return context.with(extracted, fn, undefined, extracted);
154    }
155  }
156  return fn(context.active());
157}
158 
159/**
160 * The shared BullMQ metadata carrier shape (what the API dispatcher stores
161 * + the worker processor reads). Lives here — not in a BullMQ-typed module —
162 * so both sides share ONE definition without importing BullMQ into this
163 * package.
164 */
165export interface TraceMetadata {
166  /** W3C traceparent of the enqueueing request (absent = untraced). */
167  traceparent?: string;
168}
169 
170/** Pull a VALID traceparent out of a loosely typed BullMQ job metadata map. */
171export function metadataTraceparent(metadata: Record<string, unknown> | null | undefined): string | undefined {
172  if (!metadata) return undefined;
173  const tp = metadata["traceparent"];
174  return typeof tp === "string" && parseTraceparent(tp) !== null ? tp : undefined;
175}
176 
177/**
178 * Validate a traceparent carried as a raw string — the worker-side read of
179 * BullMQ 5's `job.opts.telemetry.metadata` field (the API stores the
180 * traceparent there; see apps/api/src/common/trace-metadata.ts). Invalid or
181 * absent → undefined (the no-op contract).
182 */
183export function telemetryTraceparent(metadata: string | null | undefined): string | undefined {
184  return typeof metadata === "string" && parseTraceparent(metadata) !== null ? metadata : undefined;
185}
186