@decocms/start 6.0.1 → 6.2.0

package/src/middleware/observability.ts

@@ -239,25 +239,121 @@ export const MetricNames = {
   CACHE_MISS: "cache_miss_total",
   RESOLVE_DURATION_MS: "resolve_duration_ms",
   FETCH_DURATION_MS: "fetch_duration_ms",
+  /**
+   * Per-provider outbound commerce fetch duration. Owned by
+   * `@decocms/start` (not `@decocms/apps`) so every site emits this
+   * histogram unconditionally as soon as it bumps the framework,
+   * regardless of apps-start version. Apps register operation strings
+   * (`vtex.intelligent-search.product_search`,
+   * `shopify.graphql.cart_create`, ...) via `recordCommerceMetric`
+   * below; the framework owns the cardinality contract.
+   *
+   * Canonical labels: `provider`, `operation`, `status_class`, `cached`.
+   * See `recordCommerceMetric` for the full label set and Phase 2 in
+   * `MIGRATION_TOOLING_PLAN.md` for the rationale.
+   */
+  COMMERCE_REQUEST_DURATION_MS: "commerce_request_duration_ms",
 } as const;
 
+/**
+ * Map an HTTP status code to its canonical class label (`2xx` / ... /
+ * `5xx`). Out-of-range numbers (e.g. -1 from a thrown fetch) fall back
+ * to `"unknown"` so dashboards don't break on edge cases.
+ *
+ * Exported because callers occasionally need the same mapping for
+ * non-metric purposes (logging, tail enrichment).
+ */
+export function statusClassFor(status: number): string {
+  if (typeof status !== "number" || !Number.isFinite(status)) return "unknown";
+  if (status < 100 || status >= 600) return "unknown";
+  return `${Math.floor(status / 100)}xx`;
+}
+
+/**
+ * Optional dimensions stamped on `http_requests_total` /
+ * `http_request_duration_ms` / `http_request_errors_total`. All fields
+ * are optional — callers pass what they have, the framework fills in
+ * the rest from defaults.
+ *
+ * Cardinality discipline: every field here is bounded. `route_pattern`
+ * comes from the TanStack router (a closed set), `outcome` is the CF
+ * Workers Observability enum, `cache_decision` / `cache_layer` are
+ * union types declared in this module, `region` is a small set of CF
+ * colo codes. Status is unbounded by spec but bounded in practice; the
+ * `status_class` label bounds the cardinality further for dashboards
+ * that don't need the raw value.
+ */
+export interface RequestMetricLabels {
+  /** TanStack route pattern (`/_products/$slug/p`) — closed set. */
+  route_pattern?: string;
+  /** Cloudflare Workers Observability `outcome` (`ok`, `exception`, ...). */
+  outcome?: string;
+  /** Cache layer + decision when known. */
+  cache_decision?: CacheDecision;
+  cache_layer?: CacheLayer;
+  /** Cloudflare colo (`GRU`, `IAD`, ...). */
+  region?: string;
+  /**
+   * Arbitrary extra labels — callers should avoid this and add fields
+   * to the typed surface above instead. Kept as an escape hatch so
+   * non-canonical experiments don't require a framework release.
+   */
+  extra?: Record<string, string | number | boolean>;
+}
+
 /**
  * Record an HTTP request metric.
- * Call in middleware after the response is produced.
+ *
+ * Call in middleware after the response is produced. Two-call surface
+ * for backward compat:
+ *
+ *   recordRequestMetric(method, path, status, durationMs)
+ *   recordRequestMetric(method, path, status, durationMs, labels)
+ *
+ * The labels argument is optional — sites that haven't bumped to the
+ * Phase 2 metric shape still emit the original three labels
+ * (`method`, `route_pattern`, `status`). Adding labels never changes
+ * existing labels' values; only adds new ones.
  */
 export function recordRequestMetric(
   method: string,
   path: string,
   status: number,
   durationMs: number,
+  labels?: RequestMetricLabels,
 ) {
   const m = getState().meter;
   if (!m) return;
-  const labels: Labels = { method, path: normalizePath(path), status };
-  m.counterInc(MetricNames.HTTP_REQUESTS_TOTAL, 1, labels);
-  m.histogramRecord?.(MetricNames.HTTP_REQUEST_DURATION_MS, durationMs, labels);
+  // Cardinality discipline:
+  //   - `method`: small (GET, POST, ...).
+  //   - `route_pattern`: closed set (caller-supplied) OR normalized path
+  //     (fallback). Either way bounded.
+  //   - `status`: full HTTP code (bounded ~50 values in practice).
+  //   - `status_class`: 5-element enum (2xx / 3xx / 4xx / 5xx / unknown).
+  //   - `outcome`: CF outcome enum (~7 values).
+  //   - `cache_decision`: 5-element enum.
+  //   - `cache_layer`: 3-element enum (edge / cachedLoader / vtex-swr).
+  //   - `region`: ~250 CF colo codes worldwide.
+  // Total combinations are bounded — safe for unbounded series on
+  // ClickHouse but operators should still avoid grouping by `region`
+  // unless explicitly needed.
+  const merged: Labels = {
+    method,
+    route_pattern: labels?.route_pattern ?? normalizePath(path),
+    status,
+    status_class: statusClassFor(status),
+  };
+  if (labels?.outcome) merged.outcome = labels.outcome;
+  if (labels?.cache_decision) merged.cache_decision = labels.cache_decision;
+  if (labels?.cache_layer) merged.cache_layer = labels.cache_layer;
+  if (labels?.region) merged.region = labels.region;
+  if (labels?.extra) {
+    for (const [k, v] of Object.entries(labels.extra)) merged[k] = v;
+  }
+  m.counterInc(MetricNames.HTTP_REQUESTS_TOTAL, 1, merged);
+  m.histogramRecord?.(MetricNames.HTTP_REQUEST_DURATION_MS, durationMs, merged);
   if (status >= 500) {
-    m.counterInc(MetricNames.HTTP_REQUEST_ERRORS, 1, labels);
+    m.counterInc(MetricNames.HTTP_REQUEST_ERRORS, 1, merged);
   }
 }
 
