ENG-2398: Add private baggage propagation and explicit errors

Author: gtxy27

README.md

@@ -5,7 +5,7 @@ A DX-focused OpenTelemetry wrapper for **Bun** and **Node.js**.
 Vanilla OTel works, but the setup is verbose, the logger plumbing is awkward, and PII scrubbing is on you. `@photon-ai/otel` wraps the OTLP/HTTP stack into a few well-named functions:
 
 - **`setupOtel()`** — idempotent one-call bootstrap for traces + logs + metrics. Honors standard `OTEL_EXPORTER_OTLP_*` env vars.
-- **`createIsolatedOtel()`** — creates an isolated trace + log runtime with its own Resource and configurable propagation header, without replacing global providers or context.
+- **`createIsolatedOtel()`** — creates an isolated trace + log runtime with its own Resource, configurable trace carrier, and optional private Baggage carrier, without replacing global providers or context.
 - **`otel.getMeter(name)`** — creates standard OpenTelemetry instruments from this setup's meter provider, with identical behavior in global and scoped mode.
 - **`createLogger(module)`** — structured logger that writes to both the OTel logger provider and `console`, with automatic trace correlation and exception capture. Every level (`debug`/`info`/`warn`/`error`) accepts `attrs` **and** an `error`, and shares one configurable level gate.
 - **`withSpan(name, attrs?, fn)`** — wrap any sync or async function in a span; errors are recorded and PII in the error message is scrubbed before being attached to span status.
@@ -95,7 +95,7 @@ attribute guidance, and scoped mode.
 | Function                                      | Description                                                                                                |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `setupOtel(options): OtelHandle`              | Boots OTLP/HTTP traces + logs + metrics. The handle exposes `getMeter()`, providers, and `shutdown()`. Pass `register: false` for scoped mode. |
-| `createIsolatedOtel(options): IsolatedOtelHandle` | Creates an isolated, non-global trace + log runtime with its own endpoint, Resource, and propagation header. Returns a new runtime on every call. |
+| `createIsolatedOtel(options): IsolatedOtelHandle` | Creates an isolated, non-global trace + log runtime with its own endpoint, Resource, private trace carrier, and optional private Baggage carrier. Returns a new runtime on every call. |
 | `isOtelActive(): boolean`                     | Returns `true` if `setupOtel` has already run in this process.                                             |
 | `instrumentFetch(options?): FetchInstrumentation` | Low-level wrap of `globalThis.fetch` for CLIENT spans + W3C propagation. Returns `{ unpatch() }`. `setupOtel` calls this on Bun; on Node it prefers native undici. |
 | `createInstrumentedFetch(baseFetch?, options?): typeof fetch` | Returns a NEW instrumented fetch (CLIENT spans + W3C propagation) wrapping `baseFetch` (default `globalThis.fetch`) without touching the global. For SDKs that take a `fetch` option. |
@@ -116,19 +116,31 @@ recorded trace/log stream to a different OTLP backend without taking over the
 main OTel runtime:
 
 ```ts
+import { propagation } from "@opentelemetry/api";
 import { createIsolatedOtel } from "@photon-ai/otel";
 
 const auditOtel = createIsolatedOtel({
   endpoint: "https://audit-collector.example.com",
   serviceName: "audit-service",
   serviceVersion: "1.2.3",
+  baggageHeader: "x-audit-baggage",
   traceparentHeader: "x-audit-traceparent",
 });
 const auditLogger = auditOtel.createLogger("example.audit");
 
-await auditOtel.withSpan("audit.write", async () => {
-  auditLogger.emit({ body: "writing audit entry" });
+const baggage = propagation.createBaggage({
+  "audit.tenant.id": { value: "tenant-123" },
 });
+const baggageContext = propagation.setBaggage(
+  auditOtel.propagation.capture(),
+  baggage
+);
+
+await auditOtel.propagation.run(baggageContext, () =>
+  auditOtel.withSpan("audit.write", async () => {
+    auditLogger.emit({ body: "writing audit entry" });
+  })
+);
 
 await auditOtel.shutdown();
 ```
