@mandujs/core 0.41.2 → 0.43.0

package/src/observability/tracing.ts

@@ -1,694 +1,694 @@
-/**
- * Phase 18.θ — OpenTelemetry-compatible request tracing.
- *
- * Hand-rolled W3C Trace Context + OTLP/HTTP encoder. Zero runtime
- * dependencies (AsyncLocalStorage comes from `node:async_hooks`, which
- * Bun ships natively).
- *
- * Public API:
- *   - {@link Tracer}          — factory for root + child spans
- *   - {@link Span}            — lifecycle + attribute API (`end`, `setAttribute`, `setStatus`)
- *   - {@link parseTraceparent} / {@link formatTraceparent} — W3C wire format
- *   - {@link getActiveSpan}   — AsyncLocalStorage accessor
- *   - {@link runWithSpan}     — bind a span to the async context of a callback
- *   - {@link injectTraceContext} — stamp `traceparent` on outgoing `Headers`
- *   - {@link ConsoleSpanExporter} / {@link OtlpHttpSpanExporter}
- *
- * Design:
- *
- *   1. Tracing is **off by default**. An explicit
- *      `{ enabled: true }` on the config (or `MANDU_OTEL_ENDPOINT` env)
- *      flips it on; otherwise `startSpan()` returns a no-op span and the
- *      hot path is branch-free.
- *
- *   2. Span ids / trace ids are generated via `crypto.getRandomValues`
- *      per the W3C Trace Context spec — 16 bytes for trace-id (hex 32
- *      chars), 8 bytes for span-id (hex 16 chars). The "all zero" case
- *      forbidden by the spec is retried (probability ≈ 2^-128).
- *
- *   3. Parent context comes from the incoming `traceparent` header.
- *      If missing / malformed, a new root trace-id is minted. On
- *      outgoing fetches, {@link injectTraceContext} re-emits the current
- *      context so downstream services see the same trace-id.
- *
- *   4. AsyncLocalStorage keeps the active span in scope across
- *      `await`s, timers, and nested callbacks — without threading an
- *      explicit `ctx` parameter through every function. Works in Bun
- *      1.1+ and Node ≥ 16.
- *
- *   5. OTLP/HTTP exporter serialises spans to the JSON encoding of the
- *      `ExportTraceServiceRequest` protobuf (OTLP v1). Honeycomb,
- *      Grafana Tempo, and the OTel Collector all accept this over HTTP
- *      with `Content-Type: application/json`.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-// ─── W3C Trace Context ──────────────────────────────────────────────────
-
-/**
- * Parsed W3C `traceparent` header. The spec defines exactly four dash-
- * separated fields; anything else yields `null`.
- *
- * @see https://www.w3.org/TR/trace-context/#traceparent-header
- */
-export interface TraceparentFields {
-  /** 2-hex-char version. Always `"00"` for v1. */
-  version: string;
-  /** 32-hex-char trace-id (128-bit). */
-  traceId: string;
-  /** 16-hex-char span-id (64-bit) of the *parent* span. */
-  parentId: string;
-  /** 2-hex-char flags byte. Bit 0 = sampled. */
-  flags: string;
-}
-
-const TRACEPARENT_REGEX =
-  /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
-
-/**
- * Parse a `traceparent` header. Returns `null` for any header that does
- * not match the v1 grammar, including the all-zero trace-id / span-id
- * cases forbidden by the spec.
- */
-export function parseTraceparent(value: string | null | undefined): TraceparentFields | null {
-  if (!value) return null;
-  const m = TRACEPARENT_REGEX.exec(value.trim());
-  if (!m) return null;
-  const [, version, traceId, parentId, flags] = m;
-  if (version === "ff") return null; // reserved
-  if (/^0+$/.test(traceId)) return null;
-  if (/^0+$/.test(parentId)) return null;
-  return { version, traceId, parentId, flags };
-}
-
-/**
- * Format a `traceparent` header for downstream propagation.
- *
- * `flags` defaults to `"01"` (sampled) so the entire trace survives
- * middle hops. Pass `"00"` to mark the span as un-sampled.
- */
-export function formatTraceparent(traceId: string, spanId: string, flags: string = "01"): string {
-  return `00-${traceId}-${spanId}-${flags}`;
-}
-
-// ─── ID generation ──────────────────────────────────────────────────────
-
-function randomHex(bytes: number): string {
-  const buf = new Uint8Array(bytes);
-  crypto.getRandomValues(buf);
-  let out = "";
-  for (let i = 0; i < buf.length; i++) {
-    out += buf[i].toString(16).padStart(2, "0");
-  }
-  return out;
-}
-
-/** Mint a fresh 128-bit W3C-compliant trace-id. Never all-zero. */
-export function newTraceId(): string {
-  for (;;) {
-    const id = randomHex(16);
-    if (!/^0+$/.test(id)) return id;
-  }
-}
-
-/** Mint a fresh 64-bit W3C-compliant span-id. Never all-zero. */
-export function newSpanId(): string {
-  for (;;) {
-    const id = randomHex(8);
-    if (!/^0+$/.test(id)) return id;
-  }
-}
-
-// ─── Span / Tracer ──────────────────────────────────────────────────────
-
-export type SpanStatus = "unset" | "ok" | "error";
-
-export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
-
-export interface SpanAttributes {
-  [key: string]: string | number | boolean | null | undefined;
-}
-
-export interface SpanOptions {
-  /** Optional span kind. Default: `"internal"`. Root spans use `"server"`. */
-  kind?: SpanKind;
-  /** Attributes set at span start. Additional attributes can be set via {@link Span.setAttribute}. */
-  attributes?: SpanAttributes;
-  /**
-   * Override the parent span-id. Default: the currently-active span
-   * (from AsyncLocalStorage). Use `null` to force a root span.
-   */
-  parent?: Span | null;
-}
-
-/**
- * A single span in the trace tree. Always lifecycle-matched with
- * exactly one {@link Span.end} call — the Tracer's exporter flushes
- * the span only after `end()` returns.
- */
-export interface Span {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly parentSpanId: string | undefined;
-  readonly name: string;
-  readonly kind: SpanKind;
-  readonly startTimeMs: number;
-  readonly attributes: SpanAttributes;
-  /** `-1` until {@link end} is called. */
-  readonly endTimeMs: number;
-  readonly status: SpanStatus;
-  readonly errorMessage: string | undefined;
-  /** `false` for the no-op tracer (feature disabled). */
-  readonly recording: boolean;
-
-  setAttribute(key: string, value: string | number | boolean | null | undefined): void;
-  setAttributes(attrs: SpanAttributes): void;
-  setStatus(status: "ok" | "error", errorMessage?: string): void;
-  end(): void;
-}
-
-/** Internal mutable state for a recording span. */
-class RecordingSpan implements Span {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly parentSpanId: string | undefined;
-  readonly name: string;
-  readonly kind: SpanKind;
-  readonly startTimeMs: number;
-  readonly attributes: SpanAttributes;
-  endTimeMs: number = -1;
-  status: SpanStatus = "unset";
-  errorMessage: string | undefined;
-  readonly recording = true;
-  private ended = false;
-
-  constructor(
-    private readonly tracer: Tracer,
-    opts: {
-      traceId: string;
-      spanId: string;
-      parentSpanId: string | undefined;
-      name: string;
-      kind: SpanKind;
-      attributes: SpanAttributes;
-    }
-  ) {
-    this.traceId = opts.traceId;
-    this.spanId = opts.spanId;
-    this.parentSpanId = opts.parentSpanId;
-    this.name = opts.name;
-    this.kind = opts.kind;
-    this.startTimeMs = nowMs();
-    this.attributes = { ...opts.attributes };
-  }
-
-  setAttribute(key: string, value: string | number | boolean | null | undefined): void {
-    if (this.ended) return;
-    this.attributes[key] = value;
-  }
-
-  setAttributes(attrs: SpanAttributes): void {
-    if (this.ended) return;
-    Object.assign(this.attributes, attrs);
-  }
-
-  setStatus(status: "ok" | "error", errorMessage?: string): void {
-    if (this.ended) return;
-    this.status = status;
-    if (status === "error" && errorMessage) this.errorMessage = errorMessage;
-  }
-
-  end(): void {
-    if (this.ended) return;
-    this.ended = true;
-    this.endTimeMs = nowMs();
-    this.tracer._onSpanEnd(this);
-  }
-}
-
-/** No-op span when tracing is disabled. Zero allocations on hot path. */
-const NOOP_SPAN: Span = Object.freeze({
-  traceId: "00000000000000000000000000000000",
-  spanId: "0000000000000000",
-  parentSpanId: undefined,
-  name: "",
-  kind: "internal" as SpanKind,
-  startTimeMs: 0,
-  attributes: {} as SpanAttributes,
-  endTimeMs: 0,
-  status: "unset" as SpanStatus,
-  errorMessage: undefined,
-  recording: false,
-  setAttribute: () => {},
-  setAttributes: () => {},
-  setStatus: () => {},
-  end: () => {},
-});
-
-function nowMs(): number {
-  if (typeof performance !== "undefined" && typeof performance.now === "function") {
-    // performance.timeOrigin anchors the high-resolution clock to epoch ms,
-    // so exporters emit wall-clock timestamps rather than process-relative ones.
-    return performance.timeOrigin + performance.now();
-  }
-  return Date.now();
-}
-
-// ─── Exporters ──────────────────────────────────────────────────────────
-
-export interface SpanExporter {
-  export(spans: Span[]): void | Promise<void>;
-  shutdown?(): void | Promise<void>;
-}
-
-/**
- * Console exporter — pretty-prints each span to stderr on `end()`.
- * Indentation reflects depth (via parent-span lookup in a short-lived
- * Map). Used as the default in dev mode when no OTLP endpoint is set.
- */
-export class ConsoleSpanExporter implements SpanExporter {
-  private readonly stream: { write: (chunk: string) => void };
-  private readonly depthByParent = new Map<string, number>();
-  private readonly depthBySpan = new Map<string, number>();
-
-  constructor(stream?: { write: (chunk: string) => void }) {
-    // process.stderr guarantees a `write(string)` signature in Bun + Node.
-    // Accepting an override keeps the class testable without capturing
-    // real TTY output.
-    this.stream =
-      stream ??
-      (typeof process !== "undefined" && process.stderr
-        ? (process.stderr as unknown as { write: (chunk: string) => void })
-        : { write: (chunk) => console.error(chunk.trimEnd()) });
-  }
-
-  export(spans: Span[]): void {
-    for (const span of spans) {
-      const depth = this.resolveDepth(span);
-      const indent = "  ".repeat(depth);
-      const durationMs = Math.max(0, span.endTimeMs - span.startTimeMs).toFixed(2);
-      const statusIcon =
-        span.status === "error" ? "✗" : span.status === "ok" ? "✓" : "·";
-      const idTag = `${span.traceId.slice(0, 8)}/${span.spanId.slice(0, 8)}`;
-      const attrSummary = formatAttrsShort(span.attributes);
-      const err = span.errorMessage ? ` error=${JSON.stringify(span.errorMessage)}` : "";
-      this.stream.write(
-        `[trace ${idTag}] ${indent}${statusIcon} ${span.name} ${durationMs}ms${attrSummary}${err}\n`
-      );
-    }
-  }
-
-  /**
-   * Compute a nesting depth for the span by walking the parent chain we
-   * have already seen. The first span we see for a given trace starts at
-   * depth 0; each child adds one level of indent. Entries age out when
-   * the root span ends so the map stays bounded.
-   */
-  private resolveDepth(span: Span): number {
-    const parent = span.parentSpanId;
-    if (!parent) {
-      this.depthBySpan.set(span.spanId, 0);
-      return 0;
-    }
-    const parentDepth = this.depthBySpan.get(parent) ?? 0;
-    const depth = parentDepth + 1;
-    this.depthBySpan.set(span.spanId, depth);
-    // Housekeeping: when a root span (depth 0) ends, evict its subtree.
-    if (parentDepth === 0 && this.depthBySpan.size > 512) {
-      this.depthBySpan.clear();
-      this.depthByParent.clear();
-    }
-    return depth;
-  }
-}
-
-function formatAttrsShort(attrs: SpanAttributes): string {
-  const keys = Object.keys(attrs);
-  if (keys.length === 0) return "";
-  const parts: string[] = [];
-  for (const key of keys) {
-    const v = attrs[key];
-    if (v === undefined || v === null) continue;
-    parts.push(`${key}=${typeof v === "string" ? JSON.stringify(v) : String(v)}`);
-  }
-  return parts.length ? ` [${parts.join(" ")}]` : "";
-}
-
-/**
- * OTLP/HTTP JSON exporter. Produces an `ExportTraceServiceRequest`
- * body and POSTs it to `<endpoint>/v1/traces`. Honeycomb, Grafana
- * Tempo, AWS X-Ray (via OTel Collector), and the OpenTelemetry
- * Collector all accept this wire format.
- *
- * Errors during export are logged to stderr but never throw — tracing
- * must never break a request.
- */
-export class OtlpHttpSpanExporter implements SpanExporter {
-  constructor(
-    private readonly endpoint: string,
-    private readonly serviceName: string,
-    private readonly headers: Record<string, string> = {}
-  ) {}
-
-  async export(spans: Span[]): Promise<void> {
-    if (spans.length === 0) return;
-    const body = encodeOtlpJson(spans, this.serviceName);
-    const url = this.endpoint.endsWith("/v1/traces")
-      ? this.endpoint
-      : `${this.endpoint.replace(/\/$/, "")}/v1/traces`;
-    try {
-      const res = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...this.headers,
-        },
-        body: JSON.stringify(body),
-      });
-      if (!res.ok) {
-        if (typeof process !== "undefined" && process.stderr) {
-          process.stderr.write(
-            `[mandu/tracing] OTLP export failed: ${res.status} ${res.statusText}\n`
-          );
-        }
-      }
-    } catch (err) {
-      if (typeof process !== "undefined" && process.stderr) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[mandu/tracing] OTLP export error: ${msg}\n`);
-      }
-    }
-  }
-}
-
-/**
- * Encode an array of spans as the JSON shape of OTLP
- * `ExportTraceServiceRequest`. Externally-visible for tests and for
- * adapter authors who want to POST spans through a custom transport.
- */
-export function encodeOtlpJson(spans: Span[], serviceName: string): Record<string, unknown> {
-  // Times in OTLP are unix-nano unsigned ints encoded as decimal strings.
-  const toNano = (ms: number): string => {
-    const nanos = BigInt(Math.max(0, Math.floor(ms * 1_000_000)));
-    return nanos.toString();
-  };
-
-  const statusCodeOtlp = (s: SpanStatus): number => {
-    // OTel canonical codes: 0 = UNSET, 1 = OK, 2 = ERROR.
-    if (s === "ok") return 1;
-    if (s === "error") return 2;
-    return 0;
-  };
-
-  const spanKindOtlp = (k: SpanKind): number => {
-    // OTel canonical kinds: 1 = INTERNAL, 2 = SERVER, 3 = CLIENT, 4 = PRODUCER, 5 = CONSUMER.
-    switch (k) {
-      case "server":
-        return 2;
-      case "client":
-        return 3;
-      case "producer":
-        return 4;
-      case "consumer":
-        return 5;
-      default:
-        return 1;
-    }
-  };
-
-  const otlpAttr = (key: string, value: string | number | boolean | null | undefined) => {
-    if (value === null || value === undefined) return null;
-    if (typeof value === "string") return { key, value: { stringValue: value } };
-    if (typeof value === "boolean") return { key, value: { boolValue: value } };
-    if (Number.isInteger(value)) return { key, value: { intValue: String(value) } };
-    return { key, value: { doubleValue: value } };
-  };
-
-  const otlpSpans = spans.map((s) => ({
-    traceId: s.traceId,
-    spanId: s.spanId,
-    parentSpanId: s.parentSpanId ?? "",
-    name: s.name,
-    kind: spanKindOtlp(s.kind),
-    startTimeUnixNano: toNano(s.startTimeMs),
-    endTimeUnixNano: toNano(s.endTimeMs > 0 ? s.endTimeMs : s.startTimeMs),
-    attributes: Object.entries(s.attributes)
-      .map(([k, v]) => otlpAttr(k, v))
-      .filter((entry): entry is NonNullable<typeof entry> => entry !== null),
-    status: {
-      code: statusCodeOtlp(s.status),
-      ...(s.errorMessage ? { message: s.errorMessage } : {}),
-    },
-  }));
-
-  return {
-    resourceSpans: [
-      {
-        resource: {
-          attributes: [
-            { key: "service.name", value: { stringValue: serviceName } },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: "@mandujs/core", version: "1" },
-            spans: otlpSpans,
-          },
-        ],
-      },
-    ],
-  };
-}
-
-// ─── AsyncLocalStorage context propagation ──────────────────────────────
-
-const spanStorage = new AsyncLocalStorage<Span>();
-
-/**
- * Return the currently-active span, or `undefined` outside any
- * `runWithSpan()` scope. Works across `await`s, timers, and nested
- * callbacks.
- */
-export function getActiveSpan(): Span | undefined {
-  return spanStorage.getStore();
-}
-
-/**
- * Bind a span to the AsyncLocalStorage context of `fn`. Inside (and
- * downstream of) `fn`, {@link getActiveSpan} returns `span`. The span
- * is NOT auto-ended — callers own lifecycle.
- */
-export function runWithSpan<T>(span: Span, fn: () => T): T {
-  return spanStorage.run(span, fn);
-}
-
-/**
- * Stamp the active span's trace context onto `headers` as a
- * `traceparent` header so downstream services can join the trace.
- * No-op when no active span OR the active span is the no-op span.
- */
-export function injectTraceContext(headers: Headers, span: Span | undefined = getActiveSpan()): void {
-  if (!span || !span.recording) return;
-  headers.set("traceparent", formatTraceparent(span.traceId, span.spanId));
-}
-
-// ─── Tracer ─────────────────────────────────────────────────────────────
-
-export interface TracerConfig {
-  /** Off → `startSpan` returns no-op. Default: `false`. */
-  enabled?: boolean;
-  /** `"console"` (default) or `"otlp"`. */
-  exporter?: "console" | "otlp";
-  /** OTLP collector endpoint (e.g. `https://api.honeycomb.io`). Required for `"otlp"`. */
-  endpoint?: string;
-  /** OTLP headers (e.g. `{ 'x-honeycomb-team': 'KEY' }`). */
-  headers?: Record<string, string>;
-  /** `resource.service.name`. Default: `"mandu"`. */
-  serviceName?: string;
-  /** Inject a custom exporter (overrides `exporter` / `endpoint`). Used in tests. */
-  customExporter?: SpanExporter;
-}
-
-export class Tracer {
-  readonly config: Required<
-    Omit<TracerConfig, "customExporter" | "endpoint" | "headers">
-  > & {
-    endpoint?: string;
-    headers: Record<string, string>;
-    customExporter?: SpanExporter;
-  };
-  private readonly exporter: SpanExporter | null;
-
-  constructor(config: TracerConfig = {}) {
-    this.config = {
-      enabled: config.enabled ?? false,
-      exporter: config.exporter ?? "console",
-      endpoint: config.endpoint,
-      headers: config.headers ?? {},
-      serviceName: config.serviceName ?? "mandu",
-      customExporter: config.customExporter,
-    };
-    if (!this.config.enabled) {
-      this.exporter = null;
-    } else if (config.customExporter) {
-      this.exporter = config.customExporter;
-    } else if (this.config.exporter === "otlp") {
-      if (!this.config.endpoint) {
-        // Misconfigured → fall back to console so dev still gets output.
-        this.exporter = new ConsoleSpanExporter();
-      } else {
-        this.exporter = new OtlpHttpSpanExporter(
-          this.config.endpoint,
-          this.config.serviceName,
-          this.config.headers
-        );
-      }
-    } else {
-      this.exporter = new ConsoleSpanExporter();
-    }
-  }
-
-  /** Whether this tracer will record spans. */
-  get enabled(): boolean {
-    return this.config.enabled;
-  }
-
-  /**
-   * Start a new span. When tracing is disabled, returns the shared
-   * no-op span (zero allocations).
-   *
-   * Parent resolution order:
-   *   1. `opts.parent` if provided (use `null` to force a root span)
-   *   2. The active span from AsyncLocalStorage
-   *   3. None (root span)
-   */
-  startSpan(name: string, opts: SpanOptions = {}): Span {
-    if (!this.config.enabled) return NOOP_SPAN;
-    const parent =
-      opts.parent === null
-        ? undefined
-        : opts.parent ?? getActiveSpan();
-    const parentRecording = parent && parent.recording ? parent : undefined;
-    const traceId = parentRecording ? parentRecording.traceId : newTraceId();
-    return new RecordingSpan(this, {
-      traceId,
-      spanId: newSpanId(),
-      parentSpanId: parentRecording?.spanId,
-      name,
-      kind: opts.kind ?? (parentRecording ? "internal" : "server"),
-      attributes: opts.attributes ?? {},
-    });
-  }
-
-  /**
-   * Start a span from an incoming request's `traceparent` header. If
-   * the header is missing / malformed, a new root span is minted.
-   */
-  startSpanFromRequest(name: string, req: Request, opts: Omit<SpanOptions, "parent"> = {}): Span {
-    if (!this.config.enabled) return NOOP_SPAN;
-    const tp = parseTraceparent(req.headers.get("traceparent"));
-    if (!tp) {
-      return this.startSpan(name, { ...opts, parent: null, kind: opts.kind ?? "server" });
-    }
-    return new RecordingSpan(this, {
-      traceId: tp.traceId,
-      spanId: newSpanId(),
-      parentSpanId: tp.parentId,
-      name,
-      kind: opts.kind ?? "server",
-      attributes: opts.attributes ?? {},
-    });
-  }
-
-  /**
-   * Run `fn` with `span` as the active span. Equivalent to
-   * {@link runWithSpan} but colocated with the tracer for DX.
-   */
-  withSpan<T>(span: Span, fn: () => T): T {
-    return runWithSpan(span, fn);
-  }
-
-  /**
-   * Open a child span, invoke `fn`, and auto-end the span when the
-   * returned promise resolves (or rejects, with `status=error`).
-   */
-  async span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts: SpanOptions = {}): Promise<T> {
-    const span = this.startSpan(name, opts);
-    try {
-      const result = await runWithSpan(span, () => fn(span));
-      if (span.status === "unset") span.setStatus("ok");
-      return result;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      span.setStatus("error", msg);
-      throw err;
-    } finally {
-      span.end();
-    }
-  }
-
-  /** @internal Called by {@link RecordingSpan.end}. */
-  _onSpanEnd(span: Span): void {
-    if (!this.exporter) return;
-    try {
-      void this.exporter.export([span]);
-    } catch {
-      // Exporter failures must never surface — swallow.
-    }
-  }
-
-  /** Flush + release the underlying exporter. No-op if disabled. */
-  async shutdown(): Promise<void> {
-    if (this.exporter && typeof this.exporter.shutdown === "function") {
-      await this.exporter.shutdown();
-    }
-  }
-}
-
-// ─── Default tracer ──────────────────────────────────────────────────────
-
-let defaultTracer: Tracer = new Tracer({ enabled: false });
-
-/**
- * Return the process-global tracer. Starts disabled; the runtime
- * installs a configured tracer during `startServer()` when
- * `observability.tracing.enabled` is true.
- */
-export function getTracer(): Tracer {
-  return defaultTracer;
-}
-
-/**
- * Install a tracer as the process-global. Idempotent — a subsequent
- * call replaces the previous tracer (the runtime calls this once at
- * boot; tests use it to swap in a capturing exporter).
- */
-export function setTracer(tracer: Tracer): void {
-  defaultTracer = tracer;
-}
-
-/**
- * Reset the process-global tracer back to the disabled no-op tracer.
- * Intended for tests; production code should not need this.
- */
-export function resetTracer(): void {
-  defaultTracer = new Tracer({ enabled: false });
-}
-
-/**
- * Build a tracer from a {@link TracerConfig}-shaped object, honouring
- * the `MANDU_OTEL_ENDPOINT` env var as an override. Used by the
- * runtime at `startServer()` time.
- */
-export function createTracerFromConfig(cfg: TracerConfig | undefined): Tracer {
-  const envEndpoint =
-    typeof process !== "undefined" ? process.env?.MANDU_OTEL_ENDPOINT : undefined;
-  const resolved: TracerConfig = { ...(cfg ?? {}) };
-  if (envEndpoint) {
-    resolved.enabled = true;
-    resolved.exporter = "otlp";
-    resolved.endpoint = envEndpoint;
-  }
-  return new Tracer(resolved);
-}
+/**
+ * Phase 18.θ — OpenTelemetry-compatible request tracing.
+ *
+ * Hand-rolled W3C Trace Context + OTLP/HTTP encoder. Zero runtime
+ * dependencies (AsyncLocalStorage comes from `node:async_hooks`, which
+ * Bun ships natively).
+ *
+ * Public API:
+ *   - {@link Tracer}          — factory for root + child spans
+ *   - {@link Span}            — lifecycle + attribute API (`end`, `setAttribute`, `setStatus`)
+ *   - {@link parseTraceparent} / {@link formatTraceparent} — W3C wire format
+ *   - {@link getActiveSpan}   — AsyncLocalStorage accessor
+ *   - {@link runWithSpan}     — bind a span to the async context of a callback
+ *   - {@link injectTraceContext} — stamp `traceparent` on outgoing `Headers`
+ *   - {@link ConsoleSpanExporter} / {@link OtlpHttpSpanExporter}
+ *
+ * Design:
+ *
+ *   1. Tracing is **off by default**. An explicit
+ *      `{ enabled: true }` on the config (or `MANDU_OTEL_ENDPOINT` env)
+ *      flips it on; otherwise `startSpan()` returns a no-op span and the
+ *      hot path is branch-free.
+ *
+ *   2. Span ids / trace ids are generated via `crypto.getRandomValues`
+ *      per the W3C Trace Context spec — 16 bytes for trace-id (hex 32
+ *      chars), 8 bytes for span-id (hex 16 chars). The "all zero" case
+ *      forbidden by the spec is retried (probability ≈ 2^-128).
+ *
+ *   3. Parent context comes from the incoming `traceparent` header.
+ *      If missing / malformed, a new root trace-id is minted. On
+ *      outgoing fetches, {@link injectTraceContext} re-emits the current
+ *      context so downstream services see the same trace-id.
+ *
+ *   4. AsyncLocalStorage keeps the active span in scope across
+ *      `await`s, timers, and nested callbacks — without threading an
+ *      explicit `ctx` parameter through every function. Works in Bun
+ *      1.1+ and Node ≥ 16.
+ *
+ *   5. OTLP/HTTP exporter serialises spans to the JSON encoding of the
+ *      `ExportTraceServiceRequest` protobuf (OTLP v1). Honeycomb,
+ *      Grafana Tempo, and the OTel Collector all accept this over HTTP
+ *      with `Content-Type: application/json`.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ─── W3C Trace Context ──────────────────────────────────────────────────
+
+/**
+ * Parsed W3C `traceparent` header. The spec defines exactly four dash-
+ * separated fields; anything else yields `null`.
+ *
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+export interface TraceparentFields {
+  /** 2-hex-char version. Always `"00"` for v1. */
+  version: string;
+  /** 32-hex-char trace-id (128-bit). */
+  traceId: string;
+  /** 16-hex-char span-id (64-bit) of the *parent* span. */
+  parentId: string;
+  /** 2-hex-char flags byte. Bit 0 = sampled. */
+  flags: string;
+}
+
+const TRACEPARENT_REGEX =
+  /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+/**
+ * Parse a `traceparent` header. Returns `null` for any header that does
+ * not match the v1 grammar, including the all-zero trace-id / span-id
+ * cases forbidden by the spec.
+ */
+export function parseTraceparent(value: string | null | undefined): TraceparentFields | null {
+  if (!value) return null;
+  const m = TRACEPARENT_REGEX.exec(value.trim());
+  if (!m) return null;
+  const [, version, traceId, parentId, flags] = m;
+  if (version === "ff") return null; // reserved
+  if (/^0+$/.test(traceId)) return null;
+  if (/^0+$/.test(parentId)) return null;
+  return { version, traceId, parentId, flags };
+}
+
+/**
+ * Format a `traceparent` header for downstream propagation.
+ *
+ * `flags` defaults to `"01"` (sampled) so the entire trace survives
+ * middle hops. Pass `"00"` to mark the span as un-sampled.
+ */
+export function formatTraceparent(traceId: string, spanId: string, flags: string = "01"): string {
+  return `00-${traceId}-${spanId}-${flags}`;
+}
+
+// ─── ID generation ──────────────────────────────────────────────────────
+
+function randomHex(bytes: number): string {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  let out = "";
+  for (let i = 0; i < buf.length; i++) {
+    out += buf[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+/** Mint a fresh 128-bit W3C-compliant trace-id. Never all-zero. */
+export function newTraceId(): string {
+  for (;;) {
+    const id = randomHex(16);
+    if (!/^0+$/.test(id)) return id;
+  }
+}
+
+/** Mint a fresh 64-bit W3C-compliant span-id. Never all-zero. */
+export function newSpanId(): string {
+  for (;;) {
+    const id = randomHex(8);
+    if (!/^0+$/.test(id)) return id;
+  }
+}
+
+// ─── Span / Tracer ──────────────────────────────────────────────────────
+
+export type SpanStatus = "unset" | "ok" | "error";
+
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+
+export interface SpanAttributes {
+  [key: string]: string | number | boolean | null | undefined;
+}
+
+export interface SpanOptions {
+  /** Optional span kind. Default: `"internal"`. Root spans use `"server"`. */
+  kind?: SpanKind;
+  /** Attributes set at span start. Additional attributes can be set via {@link Span.setAttribute}. */
+  attributes?: SpanAttributes;
+  /**
+   * Override the parent span-id. Default: the currently-active span
+   * (from AsyncLocalStorage). Use `null` to force a root span.
+   */
+  parent?: Span | null;
+}
+
+/**
+ * A single span in the trace tree. Always lifecycle-matched with
+ * exactly one {@link Span.end} call — the Tracer's exporter flushes
+ * the span only after `end()` returns.
+ */
+export interface Span {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | undefined;
+  readonly name: string;
+  readonly kind: SpanKind;
+  readonly startTimeMs: number;
+  readonly attributes: SpanAttributes;
+  /** `-1` until {@link end} is called. */
+  readonly endTimeMs: number;
+  readonly status: SpanStatus;
+  readonly errorMessage: string | undefined;
+  /** `false` for the no-op tracer (feature disabled). */
+  readonly recording: boolean;
+
+  setAttribute(key: string, value: string | number | boolean | null | undefined): void;
+  setAttributes(attrs: SpanAttributes): void;
+  setStatus(status: "ok" | "error", errorMessage?: string): void;
+  end(): void;
+}
+
+/** Internal mutable state for a recording span. */
+class RecordingSpan implements Span {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | undefined;
+  readonly name: string;
+  readonly kind: SpanKind;
+  readonly startTimeMs: number;
+  readonly attributes: SpanAttributes;
+  endTimeMs: number = -1;
+  status: SpanStatus = "unset";
+  errorMessage: string | undefined;
+  readonly recording = true;
+  private ended = false;
+
+  constructor(
+    private readonly tracer: Tracer,
+    opts: {
+      traceId: string;
+      spanId: string;
+      parentSpanId: string | undefined;
+      name: string;
+      kind: SpanKind;
+      attributes: SpanAttributes;
+    }
+  ) {
+    this.traceId = opts.traceId;
+    this.spanId = opts.spanId;
+    this.parentSpanId = opts.parentSpanId;
+    this.name = opts.name;
+    this.kind = opts.kind;
+    this.startTimeMs = nowMs();
+    this.attributes = { ...opts.attributes };
+  }
+
+  setAttribute(key: string, value: string | number | boolean | null | undefined): void {
+    if (this.ended) return;
+    this.attributes[key] = value;
+  }
+
+  setAttributes(attrs: SpanAttributes): void {
+    if (this.ended) return;
+    Object.assign(this.attributes, attrs);
+  }
+
+  setStatus(status: "ok" | "error", errorMessage?: string): void {
+    if (this.ended) return;
+    this.status = status;
+    if (status === "error" && errorMessage) this.errorMessage = errorMessage;
+  }
+
+  end(): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.endTimeMs = nowMs();
+    this.tracer._onSpanEnd(this);
+  }
+}
+
+/** No-op span when tracing is disabled. Zero allocations on hot path. */
+const NOOP_SPAN: Span = Object.freeze({
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  parentSpanId: undefined,
+  name: "",
+  kind: "internal" as SpanKind,
+  startTimeMs: 0,
+  attributes: {} as SpanAttributes,
+  endTimeMs: 0,
+  status: "unset" as SpanStatus,
+  errorMessage: undefined,
+  recording: false,
+  setAttribute: () => {},
+  setAttributes: () => {},
+  setStatus: () => {},
+  end: () => {},
+});
+
+function nowMs(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    // performance.timeOrigin anchors the high-resolution clock to epoch ms,
+    // so exporters emit wall-clock timestamps rather than process-relative ones.
+    return performance.timeOrigin + performance.now();
+  }
+  return Date.now();
+}
+
+// ─── Exporters ──────────────────────────────────────────────────────────
+
+export interface SpanExporter {
+  export(spans: Span[]): void | Promise<void>;
+  shutdown?(): void | Promise<void>;
+}
+
+/**
+ * Console exporter — pretty-prints each span to stderr on `end()`.
+ * Indentation reflects depth (via parent-span lookup in a short-lived
+ * Map). Used as the default in dev mode when no OTLP endpoint is set.
+ */
+export class ConsoleSpanExporter implements SpanExporter {
+  private readonly stream: { write: (chunk: string) => void };
+  private readonly depthByParent = new Map<string, number>();
+  private readonly depthBySpan = new Map<string, number>();
+
+  constructor(stream?: { write: (chunk: string) => void }) {
+    // process.stderr guarantees a `write(string)` signature in Bun + Node.
+    // Accepting an override keeps the class testable without capturing
+    // real TTY output.
+    this.stream =
+      stream ??
+      (typeof process !== "undefined" && process.stderr
+        ? (process.stderr as unknown as { write: (chunk: string) => void })
+        : { write: (chunk) => console.error(chunk.trimEnd()) });
+  }
+
+  export(spans: Span[]): void {
+    for (const span of spans) {
+      const depth = this.resolveDepth(span);
+      const indent = "  ".repeat(depth);
+      const durationMs = Math.max(0, span.endTimeMs - span.startTimeMs).toFixed(2);
+      const statusIcon =
+        span.status === "error" ? "✗" : span.status === "ok" ? "✓" : "·";
+      const idTag = `${span.traceId.slice(0, 8)}/${span.spanId.slice(0, 8)}`;
+      const attrSummary = formatAttrsShort(span.attributes);
+      const err = span.errorMessage ? ` error=${JSON.stringify(span.errorMessage)}` : "";
+      this.stream.write(
+        `[trace ${idTag}] ${indent}${statusIcon} ${span.name} ${durationMs}ms${attrSummary}${err}\n`
+      );
+    }
+  }
+
+  /**
+   * Compute a nesting depth for the span by walking the parent chain we
+   * have already seen. The first span we see for a given trace starts at
+   * depth 0; each child adds one level of indent. Entries age out when
+   * the root span ends so the map stays bounded.
+   */
+  private resolveDepth(span: Span): number {
+    const parent = span.parentSpanId;
+    if (!parent) {
+      this.depthBySpan.set(span.spanId, 0);
+      return 0;
+    }
+    const parentDepth = this.depthBySpan.get(parent) ?? 0;
+    const depth = parentDepth + 1;
+    this.depthBySpan.set(span.spanId, depth);
+    // Housekeeping: when a root span (depth 0) ends, evict its subtree.
+    if (parentDepth === 0 && this.depthBySpan.size > 512) {
+      this.depthBySpan.clear();
+      this.depthByParent.clear();
+    }
+    return depth;
+  }
+}
+
+function formatAttrsShort(attrs: SpanAttributes): string {
+  const keys = Object.keys(attrs);
+  if (keys.length === 0) return "";
+  const parts: string[] = [];
+  for (const key of keys) {
+    const v = attrs[key];
+    if (v === undefined || v === null) continue;
+    parts.push(`${key}=${typeof v === "string" ? JSON.stringify(v) : String(v)}`);
+  }
+  return parts.length ? ` [${parts.join(" ")}]` : "";
+}
+
+/**
+ * OTLP/HTTP JSON exporter. Produces an `ExportTraceServiceRequest`
+ * body and POSTs it to `<endpoint>/v1/traces`. Honeycomb, Grafana
+ * Tempo, AWS X-Ray (via OTel Collector), and the OpenTelemetry
+ * Collector all accept this wire format.
+ *
+ * Errors during export are logged to stderr but never throw — tracing
+ * must never break a request.
+ */
+export class OtlpHttpSpanExporter implements SpanExporter {
+  constructor(
+    private readonly endpoint: string,
+    private readonly serviceName: string,
+    private readonly headers: Record<string, string> = {}
+  ) {}
+
+  async export(spans: Span[]): Promise<void> {
+    if (spans.length === 0) return;
+    const body = encodeOtlpJson(spans, this.serviceName);
+    const url = this.endpoint.endsWith("/v1/traces")
+      ? this.endpoint
+      : `${this.endpoint.replace(/\/$/, "")}/v1/traces`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.headers,
+        },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        if (typeof process !== "undefined" && process.stderr) {
+          process.stderr.write(
+            `[mandu/tracing] OTLP export failed: ${res.status} ${res.statusText}\n`
+          );
+        }
+      }
+    } catch (err) {
+      if (typeof process !== "undefined" && process.stderr) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[mandu/tracing] OTLP export error: ${msg}\n`);
+      }
+    }
+  }
+}
+
+/**
+ * Encode an array of spans as the JSON shape of OTLP
+ * `ExportTraceServiceRequest`. Externally-visible for tests and for
+ * adapter authors who want to POST spans through a custom transport.
+ */
+export function encodeOtlpJson(spans: Span[], serviceName: string): Record<string, unknown> {
+  // Times in OTLP are unix-nano unsigned ints encoded as decimal strings.
+  const toNano = (ms: number): string => {
+    const nanos = BigInt(Math.max(0, Math.floor(ms * 1_000_000)));
+    return nanos.toString();
+  };
+
+  const statusCodeOtlp = (s: SpanStatus): number => {
+    // OTel canonical codes: 0 = UNSET, 1 = OK, 2 = ERROR.
+    if (s === "ok") return 1;
+    if (s === "error") return 2;
+    return 0;
+  };
+
+  const spanKindOtlp = (k: SpanKind): number => {
+    // OTel canonical kinds: 1 = INTERNAL, 2 = SERVER, 3 = CLIENT, 4 = PRODUCER, 5 = CONSUMER.
+    switch (k) {
+      case "server":
+        return 2;
+      case "client":
+        return 3;
+      case "producer":
+        return 4;
+      case "consumer":
+        return 5;
+      default:
+        return 1;
+    }
+  };
+
+  const otlpAttr = (key: string, value: string | number | boolean | null | undefined) => {
+    if (value === null || value === undefined) return null;
+    if (typeof value === "string") return { key, value: { stringValue: value } };
+    if (typeof value === "boolean") return { key, value: { boolValue: value } };
+    if (Number.isInteger(value)) return { key, value: { intValue: String(value) } };
+    return { key, value: { doubleValue: value } };
+  };
+
+  const otlpSpans = spans.map((s) => ({
+    traceId: s.traceId,
+    spanId: s.spanId,
+    parentSpanId: s.parentSpanId ?? "",
+    name: s.name,
+    kind: spanKindOtlp(s.kind),
+    startTimeUnixNano: toNano(s.startTimeMs),
+    endTimeUnixNano: toNano(s.endTimeMs > 0 ? s.endTimeMs : s.startTimeMs),
+    attributes: Object.entries(s.attributes)
+      .map(([k, v]) => otlpAttr(k, v))
+      .filter((entry): entry is NonNullable<typeof entry> => entry !== null),
+    status: {
+      code: statusCodeOtlp(s.status),
+      ...(s.errorMessage ? { message: s.errorMessage } : {}),
+    },
+  }));
+
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            { key: "service.name", value: { stringValue: serviceName } },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: "@mandujs/core", version: "1" },
+            spans: otlpSpans,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+// ─── AsyncLocalStorage context propagation ──────────────────────────────
+
+const spanStorage = new AsyncLocalStorage<Span>();
+
+/**
+ * Return the currently-active span, or `undefined` outside any
+ * `runWithSpan()` scope. Works across `await`s, timers, and nested
+ * callbacks.
+ */
+export function getActiveSpan(): Span | undefined {
+  return spanStorage.getStore();
+}
+
+/**
+ * Bind a span to the AsyncLocalStorage context of `fn`. Inside (and
+ * downstream of) `fn`, {@link getActiveSpan} returns `span`. The span
+ * is NOT auto-ended — callers own lifecycle.
+ */
+export function runWithSpan<T>(span: Span, fn: () => T): T {
+  return spanStorage.run(span, fn);
+}
+
+/**
+ * Stamp the active span's trace context onto `headers` as a
+ * `traceparent` header so downstream services can join the trace.
+ * No-op when no active span OR the active span is the no-op span.
+ */
+export function injectTraceContext(headers: Headers, span: Span | undefined = getActiveSpan()): void {
+  if (!span || !span.recording) return;
+  headers.set("traceparent", formatTraceparent(span.traceId, span.spanId));
+}
+
+// ─── Tracer ─────────────────────────────────────────────────────────────
+
+export interface TracerConfig {
+  /** Off → `startSpan` returns no-op. Default: `false`. */
+  enabled?: boolean;
+  /** `"console"` (default) or `"otlp"`. */
+  exporter?: "console" | "otlp";
+  /** OTLP collector endpoint (e.g. `https://api.honeycomb.io`). Required for `"otlp"`. */
+  endpoint?: string;
+  /** OTLP headers (e.g. `{ 'x-honeycomb-team': 'KEY' }`). */
+  headers?: Record<string, string>;
+  /** `resource.service.name`. Default: `"mandu"`. */
+  serviceName?: string;
+  /** Inject a custom exporter (overrides `exporter` / `endpoint`). Used in tests. */
+  customExporter?: SpanExporter;
+}
+
+export class Tracer {
+  readonly config: Required<
+    Omit<TracerConfig, "customExporter" | "endpoint" | "headers">
+  > & {
+    endpoint?: string;
+    headers: Record<string, string>;
+    customExporter?: SpanExporter;
+  };
+  private readonly exporter: SpanExporter | null;
+
+  constructor(config: TracerConfig = {}) {
+    this.config = {
+      enabled: config.enabled ?? false,
+      exporter: config.exporter ?? "console",
+      endpoint: config.endpoint,
+      headers: config.headers ?? {},
+      serviceName: config.serviceName ?? "mandu",
+      customExporter: config.customExporter,
+    };
+    if (!this.config.enabled) {
+      this.exporter = null;
+    } else if (config.customExporter) {
+      this.exporter = config.customExporter;
+    } else if (this.config.exporter === "otlp") {
+      if (!this.config.endpoint) {
+        // Misconfigured → fall back to console so dev still gets output.
+        this.exporter = new ConsoleSpanExporter();
+      } else {
+        this.exporter = new OtlpHttpSpanExporter(
+          this.config.endpoint,
+          this.config.serviceName,
+          this.config.headers
+        );
+      }
+    } else {
+      this.exporter = new ConsoleSpanExporter();
+    }
+  }
+
+  /** Whether this tracer will record spans. */
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Start a new span. When tracing is disabled, returns the shared
+   * no-op span (zero allocations).
+   *
+   * Parent resolution order:
+   *   1. `opts.parent` if provided (use `null` to force a root span)
+   *   2. The active span from AsyncLocalStorage
+   *   3. None (root span)
+   */
+  startSpan(name: string, opts: SpanOptions = {}): Span {
+    if (!this.config.enabled) return NOOP_SPAN;
+    const parent =
+      opts.parent === null
+        ? undefined
+        : opts.parent ?? getActiveSpan();
+    const parentRecording = parent && parent.recording ? parent : undefined;
+    const traceId = parentRecording ? parentRecording.traceId : newTraceId();
+    return new RecordingSpan(this, {
+      traceId,
+      spanId: newSpanId(),
+      parentSpanId: parentRecording?.spanId,
+      name,
+      kind: opts.kind ?? (parentRecording ? "internal" : "server"),
+      attributes: opts.attributes ?? {},
+    });
+  }
+
+  /**
+   * Start a span from an incoming request's `traceparent` header. If
+   * the header is missing / malformed, a new root span is minted.
+   */
+  startSpanFromRequest(name: string, req: Request, opts: Omit<SpanOptions, "parent"> = {}): Span {
+    if (!this.config.enabled) return NOOP_SPAN;
+    const tp = parseTraceparent(req.headers.get("traceparent"));
+    if (!tp) {
+      return this.startSpan(name, { ...opts, parent: null, kind: opts.kind ?? "server" });
+    }
+    return new RecordingSpan(this, {
+      traceId: tp.traceId,
+      spanId: newSpanId(),
+      parentSpanId: tp.parentId,
+      name,
+      kind: opts.kind ?? "server",
+      attributes: opts.attributes ?? {},
+    });
+  }
+
+  /**
+   * Run `fn` with `span` as the active span. Equivalent to
+   * {@link runWithSpan} but colocated with the tracer for DX.
+   */
+  withSpan<T>(span: Span, fn: () => T): T {
+    return runWithSpan(span, fn);
+  }
+
+  /**
+   * Open a child span, invoke `fn`, and auto-end the span when the
+   * returned promise resolves (or rejects, with `status=error`).
+   */
+  async span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts: SpanOptions = {}): Promise<T> {
+    const span = this.startSpan(name, opts);
+    try {
+      const result = await runWithSpan(span, () => fn(span));
+      if (span.status === "unset") span.setStatus("ok");
+      return result;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      span.setStatus("error", msg);
+      throw err;
+    } finally {
+      span.end();
+    }
+  }
+
+  /** @internal Called by {@link RecordingSpan.end}. */
+  _onSpanEnd(span: Span): void {
+    if (!this.exporter) return;
+    try {
+      void this.exporter.export([span]);
+    } catch {
+      // Exporter failures must never surface — swallow.
+    }
+  }
+
+  /** Flush + release the underlying exporter. No-op if disabled. */
+  async shutdown(): Promise<void> {
+    if (this.exporter && typeof this.exporter.shutdown === "function") {
+      await this.exporter.shutdown();
+    }
+  }
+}
+
+// ─── Default tracer ──────────────────────────────────────────────────────
+
+let defaultTracer: Tracer = new Tracer({ enabled: false });
+
+/**
+ * Return the process-global tracer. Starts disabled; the runtime
+ * installs a configured tracer during `startServer()` when
+ * `observability.tracing.enabled` is true.
+ */
+export function getTracer(): Tracer {
+  return defaultTracer;
+}
+
+/**
+ * Install a tracer as the process-global. Idempotent — a subsequent
+ * call replaces the previous tracer (the runtime calls this once at
+ * boot; tests use it to swap in a capturing exporter).
+ */
+export function setTracer(tracer: Tracer): void {
+  defaultTracer = tracer;
+}
+
+/**
+ * Reset the process-global tracer back to the disabled no-op tracer.
+ * Intended for tests; production code should not need this.
+ */
+export function resetTracer(): void {
+  defaultTracer = new Tracer({ enabled: false });
+}
+
+/**
+ * Build a tracer from a {@link TracerConfig}-shaped object, honouring
+ * the `MANDU_OTEL_ENDPOINT` env var as an override. Used by the
+ * runtime at `startServer()` time.
+ */
+export function createTracerFromConfig(cfg: TracerConfig | undefined): Tracer {
+  const envEndpoint =
+    typeof process !== "undefined" ? process.env?.MANDU_OTEL_ENDPOINT : undefined;
+  const resolved: TracerConfig = { ...(cfg ?? {}) };
+  if (envEndpoint) {
+    resolved.enabled = true;
+    resolved.exporter = "otlp";
+    resolved.endpoint = envEndpoint;
+  }
+  return new Tracer(resolved);
+}