@@ -272,22 +368,45 @@ export function recordRequestMetric(
  */
 export type CacheDecision = "HIT" | "STALE-HIT" | "STALE-ERROR" | "MISS" | "BYPASS";
 
+/**
+ * Where the cache lives. Phase 2 label expansion (D-11).
+ *  - `edge`         — Cloudflare Cache API (HTML pages, server-fn responses)
+ *  - `cachedLoader` — In-memory per-isolate via `sdk/cachedLoader.ts`
+ *                     (loader-level SWR, dedup, in-flight)
+ *  - `vtex-swr`     — Apps-side in-memory cache shared by VTEX clients
+ *                     (intelligent-search, cross-selling, etc.)
+ */
+export type CacheLayer = "edge" | "cachedLoader" | "vtex-swr";
+
 /**
  * Record a cache hit/miss metric. Also stamps the decision on the active
  * trace span (when one exists) as `deco.cache.decision` / `deco.cache.profile`
  * so operators can filter ClickStack traces by cache decision directly,
  * without joining to metrics.
  *
- * `decision` is optional — when omitted, the metric still records HIT vs MISS
- * but dashboards can't distinguish SWR/SIE paths. Pass it whenever known.
+ * Backward-compatible signature:
+ *   recordCacheMetric(hit, profile?, decision?)
+ *   recordCacheMetric(hit, profile?, decision?, layer?)
+ *
+ * `decision` is optional — when omitted, the metric still records HIT
+ * vs MISS but dashboards can't distinguish SWR/SIE paths. Pass it
+ * whenever known. `layer` defaults to `edge` when called from
+ * workerEntry; cachedLoader / vtex-swr call sites should pass their
+ * value explicitly.
  */
-export function recordCacheMetric(hit: boolean, profile?: string, decision?: CacheDecision) {
+export function recordCacheMetric(
+  hit: boolean,
+  profile?: string,
+  decision?: CacheDecision,
+  layer?: CacheLayer,
+) {
   // Stamp on the active span FIRST so the attribute survives even if the
   // meter is a no-op (e.g. on tests, or in dev without DECO_METRICS).
   const active = getActiveSpan();
   if (active) {
     if (decision) active.setAttribute?.("deco.cache.decision", decision);
     if (profile) active.setAttribute?.("deco.cache.profile", profile);
+    if (layer) active.setAttribute?.("deco.cache.layer", layer);
   }
 
   const m = getState().meter;
@@ -295,9 +414,47 @@ export function recordCacheMetric(hit: boolean, profile?: string, decision?: Cac
   const labels: Labels = {};
   if (profile) labels.profile = profile;
   if (decision) labels.decision = decision;
+  if (layer) labels.layer = layer;
   m.counterInc(hit ? MetricNames.CACHE_HIT : MetricNames.CACHE_MISS, 1, labels);
 }
 
+/**
+ * Labels for `commerce_request_duration_ms`. Owned by the framework so
+ * apps-start (and any future provider package) can register operation
+ * strings without owning the histogram declaration. Phase 2 (D-11).
+ */
+export interface CommerceMetricLabels {
+  /** `vtex`, `shopify`, `wake`, ... — small closed set. */
+  provider: string;
+  /** Per-provider operation, e.g. `intelligent-search.product_search`. */
+  operation: string;
+  /** Set when known (e.g. from the HTTP response). Bounded enum. */
+  status_class?: string;
+  /** Whether the underlying fetch was served from a cache. */
+  cached?: boolean;
+}
+
+/**
+ * Record a commerce / outbound-fetch duration sample. No-op when no
+ * meter is configured. The metric name is constant
+ * (`commerce_request_duration_ms`) — providers vary by the `provider`
+ * label, not by name, so dashboards aggregate cleanly across the fleet.
+ */
+export function recordCommerceMetric(
+  durationMs: number,
+  labels: CommerceMetricLabels,
+) {
+  const m = getState().meter;
+  if (!m) return;
+  const merged: Labels = {
+    provider: labels.provider,
+    operation: labels.operation,
+  };
+  if (labels.status_class) merged.status_class = labels.status_class;
+  if (typeof labels.cached === "boolean") merged.cached = labels.cached;
+  m.histogramRecord?.(MetricNames.COMMERCE_REQUEST_DURATION_MS, durationMs, merged);
+}
+
 function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
   return path

package/src/sdk/cachedLoader.ts

@@ -99,13 +99,13 @@ export function createCachedLoader<TProps, TResult>(
     const inflight = inflightRequests.get(cacheKey);
     if (inflight) {
       // Treat in-flight dedup as a cache hit — avoided the origin call.
-      recordCacheMetric(true, name);
+      recordCacheMetric(true, name, undefined, "cachedLoader");
       return inflight as Promise<TResult>;
     }
 
     if (isDev) {
       // Dev mode: no caching, but still useful to count attempts.
-      recordCacheMetric(false, name);
+      recordCacheMetric(false, name, undefined, "cachedLoader");
       const promise = withTracing(
         "deco.cachedLoader",
         () => loaderFn(props).finally(() => inflightRequests.delete(cacheKey)),
@@ -121,20 +121,20 @@ export function createCachedLoader<TProps, TResult>(
 
     if (policy === "no-cache") {
       if (entry && !isStale) {
-        recordCacheMetric(true, name);
+        recordCacheMetric(true, name, "HIT", "cachedLoader");
         return entry.value;
       }
     }
 
     if (policy === "stale-while-revalidate") {
       if (entry && !isStale) {
-        recordCacheMetric(true, name);
+        recordCacheMetric(true, name, "HIT", "cachedLoader");
         return entry.value;
       }
 
       if (entry && isStale && !entry.refreshing) {
         // Stale-while-revalidate hit: serve stale, refresh in background.
-        recordCacheMetric(true, name);
+        recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
         entry.refreshing = true;
         loaderFn(props)
           .then((result) => {
@@ -156,14 +156,17 @@ export function createCachedLoader<TProps, TResult>(
       }
 
       if (entry) {
-        recordCacheMetric(true, name);
+        // Past SIE window — still serve the stale value once but mark
+        // the decision as STALE-ERROR so dashboards can distinguish
+        // this from healthy SWR.
+        recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
         return entry.value;
       }
     }
 
     // Cache miss — emit metric, then run loader inside a span so individual
     // slow loaders are visible in traces.
-    recordCacheMetric(false, name);
+    recordCacheMetric(false, name, "MISS", "cachedLoader");
     const promise = withTracing("deco.cachedLoader", () => loaderFn(props), {
       "deco.loader": name,
       "deco.cache.policy": policy,

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,