@decocms/blocks 7.37.4 → 7.37.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.37.4",
+  "version": "7.37.5",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/middleware/observability.test.ts

@@ -7,9 +7,11 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   configureMeter,
-  normalizePath,
+  DURATION_BUCKET_BOUNDARIES_SECONDS,
+  METRIC_METADATA,
   type MeterAdapter,
   MetricNames,
+  normalizePath,
   recordCacheMetric,
   recordCommerceMetric,
   recordRequestMetric,
@@ -258,6 +260,46 @@ describe("recordCommerceMetric (D-11)", () => {
   });
 });
 
+/**
+ * Guards the unit/bucket agreement. Durations are recorded in seconds, but the
+ * OTel SDK's default explicit buckets are milliseconds
+ * (`[0, 5, 10, 25, 50, 75, 100, 250, 500, 1000]`). A duration metric that ships
+ * without `boundaries` inherits those defaults and files ~100% of real traffic
+ * into the first bucket, which silently destroys every quantile computed from
+ * it. These assertions exist so that regression fails here instead of in a
+ * dashboard six months later.
+ */
+describe("METRIC_METADATA duration buckets", () => {
+  it("declares second-scale boundaries for every metric measured in seconds", () => {
+    const secondValued = Object.entries(METRIC_METADATA).filter(
+      ([, meta]) => meta.unit === "s",
+    );
+
+    expect(secondValued.length).toBeGreaterThan(0);
+
+    for (const [name, meta] of secondValued) {
+      expect(meta.boundaries, `${name} must declare boundaries`).toBeDefined();
+      // A millisecond-scaled bucket set starts at 5; a second-scaled one starts
+      // well below 1. This is the exact mistake being guarded against.
+      expect(meta.boundaries![0], `${name} boundaries look like milliseconds`)
+        .toBeLessThan(1);
+    }
+  });
+
+  it("keeps boundaries sorted ascending and free of duplicates", () => {
+    const b = DURATION_BUCKET_BOUNDARIES_SECONDS;
+    expect([...b]).toEqual([...new Set(b)]);
+    expect([...b]).toEqual([...b].sort((x, y) => x - y));
+  });
+
+  it("covers the latency range real traffic falls in", () => {
+    // Observed production averages sat between 0.14s and 0.49s, with a tail
+    // past 10s on uncached loader paths. Buckets must resolve both ends.
+    expect(DURATION_BUCKET_BOUNDARIES_SECONDS.some((x) => x <= 0.05)).toBe(true);
+    expect(DURATION_BUCKET_BOUNDARIES_SECONDS.some((x) => x >= 10)).toBe(true);
+  });
+});
+
 /**
  * `http.route` is the highest-cardinality risk on the highest-volume metric.
  * These cases are the real paths measured on production when the label reached

package/src/middleware/observability.ts

@@ -27,7 +27,23 @@
  *
  * configureMeter({
  *   counterInc: (name, value, labels) => metrics.getMeter("deco").createCounter(name).add(value, labels),
- *   histogramRecord: (name, value, labels) => metrics.getMeter("deco").createHistogram(name).record(value, labels),
+ *   histogramRecord: (name, value, labels) => {
+ *     // METRIC_METADATA carries the unit AND the bucket boundaries. Forwarding
+ *     // `boundaries` to `advice` is required, not optional: durations are
+ *     // recorded in seconds and the SDK's default buckets are milliseconds, so
+ *     // an adapter that omits it files everything into the first bucket and
+ *     // every quantile reads back as ~0.
+ *     const meta = METRIC_METADATA[name];
+ *     metrics.getMeter("deco")
+ *       .createHistogram(name, {
+ *         unit: meta?.unit,
+ *         description: meta?.description,
+ *         advice: meta?.boundaries
+ *           ? { explicitBucketBoundaries: [...meta.boundaries] }
+ *           : undefined,
+ *       })
+ *       .record(value, labels);
+ *   },
  * });
  * ```
  */
@@ -271,23 +287,69 @@ export const MetricNames = {
   LOADER_ERRORS: "deco.loader.errors",
 } as const;
 
+/**
+ * Explicit bucket boundaries, in SECONDS, for every duration histogram declared
+ * in {@link METRIC_METADATA}.
+ *
+ * These exist because the unit and the buckets are configured in two different
+ * places and had drifted apart. The record helpers divide by 1000, so values
+ * arrive in seconds — correct per SemConv. But the OTel SDK's *default*
+ * boundaries are `[0, 5, 10, 25, 50, 75, 100, 250, 500, 1000]`, which are
+ * milliseconds. An adapter that calls `createHistogram(name)` without an
+ * `advice` therefore files every sub-5-second observation into the first bucket.
+ *
+ * Measured on the production ClickHouse before this change: 99.8%–99.95% of all
+ * observations on `http.server.request.duration` (78.7M/hour),
+ * `http.client.request.duration`, `deco.loader.duration` and
+ * `deco.cms.resolve.duration` sat in bucket 1, so every quantile read back as
+ * ~0 and the latency dashboards had to fall back to tail-sampled traces.
+ *
+ * Values are the SemConv-recommended defaults for HTTP duration histograms.
+ */
+export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
+  0.005,
+  0.01,
+  0.025,
+  0.05,
+  0.075,
+  0.1,
+  0.25,
+  0.5,
+  0.75,
+  1,
+  2.5,
+  5,
+  7.5,
+  10,
+];
+
 /**
  * Per-metric metadata emitted in the OTLP payload's `description` and
  * `unit` fields. Durations are normalized to **seconds at the source** (OTel
  * semconv), matching the deco-cx/deco framework — NOT converted downstream in
  * the collector. Callers still pass milliseconds; the record helpers divide.
  *
+ * `boundaries`, when present, MUST be forwarded to the histogram's `advice` at
+ * creation time — the unit alone does not tell the SDK how to bucket, and its
+ * defaults assume milliseconds. See
+ * {@link DURATION_BUCKET_BOUNDARIES_SECONDS}.
+ *
  * Keep keys aligned with `MetricNames` values so a missing entry is a
  * type error at compile time when a new metric ships without metadata.
  */
-export const METRIC_METADATA: Record<string, { description: string; unit: string }> = {
+export const METRIC_METADATA: Record<
+  string,
+  { description: string; unit: string; boundaries?: readonly number[] }
+> = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
     description: "Duration of HTTP server requests handled at the Worker entry point.",
     unit: "s",
+    boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
   },
   [MetricNames.HTTP_CLIENT_REQUEST_DURATION]: {
     description: "Duration of outbound HTTP client requests (commerce, generic fetch).",
     unit: "s",
+    boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
   },
   [MetricNames.CACHE_REQUESTS]: {
     description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
@@ -296,10 +358,12 @@ export const METRIC_METADATA: Record<string, { description: string; unit: string
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
     unit: "s",
+    boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
   },
   [MetricNames.LOADER_DURATION]: {
     description: "Per-loader execution duration, emitted by cachedLoader.",
     unit: "s",
+    boundaries: DURATION_BUCKET_BOUNDARIES_SECONDS,
   },
   [MetricNames.LOADER_ERRORS]: {
     description: "Per-loader error count.",