@@ -143,8 +155,21 @@ The isolated runtime has its own providers, processors, exporters, Resource, and
 read the main `OTEL_EXPORTER_OTLP_*` variables, add `deployment.environment`, or
 require `setupOtel()`.
 
-Its propagation helper carries only its isolated trace context through the
-configured `traceparentHeader`; it never changes the standard `traceparent`.
+Its propagation helper carries isolated trace context through the configured
+`traceparentHeader`. When `baggageHeader` is present, `inject()` and `extract()`
+also serialize standard OTel Baggage through that private carrier. They never
+change the standard `traceparent` or `baggage` headers used by main OTel.
+
+The runtime does not add a second Baggage API. Use
+`@opentelemetry/api`'s `createBaggage()` / `setBaggage()` on the Context returned
+by `propagation.capture()`, then activate the returned immutable Context with
+the isolated `propagation.run()` as shown above.
+
+If an isolated Span callback throws, the runtime marks the Span `ERROR` and
+rethrows the same value without automatically recording its type, message, or
+stack. Call `auditOtel.recordError(error)` inside the active callback when those
+exception details should be exported. Calling it outside a local recording Span
+is a diagnostic no-op.
 
 ### Logger signatures
 

src/isolated-runtime.ts

@@ -6,6 +6,7 @@ import {
   defaultTextMapSetter,
   diag,
   INVALID_SPAN_CONTEXT,
+  propagation as otelPropagation,
   ROOT_CONTEXT,
   type Span,
   type SpanOptions,
@@ -14,7 +15,10 @@ import {
 } from "@opentelemetry/api";
 import type { Logger, LogRecord } from "@opentelemetry/api-logs";
 import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import {
+  W3CBaggagePropagator,
+  W3CTraceContextPropagator,
+} from "@opentelemetry/core";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import {
@@ -38,6 +42,7 @@ import {
 } from "./service-resource";
 
 const INSTRUMENTATION_SCOPE = "@photon-ai/otel";
+const BAGGAGE_KEY = "baggage";
 const TRACEPARENT_KEY = "traceparent";
 
 // biome-ignore assist/source/useSortedInterfaceMembers: required options precede optional configuration.
@@ -47,16 +52,18 @@ export interface IsolatedOtelOptions extends ServiceResourceOptions {
    * runtime. Standard main OTel environment variables do not override it.
    */
   endpoint: string;
-  /** Private carrier header; the standard `traceparent` name is rejected. */
+  /** Private trace carrier; standard `traceparent` and `baggage` are rejected. */
   traceparentHeader: string;
+  /** Optional private W3C Baggage carrier; standard `baggage` is untouched. */
+  baggageHeader?: string;
   /** Optional OTLP transport headers, typically used for Collector auth. */
   headers?: Record<string, string>;
 }
 
 /** Transport-only options; the Resource is supplied separately. */
 type IsolatedOtelTransport = Pick<
   IsolatedOtelOptions,
-  "endpoint" | "headers" | "traceparentHeader"
+  "baggageHeader" | "endpoint" | "headers" | "traceparentHeader"
 >;
 
 export interface IsolatedOtelHandle {
@@ -78,6 +85,8 @@ export interface IsolatedOtelHandle {
     /** Run a callback in this runtime's isolated async context. */
     run: <T>(captured: Context, fn: () => T) => T;
   };
+  /** Explicitly record exception details on the current local recording Span. */
+  recordError(error: unknown): void;
   shutdown(): Promise<void>;
   /** Run a callback with a Span active only in this runtime's private Context. */
   withActiveSpan<T>(
@@ -127,21 +136,51 @@ export const createIsolatedOtelRuntime = (
   if (!(endpointProtocol === "http:" || endpointProtocol === "https:")) {
     throw new TypeError("createIsolatedOtel: endpoint must use http or https");
   }
-  const traceparentHeader = options.traceparentHeader;
-  try {
-    if (!traceparentHeader) {
-      throw new TypeError("traceparentHeader is empty");
+  const validateHeaderName = (
+    headerName: string,
+    optionName: "baggageHeader" | "traceparentHeader"
+  ): void => {
+    try {
+      if (!headerName) {
+        throw new TypeError(`${optionName} is empty`);
+      }
+      new Headers().set(headerName, "validate");
+    } catch {
+      throw new TypeError(
+        `createIsolatedOtel: ${optionName} must be a valid HTTP header name`
+      );
     }
-    new Headers().set(traceparentHeader, "validate");
-  } catch {
+  };
+
+  const traceparentHeader = options.traceparentHeader;
+  validateHeaderName(traceparentHeader, "traceparentHeader");
+  const normalizedTraceparentHeader = traceparentHeader.toLowerCase();
+  if (
+    normalizedTraceparentHeader === TRACEPARENT_KEY ||
+    normalizedTraceparentHeader === BAGGAGE_KEY
+  ) {
     throw new TypeError(
-      "createIsolatedOtel: traceparentHeader must be a valid HTTP header name"
+      "createIsolatedOtel: traceparentHeader must not be traceparent or baggage"
     );
   }
-  if (traceparentHeader.toLowerCase() === TRACEPARENT_KEY) {
-    throw new TypeError(
-      "createIsolatedOtel: traceparentHeader must not be traceparent"
-    );
+
+  const baggageHeader = options.baggageHeader;
+  if (baggageHeader !== undefined) {
+    validateHeaderName(baggageHeader, "baggageHeader");
+    const normalizedBaggageHeader = baggageHeader.toLowerCase();
+    if (
+      normalizedBaggageHeader === TRACEPARENT_KEY ||
+      normalizedBaggageHeader === BAGGAGE_KEY
+    ) {
+      throw new TypeError(
+        "createIsolatedOtel: baggageHeader must not be traceparent or baggage"
+      );
+    }
+    if (normalizedBaggageHeader === normalizedTraceparentHeader) {
+      throw new TypeError(
+        "createIsolatedOtel: baggageHeader must differ from traceparentHeader"
+      );
+    }
   }
   const headers = options.headers ? { ...options.headers } : undefined;
   const traceEndpoint = resolveOtlpEndpoint("traces", endpoint, {});
@@ -172,50 +211,88 @@ export const createIsolatedOtelRuntime = (
   });
   const contextManager = new AsyncLocalStorageContextManager().enable();
   const localSpanKey = createContextKey("@photon-ai/isolated-otel.local-span");
+  const baggagePropagator = new W3CBaggagePropagator();
   const traceContextPropagator = new W3CTraceContextPropagator();
   const tracer = tracerProvider.getTracer(INSTRUMENTATION_SCOPE);
   let shutdownPromise: Promise<void> | undefined;
 
   const propagation: IsolatedOtelHandle["propagation"] = {
     capture: () => contextManager.active(),
     extract: (headersObject) => {
-      const value = headersObject.get(traceparentHeader);
-      if (!value) {
-        return;
+      let extracted = ROOT_CONTEXT;
+      let foundContext = false;
+
+      const traceValue = headersObject.get(traceparentHeader);
+      if (traceValue) {
+        try {
+          const traceExtracted = traceContextPropagator.extract(
+            extracted,
+            { [TRACEPARENT_KEY]: traceValue },
+            defaultTextMapGetter
+          );
+          const spanContext = trace.getSpanContext(traceExtracted);
+          if (spanContext && trace.isSpanContextValid(spanContext)) {
+            extracted = traceExtracted;
+            foundContext = true;
+          } else {
+            reportDiagnostic("ignored invalid isolated trace header");
+          }
+        } catch (error) {
+          reportDiagnostic("ignored invalid isolated trace header", error);
+        }
       }
-      try {
-        const extracted = traceContextPropagator.extract(
-          ROOT_CONTEXT,
-          { [TRACEPARENT_KEY]: value },
-          defaultTextMapGetter
-        );
-        const spanContext = trace.getSpanContext(extracted);
-        if (spanContext && trace.isSpanContextValid(spanContext)) {
-          return extracted;
+
+      const baggageValue = baggageHeader
+        ? headersObject.get(baggageHeader)
+        : undefined;
+      if (baggageValue) {
+        try {
+          const baggageExtracted = baggagePropagator.extract(
+            extracted,
+            { [BAGGAGE_KEY]: baggageValue },
+            defaultTextMapGetter
+          );
+          const baggage = otelPropagation.getBaggage(baggageExtracted);
+          if (baggage && baggage.getAllEntries().length > 0) {
+            extracted = baggageExtracted;
+            foundContext = true;
+          } else {
+            reportDiagnostic("ignored invalid isolated baggage header");
+          }
+        } catch (error) {
+          reportDiagnostic("ignored invalid isolated baggage header", error);
         }
-        reportDiagnostic("ignored invalid isolated trace header");
-        return;
-      } catch (error) {
-        reportDiagnostic("ignored invalid isolated trace header", error);
-        return;
       }
+
+      return foundContext ? extracted : undefined;
     },
     inject: (headersObject, captured) => {
+      const active = captured ?? contextManager.active();
       try {
         headersObject.delete(traceparentHeader);
         const carrier: Record<string, string> = {};
-        traceContextPropagator.inject(
-          captured ?? contextManager.active(),
-          carrier,
-          defaultTextMapSetter
-        );
+        traceContextPropagator.inject(active, carrier, defaultTextMapSetter);
         const value = carrier[TRACEPARENT_KEY];
         if (value) {
           headersObject.set(traceparentHeader, value);
         }
       } catch (error) {
         reportDiagnostic("failed to inject isolated trace header", error);
       }
+
+      if (baggageHeader) {
+        try {
+          headersObject.delete(baggageHeader);
+          const carrier: Record<string, string> = {};
+          baggagePropagator.inject(active, carrier, defaultTextMapSetter);
+          const value = carrier[BAGGAGE_KEY];
+          if (value) {
+            headersObject.set(baggageHeader, value);
+          }
+        } catch (error) {
+          reportDiagnostic("failed to inject isolated baggage header", error);
+        }
+      }
     },
     run: (captured, fn) => contextManager.with(captured, fn),
   };
@@ -244,14 +321,9 @@ export const createIsolatedOtelRuntime = (
         return await fn(span);
       } catch (error) {
         try {
-          span.recordException(error instanceof Error ? error : String(error));
-          span.setAttribute(
-            "error.type",
-            error instanceof Error ? error.constructor.name : typeof error
-          );
           span.setStatus({ code: SpanStatusCode.ERROR });
         } catch (telemetryError) {
-          reportDiagnostic("failed to record Span error", telemetryError);
+          reportDiagnostic("failed to set Span error status", telemetryError);
         }
         throw error;
       } finally {
@@ -294,6 +366,46 @@ export const createIsolatedOtelRuntime = (
     hasActiveSpan: () =>
       contextManager.active().getValue(localSpanKey) !== undefined,
     propagation,
+    recordError(error) {
+      const span = contextManager.active().getValue(localSpanKey) as
+        | Span
+        | undefined;
+      if (!span?.isRecording()) {
+        reportDiagnostic("ignored recordError outside a local recording Span");
+        return;
+      }
+
+      try {
+        span.setStatus({ code: SpanStatusCode.ERROR });
+      } catch (telemetryError) {
+        reportDiagnostic("failed to set Span error status", telemetryError);
+      }
+
+      let exception: Error | string;
+      let errorType: string;
+      try {
+        exception = error instanceof Error ? error : String(error);
+        errorType =
+          error instanceof Error ? error.constructor.name : typeof error;
+      } catch (telemetryError) {
+        reportDiagnostic(
+          "failed to normalize Span error details",
+          telemetryError
+        );
+        return;
+      }
+
+      try {
+        span.recordException(exception);
+      } catch (telemetryError) {
+        reportDiagnostic("failed to record Span exception", telemetryError);
+      }
+      try {
+        span.setAttribute("error.type", errorType);
+      } catch (telemetryError) {
+        reportDiagnostic("failed to set Span error type", telemetryError);
+      }
+    },
     shutdown() {
       if (!shutdownPromise) {
         shutdownPromise = (async () => {