Forward the @vercel/otel X-Ray trace context to the backend — connect app → functions

1 — The break, in one sentence

The app ran two trace contexts that were never reconciled. @vercel/otel exported the vercel.* span under id A; outbound-headers.ts forwarded the proxy-stamped random id B instead. Single-source the outbound carrier on the active span and the gap closes — the fix is single-source, not better-minting (making B X-Ray-legal would still be a different id).

2 — The fix: inject the active context via the installed propagator

On a live request the active @vercel/otel span wins. We inject it into a fresh W3C carrier using the global propagator that registerOTel already installed (src/instrumentation.ts) — so the carrier always matches the active context and tracestate is handled too. No provider is constructed here; provider ownership stays in instrumentation.ts (pramaan-docs ADR-104 Phase B).

// src/lib/outbound-headers.ts  (server-only)
function injectActiveTraceContext(): Record<string, string> | null {
  const carrier: Record<string, string> = {};
  propagation.inject(otelContext.active(), carrier);   // global W3C propagator
  return isValidTraceparent(getHeaderValue(carrier, TRACEPARENT_HEADER))
    ? carrier        // active recording span → id A landed in the carrier
    : null;          // no active span → caller falls back to minting
}

// in applyOutboundRequestHeaders():
if (isTraceBridgeDisabled()) {
  traceparent = null;                                  // kill switch
} else {
  const carrier = injectActiveTraceContext();
  if (carrier !== null) {
    traceparent = getHeaderValue(carrier, TRACEPARENT_HEADER)!;   // id A WINS
    const tracestate = getHeaderValue(carrier, TRACESTATE_HEADER);
    if (tracestate !== undefined) setHeaderValue(requestHeaders, TRACESTATE_HEADER, tracestate);
  } else {
    traceparent = resolveTraceparent(inboundTraceparent);         // fallback: mint
  }
}

The active span's traceparent overrides the proxy-stamped Phase-A header, so the id on the wire is the SAME span that @vercel/otel exports to X-Ray. With the functions-lane ADOT extractor already preferring tracecontext, pramaan-app-api adopts id A and joins the trace — no functions or infra change required.

3 — What was deliberately preserved

4 — Tests

• Active span wins: with a mocked propagator injecting id A, the outbound traceparent's traceId equals the active span's id — not a random/minted id — and overrides a present inbound/proxy-stamped traceparent.
• tracestate carried: a tracestate from the active context rides alongside traceparent.
• No-active-span fallback: with no provider the default no-op propagator injects nothing → the helper falls back to resolveTraceparent/mintTraceparent (background/no-request unchanged).
• Kill switch: PRAMAAN_OTEL_DISABLED=1 strips traceparent even when a span is active; correlation unaffected.

Verification green

• pnpm lint — clean (1 pre-existing no-img-element warning in avatar.tsx, unrelated).
• pnpm exec tsc --noEmit — clean.
• pnpm test — 557 passed (96 files); new active-span cases in tests/unit/lib/outbound-headers.test.ts.
• pnpm build — pass. git diff --check — clean.

Out of scope

The broader Phase-A correlation_id retirement (#1454/G7) is NOT done here. The live X-Ray acceptance proof — one real stg.app.pramaan.io request yielding a single trace_id where service("vercel.serverless-runtime") AND service("pramaan-functions-app-api") co-occur with a parent edge — is the EPIC-1400 / #1466 gate, run on the deployed SHA after this merges. The admin surface carries the same defect and gets the same fix in a separate pramaan-admin app-lane child.

Files changed

2 file(s), +145 / -7 lines