@decocms/start 6.0.1 → 6.1.0

package/src/sdk/logger.test.ts

@@ -266,6 +266,105 @@ describe("serializeError", () => {
   });
 });
 
+describe("request.id stamping (Phase 1, D-9)", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("stamps request.id from RequestContext on every log line emitted inside a request scope", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const reqWithId = new Request("https://example.com/", {
+      headers: { "x-request-id": "client-supplied-uuid" },
+    });
+    await RequestContext.run(reqWithId, async () => {
+      logger.info("inside-scope", { custom: "yes" });
+    });
+    // Outside the scope, no request.id is stamped — the fast path stays
+    // fast (no allocation, no key) when RequestContext.requestId is null.
+    logger.info("outside-scope", { custom: "no" });
+
+    expect(seen[0]).toMatchObject({
+      "request.id": "client-supplied-uuid",
+      custom: "yes",
+    });
+    expect(seen[1]).toEqual({ custom: "no" });
+    expect(seen[1]).not.toHaveProperty("request.id");
+  });
+
+  it("prefers caller-supplied request.id over the auto-generated one", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/", {
+      headers: { "x-request-id": "from-headers" },
+    });
+
+    await RequestContext.run(req, async () => {
+      // Caller can still override by passing the key directly in attrs.
+      logger.info("override", { "request.id": "explicit-from-caller" });
+    });
+
+    expect(seen[0]?.["request.id"]).toBe("explicit-from-caller");
+  });
+
+  it("falls back to cf-ray when x-request-id is absent", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/", {
+      headers: { "cf-ray": "8a1b2c3d4e5f6a7b" },
+    });
+
+    await RequestContext.run(req, async () => {
+      logger.info("cf-ray-stamped");
+    });
+
+    expect(seen[0]?.["request.id"]).toBe("8a1b2c3d4e5f6a7b");
+  });
+
+  it("generates a fresh UUID when neither header is set", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/");
+
+    await RequestContext.run(req, async () => {
+      logger.info("uuid-stamped");
+    });
+
+    const stamped = seen[0]?.["request.id"];
+    expect(typeof stamped).toBe("string");
+    expect((stamped as string).length).toBeGreaterThan(8);
+  });
+});
+
 describe("trace correlation", () => {
   afterEach(() => {
     configureLogger(defaultLoggerAdapter);

package/src/sdk/logger.ts

@@ -25,6 +25,7 @@
  */
 
 import { getActiveSpan } from "./observability";
+import { RequestContext } from "./requestContext";
 
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
@@ -252,20 +253,30 @@ function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): vo
   // to its trace in ClickStack/HyperDX. No active span → no-op; caller
   // attrs always win so explicit `trace_id` overrides keep working.
   const ctx = getActiveSpan()?.spanContext?.();
-  const traceAttrs: Record<string, unknown> | undefined = ctx
-    ? { trace_id: ctx.traceId, span_id: ctx.spanId }
-    : undefined;
-  // Merge order: floor → trace context → caller attrs. Caller wins; trace
-  // context only overrides floor (which never sets trace_id anyway).
+  // Pull request.id from the AsyncLocalStorage-backed RequestContext so
+  // every log line in the request also carries the join key used by
+  // direct-POST metrics + tail-worker rows. Single read, no allocation
+  // when outside a request scope.
+  const requestId = RequestContext.requestId;
+  const requestAttrs: Record<string, unknown> | undefined =
+    ctx || requestId
+      ? {
+          ...(ctx ? { trace_id: ctx.traceId, span_id: ctx.spanId } : {}),
+          ...(requestId ? { "request.id": requestId } : {}),
+        }
+      : undefined;
+  // Merge order: floor → trace / request context → caller attrs. Caller
+  // wins; the request-scoped context only overrides floor keys (which
+  // never set `trace_id` / `request.id` anyway).
   const s = getState();
   const hasFloor = Object.keys(s.attributeFloor).length > 0;
   let merged: Record<string, unknown> | undefined;
-  if (!hasFloor && !traceAttrs && !attrs) {
+  if (!hasFloor && !requestAttrs && !attrs) {
     merged = undefined;
   } else {
     merged = {
       ...(hasFloor ? s.attributeFloor : {}),
-      ...(traceAttrs ?? {}),
+      ...(requestAttrs ?? {}),
       ...(attrs ?? {}),
     };
   }

package/src/sdk/observability.ts

@@ -52,6 +52,8 @@ export {
 // Tracer / meter / request log primitives (re-exported from the middleware)
 export {
   type CacheDecision,
+  type CacheLayer,
+  type CommerceMetricLabels,
   configureMeter,
   configureTracer,
   getActiveSpan,
@@ -62,16 +64,32 @@ export {
   type MeterAdapter,
   MetricNames,
   recordCacheMetric,
+  recordCommerceMetric,
   recordRequestMetric,
+  type RequestMetricLabels,
   type RequestStore,
   type Span,
   setObservabilitySpanStore,
   setSpanAttribute,
+  statusClassFor,
   type TracerAdapter,
   withTracing,
 } from "../middleware/observability";
 // Worker-entry wrapper + adapter wiring
 export { instrumentWorker, type OtelOptions } from "./otel";
+// Direct-POST OTLP trace exporter (Phase 3 / D-12). Exported for sites
+// that need to wire a custom traces endpoint outside `instrumentWorker`,
+// and for the audit tooling that asserts framework spans are flowing.
+export {
+  createOtlpHttpTracerAdapter,
+  newSpanId,
+  newTraceId,
+  type OtlpHttpTracer,
+  type OtlpHttpTracerOptions,
+  parseTraceparent,
+  shouldSampleTrace,
+  type TraceContext,
+} from "./otelHttpTracer";
 // AE meter adapter + runtime env helpers (for tests / custom wiring)
 export {
   type AnalyticsEngineDataset,

package/src/sdk/otel.ts

@@ -61,10 +61,16 @@
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 import { createCompositeLogger, createCompositeMeter } from "./composite";
 import { configureLogger, defaultLoggerAdapter, setLoggerAttributeFloor } from "./logger";
-import { configureMeter, configureTracer } from "./observability";
+import { configureMeter, configureTracer, getActiveSpan } from "./observability";
 import { createAnalyticsEngineMeterAdapter } from "./otelAdapters";
 import { createOtlpHttpErrorLogAdapter, type OtlpHttpErrorLog } from "./otelHttpErrorLog";
 import { createOtlpHttpMeterAdapter, type OtlpHttpMeter } from "./otelHttpMeter";
+import {
+  createOtlpHttpTracerAdapter,
+  type OtlpHttpTracer,
+  type TraceContext,
+} from "./otelHttpTracer";
+import { RequestContext } from "./requestContext";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -98,6 +104,36 @@ export interface OtelOptions {
   otlpErrorLogsEndpointEnvVar?: string;
   /** Set to `false` to disable the OTLP/HTTP error-log exporter explicitly. */
   otlpErrorLogsEnabled?: boolean;
+  /**
+   * Env var name holding the OTLP/HTTP traces endpoint used by the
+   * direct-POST span exporter. Defaults to `"DECO_OTEL_TRACES_ENDPOINT"`.
+   * When set (and `otlpTracesEnabled !== false`), framework `deco.*`
+   * spans created via `withTracing` are captured, sampled, and POSTed
+   * directly to this endpoint. Flushed alongside metrics via
+   * `ctx.waitUntil`.
+   *
+   * Without this endpoint configured, `withTracing` falls back to the
+   * `@opentelemetry/api` global tracer (the legacy CF auto-instrumentation
+   * path). The framework registers BOTH adapters when a traces endpoint
+   * is set so CF auto-spans stay intact AND framework spans get
+   * direct-POSTed to ClickHouse. See Phase 3 in
+   * `MIGRATION_TOOLING_PLAN.md`.
+   */
+  otlpTracesEndpointEnvVar?: string;
+  /** Set to `false` to disable the OTLP/HTTP traces exporter explicitly. */
+  otlpTracesEnabled?: boolean;
+  /**
+   * Head sampling rate for framework spans direct-POSTed via the OTLP
+   * traces endpoint. Default `0.01` matches the CF Destinations
+   * `traces.head_sampling_rate` recommendation. Decisions are consistent
+   * per trace (hash of `trace_id`), so child spans (`deco.cache.lookup`,
+   * `deco.cms.resolvePage`, ...) are kept iff their root
+   * `deco.http.request` span is kept. Set to `1` to capture every trace
+   * (preview / debug only — production cost grows linearly).
+   */
+  otlpTracesSamplingRate?: number;
+  /** Test seam — replace the global `fetch` used by the traces exporter. */
+  otlpTracesFetchImpl?: typeof fetch;
   /**
    * Version of `@decocms/start` to advertise as `deco.runtime.version`
    * on every span and every log line. Falls back to a build-time constant;
@@ -150,6 +186,37 @@ let otlpMeter: OtlpHttpMeter | null = null;
  */
 let otlpErrorLog: OtlpHttpErrorLog | null = null;
 
+/**
+ * Module-level handle to the OTLP/HTTP trace exporter — installed by
+ * `bootObservability` when `DECO_OTEL_TRACES_ENDPOINT` is set on `env`.
+ * Flushed alongside the metrics + error-log exporters via
+ * `ctx.waitUntil(...)` at the end of every request.
+ */
+let otlpTracer: OtlpHttpTracer | null = null;
+
+/**
+ * Per-request inbound W3C trace context, parsed from the `traceparent`
+ * header at request entry. Read by the OTLP trace exporter when it
+ * creates a root span so we honor remote parents and the `sampled`
+ * flag. Stored on a request-scoped slot (via `RequestContext.bag`) so
+ * concurrent requests in the same isolate don't trample each other.
+ */
+const TRACE_CTX_BAG_KEY = "deco.observability.traceContext.v1";
+
+function getRequestTraceContext(): TraceContext | null {
+  return RequestContext.getBag<TraceContext>(TRACE_CTX_BAG_KEY) ?? null;
+}
+
+/**
+ * Public entry point used by `workerEntry.ts` to stash the parsed
+ * traceparent for the OTLP tracer to consume. Exported (not just
+ * module-local) because the parser lives in `otelHttpTracer.ts` and
+ * the call site is `workerEntry.ts`.
+ */
+export function _setRequestTraceContext(ctx: TraceContext | null): void {
+  if (ctx) RequestContext.setBag(TRACE_CTX_BAG_KEY, ctx);
+}
+
 /**
  * Per-span attribute floor — stamped on every span we create via
  * `configureTracer().startSpan(...)`. CF's trace export emits its own
@@ -183,38 +250,13 @@ export function instrumentWorker(
   handler: WorkerHandler,
   options: OtelOptions | ((env: Record<string, unknown>) => OtelOptions) = {},
 ): WorkerHandler {
-  // Bridge our pluggable TracerAdapter onto @opentelemetry/api. Framework
-  // code calls `withTracing("name", fn, { attr: val })`; that delegates here
-  // and lands on `trace.getTracer("@decocms/start").startSpan(...)`.
-  //
-  // CF Workers Tracing (when `observability.traces.enabled = true` in
-  // wrangler) installs its own TracerProvider into the @opentelemetry/api
-  // global, so these spans flow through to the CF dashboard. Without CF
-  // tracing the global tracer is a no-op proxy and the spans simply drop
-  // — same outcome as before, no error.
-  configureTracer({
-    startSpan: (name, attrs) => {
-      const merged = { ...spanAttributeFloor, ...(attrs ?? {}) };
-      const span = trace.getTracer("@decocms/start").startSpan(name, { attributes: merged });
-      return {
-        end: () => span.end(),
-        setError: (error) => {
-          const message = error instanceof Error ? error.message : String(error);
-          if (error instanceof Error) span.recordException(error);
-          span.setStatus({ code: SpanStatusCode.ERROR, message });
-        },
-        setAttribute: (k, v) => span.setAttribute(k, v),
-        spanContext: () => {
-          const ctx = span.spanContext();
-          return {
-            traceId: ctx.traceId,
-            spanId: ctx.spanId,
-            traceFlags: ctx.traceFlags,
-          };
-        },
-      };
-    },
-  });
+  // Default tracer bridge — delegates to `@opentelemetry/api` global. When
+  // `bootObservability` discovers `DECO_OTEL_TRACES_ENDPOINT`, it composes
+  // this bridge with the direct-POST OTLP tracer so framework spans flow to
+  // BOTH the CF dashboard AND ClickHouse (the bridge stays a no-op when CF
+  // tracing isn't configured, which is the common case today). See
+  // `configureTracerStack` below.
+  configureTracer(buildOtelApiTracer());
 
   return {
     async fetch(request, env, ctx) {
@@ -227,11 +269,11 @@ export function instrumentWorker(
       try {
         return await handler.fetch(request, env, ctx);
       } finally {
-        // Drain the OTLP metrics + error-log buffers via ctx.waitUntil
-        // so neither POST blocks the response. Both exporters throttle
-        // themselves per isolate — calling on every request is cheap;
-        // the network only fires when the cooldown elapses or the
-        // buffer fills.
+        // Drain the OTLP metrics + error-log + traces buffers via
+        // ctx.waitUntil so no POST blocks the response. Each exporter
+        // throttles itself per isolate — calling on every request is
+        // cheap; the network only fires when the cooldown elapses or
+        // the buffer fills.
         if (otlpMeter) {
           try {
             ctx.waitUntil(otlpMeter.flush());
@@ -246,11 +288,122 @@ export function instrumentWorker(
             /* swallow */
           }
         }
+        if (otlpTracer) {
+          try {
+            ctx.waitUntil(otlpTracer.flush());
+          } catch {
+            /* swallow */
+          }
+        }
       }
     },
   };
 }
 
+/**
+ * Build the legacy `@opentelemetry/api` global-tracer bridge. Stays a
+ * no-op when no global TracerProvider is registered — same outcome as
+ * the historical configuration.
+ */
+function buildOtelApiTracer(): import("../middleware/observability").TracerAdapter {
+  return {
+    startSpan: (name, attrs) => {
+      const merged = { ...spanAttributeFloor, ...(attrs ?? {}) };
+      const span = trace.getTracer("@decocms/start").startSpan(name, { attributes: merged });
+      return {
+        end: () => span.end(),
+        setError: (error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          if (error instanceof Error) span.recordException(error);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+        },
+        setAttribute: (k, v) => span.setAttribute(k, v),
+        spanContext: () => {
+          const ctx = span.spanContext();
+          return {
+            traceId: ctx.traceId,
+            spanId: ctx.spanId,
+            traceFlags: ctx.traceFlags,
+          };
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Wire the framework tracer. When the OTLP traces endpoint is configured,
+ * compose the direct-POST tracer ALONGSIDE the `@opentelemetry/api` bridge
+ * via a fanout adapter so:
+ *   1. `withTracing` calls feed BOTH adapters.
+ *   2. A child span's `spanContext()` reports the direct-POST span's IDs
+ *      (the bridge is best-effort — if CF tracing isn't installed those
+ *      IDs are zeros anyway).
+ *
+ * When no traces endpoint is configured, fall back to the bridge alone —
+ * preserves the legacy behavior for sites that haven't bumped wrangler.
+ */
+function configureTracerStack(otlpAdapter: OtlpHttpTracer | null): void {
+  const bridge = buildOtelApiTracer();
+  if (!otlpAdapter) {
+    configureTracer(bridge);
+    return;
+  }
+  // Compose. The OTLP adapter is the "primary" (its IDs win for
+  // `spanContext()` because callers downstream use them for trace
+  // propagation). The bridge is best-effort — fed the same name/attrs
+  // so CF Workers Observability still sees the spans if that channel
+  // is enabled in wrangler.jsonc.
+  configureTracer({
+    startSpan(name, attrs) {
+      const merged = { ...spanAttributeFloor, ...(attrs ?? {}) };
+      const primary = otlpAdapter.startSpan(name, merged);
+      const secondary = bridge.startSpan(name, merged);
+      return {
+        end(): void {
+          try {
+            primary.end();
+          } finally {
+            try {
+              secondary.end();
+            } catch {
+              /* swallow */
+            }
+          }
+        },
+        setError(error: unknown): void {
+          try {
+            primary.setError?.(error);
+          } finally {
+            try {
+              secondary.setError?.(error);
+            } catch {
+              /* swallow */
+            }
+          }
+        },
+        setAttribute(key: string, value: string | number | boolean): void {
+          primary.setAttribute?.(key, value);
+          try {
+            secondary.setAttribute?.(key, value);
+          } catch {
+            /* swallow */
+          }
+        },
+        spanContext() {
+          // The OTLP adapter owns the canonical IDs — those are the IDs
+          // we propagate downstream via `traceparent` headers.
+          return primary.spanContext?.() ?? secondary.spanContext?.() ?? {
+            traceId: "",
+            spanId: "",
+            traceFlags: 0,
+          };
+        },
+      };
+    },
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Boot — wires the loggers/meters once (per worker isolate)
 // ---------------------------------------------------------------------------
@@ -391,6 +544,41 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
   // composite becomes a 0-element no-op via createCompositeMeter's filter.
   configureMeter(composedMeter);
 
+  // Traces — direct-POST exporter for framework `deco.*` spans. Without
+  // this, `withTracing` delegates to the no-op `@opentelemetry/api`
+  // global tracer and every framework span silently disappears (the
+  // Phase 3 gap documented in `MIGRATION_TOOLING_PLAN.md`). Same
+  // transport pattern as metrics/error-logs — buffered, sampled by
+  // trace-id hash, flushed via `ctx.waitUntil`.
+  const otlpTracesEnvVar = opts.otlpTracesEndpointEnvVar ?? "DECO_OTEL_TRACES_ENDPOINT";
+  const otlpTracesEndpoint = (env[otlpTracesEnvVar] as string | undefined) ?? "";
+  const otlpTracesEnabled =
+    opts.otlpTracesEnabled !== false && otlpTracesEndpoint.length > 0;
+  if (otlpTracesEnabled) {
+    otlpTracer = createOtlpHttpTracerAdapter({
+      endpoint: otlpTracesEndpoint,
+      resourceAttributes: floor,
+      scopeVersion: decoRuntimeVersion,
+      headSamplingRate: opts.otlpTracesSamplingRate ?? 0.01,
+      fetchImpl: opts.otlpTracesFetchImpl,
+      getActiveSpanForParent: () => getActiveSpan(),
+      getRequestTraceContext,
+      onError: (kind, err) => {
+        defaultLoggerAdapter.log("warn", "otlp traces exporter", {
+          kind,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      },
+    });
+  } else {
+    otlpTracer = null;
+  }
+
+  // Wire the tracer stack — composes the OTLP direct-POST adapter (when
+  // configured) with the @opentelemetry/api bridge. See
+  // `configureTracerStack` for the fanout semantics.
+  configureTracerStack(otlpTracer);
+
   booted = true;
 
   // Single boot-time breadcrumb so operators can confirm the wiring at a
@@ -400,6 +588,7 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
     analyticsEngine: aeEnabled,
     otlpMetrics: otlpEnabled,
     otlpErrorLogs: otlpErrorLogsEnabled,
+    otlpTraces: otlpTracesEnabled,
     runtimeVersion: decoRuntimeVersion,
     deploymentEnvironment,
     ...(serviceVersion ? { serviceVersion } : {}),
@@ -415,6 +604,7 @@ export function _resetBootStateForTests(): void {
   spanAttributeFloor = {};
   otlpMeter = null;
   otlpErrorLog = null;
+  otlpTracer = null;
   setLoggerAttributeFloor({});
 }