@decocms/blocks 7.62.5 → 7.63.0

package/package.json

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

package/src/middleware/observability.ts

@@ -282,6 +282,10 @@ export const MetricNames = {
   // Labels on this counter use short keys (status/profile/layer/provider) —
   // the metric name already provides the deco.cache.* namespace.
   CACHE_REQUESTS: "deco.cache.requests",
+  // Size in bytes of the values moving through a cache, dimensioned by `op`.
+  // Exponential (base-2) aggregation — see METRIC_METADATA for the scale and
+  // why an explicit-bounds histogram is the wrong shape here.
+  CACHE_SIZE: "deco.cache.size",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
   LOADER_ERRORS: "deco.loader.errors",
@@ -339,7 +343,21 @@ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
  */
 export const METRIC_METADATA: Record<
   string,
-  { description: string; unit: string; boundaries?: readonly number[] }
+  {
+    description: string;
+    unit: string;
+    boundaries?: readonly number[];
+    /**
+     * Histogram aggregation. Omitted means `"explicit"` — bucket into
+     * `boundaries`. `"exponential"` selects an OTel base-2 exponential
+     * histogram at {@link scale}, where bucket `i` covers
+     * `(2^(2^-scale))^i .. ^(i+1)]`. Adapters that don't implement it are free
+     * to keep treating the metric as an ordinary histogram.
+     */
+    aggregation?: "explicit" | "exponential";
+    /** Exponential-histogram scale. Fixed per metric; adapters never rescale. */
+    scale?: number;
+  }
 > = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
     description: "Duration of HTTP server requests handled at the Worker entry point.",
@@ -355,6 +373,19 @@ export const METRIC_METADATA: Record<
     description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
     unit: "{request}",
   },
+  [MetricNames.CACHE_SIZE]: {
+    description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
+    unit: "By",
+    // Exponential rather than explicit bounds: entries span 512 B (the
+    // cachedLoader floor) to the 32 MB cap — five decades. Any fixed bound set
+    // wide enough for the top is useless at the bottom.
+    aggregation: "exponential",
+    // scale -1 => base 4, so buckets land on 512 B · 2 K · 8 K · 32 K · 128 K ·
+    // 512 K · 2 M · 8 M · 32 M: ~9 buckets over the real range, ~1.7 per
+    // decade. scale 0 (base 2) would double the series count without saying
+    // anything new about a size distribution.
+    scale: -1,
+  },
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
     unit: "s",
@@ -590,6 +621,22 @@ export function recordCacheMetric(
   m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
 }
 
+/**
+ * Record the size of a value moving through a cache, in BYTES — not seconds,
+ * so unlike the duration helpers this one does not divide.
+ *
+ * `profile` deliberately reuses the label key {@link recordCacheMetric} already
+ * uses for the `cachedLoader` layer (there it carries the loader name), so
+ * `deco.cache.size` joins `deco.cache.requests{layer="cachedLoader"}` on
+ * `profile` with no renaming in the query.
+ *
+ * Only `op: "set"` is emitted today; the label exists so a future read-side
+ * measurement lands on the same series without a breaking dashboard change.
+ */
+export function recordCacheSizeMetric(bytes: number, profile: string, op: "set" | "get" = "set") {
+  getState().meter?.histogramRecord?.(MetricNames.CACHE_SIZE, bytes, { op, profile });
+}
+
 /**
  * Labels for the outbound commerce sample recorded on
  * `http.client.request.duration`. Owned by the framework so apps-start (and

package/src/sdk/cachedLoader.ts

@@ -13,6 +13,7 @@
 
 import {
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordLoaderError,
   recordLoaderMetric,
   withTracing,
@@ -171,7 +172,13 @@ function estimateBytes(value: unknown): number {
   }
 }
 
-function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
+/**
+ * The single write path into the cache — both the cold-miss and the SWR
+ * background-refresh callers route through here, which is why the size metric
+ * is emitted at this chokepoint rather than at each call site.
+ */
+function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string) {
+  recordCacheSizeMetric(entry.estimatedBytes, name);
   const prev = cache.get(key);
   if (prev) cacheBytes -= prev.estimatedBytes;
   cacheBytes += entry.estimatedBytes;
@@ -317,12 +324,16 @@ export function createCachedLoader<TProps, TResult>(
             // Skip the write if a purge cleared the cache mid-refresh — otherwise
             // we'd re-insert pre-purge data the purge was meant to drop.
             if (gen !== cacheGeneration) return;
-            setCacheEntry(cacheKey, {
-              value: result,
-              createdAt: Date.now(),
-              refreshing: false,
-              estimatedBytes: estimateBytes(result),
-            });
+            setCacheEntry(
+              cacheKey,
+              {
+                value: result,
+                createdAt: Date.now(),
+                refreshing: false,
+                estimatedBytes: estimateBytes(result),
+              },
+              name,
+            );
             evictIfNeeded();
           })
           .catch(() => {
@@ -362,12 +373,16 @@ export function createCachedLoader<TProps, TResult>(
         // Skip caching if a purge landed while this loader was in flight — still
         // return the fresh value to the caller, just don't persist a raced entry.
         if (gen === cacheGeneration) {
-          setCacheEntry(cacheKey, {
-            value: result,
-            createdAt: Date.now(),
-            refreshing: false,
-            estimatedBytes: estimateBytes(result),
-          });
+          setCacheEntry(
+            cacheKey,
+            {
+              value: result,
+              createdAt: Date.now(),
+              refreshing: false,
+              estimatedBytes: estimateBytes(result),
+            },
+            name,
+          );
           evictIfNeeded();
         }
         return result;

package/src/sdk/cachedLoaderSizeMetric.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMeter, MetricNames } from "../middleware/observability";
+import { clearLoaderCache, createCachedLoader } from "./cachedLoader";
+
+type Sample = { name: string; value: number; labels?: Record<string, unknown> };
+
+function fakeMeter(samples: Sample[]) {
+  return {
+    counterInc: () => {},
+    gaugeSet: () => {},
+    histogramRecord: (name: string, value: number, labels?: Record<string, unknown>) => {
+      samples.push({ name, value, labels });
+    },
+  };
+}
+
+const sizeSamples = (samples: Sample[]) => samples.filter((s) => s.name === MetricNames.CACHE_SIZE);
+
+describe("deco.cache.size — emitted on every loader cache write", () => {
+  let samples: Sample[];
+
+  beforeEach(() => {
+    clearLoaderCache();
+    samples = [];
+    configureMeter(fakeMeter(samples));
+  });
+
+  afterEach(() => {
+    clearLoaderCache();
+    configureMeter({ counterInc: () => {} }); // drop the recorder
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("records one sample on the cold-miss write, labelled op=set + the loader name", async () => {
+    const cached = createCachedLoader("t/size-miss", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 });
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(1);
+    expect(sizes[0].labels).toEqual({ op: "set", profile: "t/size-miss" });
+    // Bytes, not seconds — and floored at MIN_ENTRY_BYTES for a tiny payload.
+    expect(sizes[0].value).toBe(512);
+  });
+
+  it("does not re-record on a HIT — only writes are measured", async () => {
+    const cached = createCachedLoader("t/size-hit", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write
+    await cached({ id: 1 }); // HIT  -> no write
+
+    expect(sizeSamples(samples)).toHaveLength(1);
+  });
+
+  it("records the SWR background-refresh write too, not just the cold miss", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+
+    const cached = createCachedLoader("t/size-swr", async (p: { id: number }) => ({ v: p.id }), {
+      policy: "stale-while-revalidate",
+      maxAge: 1_000,
+    });
+
+    await cached({ id: 1 }); // MISS -> write #1
+    vi.setSystemTime(new Date("2026-05-18T16:00:05.000Z")); // now stale
+    await cached({ id: 1 }); // STALE-HIT -> background refresh
+    await vi.runAllTimersAsync(); // let the refresh settle
+
+    const sizes = sizeSamples(samples);
+    expect(sizes).toHaveLength(2); // write #2 came from the refresh
+    expect(sizes.every((s) => s.labels?.op === "set")).toBe(true);
+    expect(sizes.every((s) => s.labels?.profile === "t/size-swr")).toBe(true);
+  });
+
+  it("scales with the payload so a fat loader is distinguishable from a thin one", async () => {
+    const big = { blob: "x".repeat(50_000) };
+    const cached = createCachedLoader("t/size-big", async () => big, {
+      policy: "stale-while-revalidate",
+      maxAge: 60_000,
+    });
+
+    await cached({});
+
+    expect(sizeSamples(samples)[0].value).toBeGreaterThan(50_000);
+  });
+});

package/src/sdk/observability.ts

@@ -64,6 +64,7 @@ export {
   type MeterAdapter,
   MetricNames,
   recordCacheMetric,
+  recordCacheSizeMetric,
   recordCommerceMetric,
   recordLoaderError,
   recordLoaderMetric,

package/src/sdk/otelHttpMeter.test.ts

@@ -63,6 +63,15 @@ function buildAdapter(
     nowMs?: () => number;
     onError?: (kind: "flush" | "overflow" | "kind-mismatch", err: unknown) => void;
     histogramBounds?: number[];
+    metricMetadata?: Record<
+      string,
+      {
+        description?: string;
+        unit?: string;
+        aggregation?: "explicit" | "exponential";
+        scale?: number;
+      }
+    >;
   } = {},
 ) {
   return createOtlpHttpMeterAdapter({
@@ -78,6 +87,7 @@ function buildAdapter(
     nowMs: overrides.nowMs,
     onError: overrides.onError,
     histogramBounds: overrides.histogramBounds,
+    metricMetadata: overrides.metricMetadata,
   });
 }
 
@@ -290,3 +300,166 @@ describe("createOtlpHttpMeterAdapter — buffer + flush", () => {
     expect(slow).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Exponential histograms (deco.cache.size)
+// ---------------------------------------------------------------------------
+
+interface ExpHistogramMetric {
+  name: string;
+  unit?: string;
+  histogram?: unknown;
+  exponentialHistogram?: {
+    aggregationTemporality: number;
+    dataPoints: Array<{
+      attributes: Array<{ key: string; value: Record<string, unknown> }>;
+      count: string;
+      sum: number;
+      min: number;
+      max: number;
+      scale: number;
+      zeroCount: string;
+      positive: { offset: number; bucketCounts: string[] };
+    }>;
+  };
+}
+
+function metricsFrom(calls: Array<{ init?: RequestInit }>): ExpHistogramMetric[] {
+  const payload = JSON.parse(calls[0].init!.body as string) as {
+    resourceMetrics: Array<{ scopeMetrics: Array<{ metrics: ExpHistogramMetric[] }> }>;
+  };
+  return payload.resourceMetrics[0].scopeMetrics[0].metrics;
+}
+
+const CACHE_SIZE_META = {
+  "deco.cache.size": {
+    description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
+    unit: "By",
+    aggregation: "exponential" as const,
+    // base 4 — the scale the framework declares for byte sizes.
+    scale: -1,
+  },
+};
+
+describe("createOtlpHttpMeterAdapter — exponential histogram", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("buckets byte sizes at scale -1 and exports OTLP exponentialHistogram", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    // base 4. Bucket i covers (4^i, 4^(i+1)], upper-inclusive:
+    //   512  -> index 4  (256, 1024]
+    //   1024 -> index 4  (256, 1024]  — exact power of the base stays LOW
+    //   4096 -> index 5  (1024, 4096]
+    const labels = { op: "set", profile: "productList" };
+    meter.histogramRecord("deco.cache.size", 512, labels);
+    meter.histogramRecord("deco.cache.size", 1024, labels);
+    meter.histogramRecord("deco.cache.size", 4096, labels);
+
+    await meter.flush();
+
+    const m = metricsFrom(calls)[0];
+    expect(m.name).toBe("deco.cache.size");
+    expect(m.unit).toBe("By");
+    // Must NOT be serialized as an explicit-bounds histogram.
+    expect(m.histogram).toBeUndefined();
+
+    const dp = m.exponentialHistogram!.dataPoints[0];
+    expect(m.exponentialHistogram!.aggregationTemporality).toBe(2); // CUMULATIVE
+    expect(dp.scale).toBe(-1);
+    expect(dp.count).toBe("3");
+    expect(dp.sum).toBe(512 + 1024 + 4096);
+    expect(dp.min).toBe(512);
+    expect(dp.max).toBe(4096);
+    expect(dp.zeroCount).toBe("0");
+    // offset is the index of bucketCounts[0]; two counts in bucket 4, one in 5.
+    expect(dp.positive.offset).toBe(4);
+    expect(dp.positive.bucketCounts).toEqual(["2", "1"]);
+    expect(dp.attributes.map((a) => a.key)).toEqual(["op", "profile"]);
+  });
+
+  it("fills gaps between populated buckets so offset+i stays aligned", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    // 512 -> index 4, 32 MB -> index 12. Everything between must be zero-filled,
+    // otherwise the consumer reads the top bucket at the wrong boundary.
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+    meter.histogramRecord("deco.cache.size", 32 * 1024 * 1024, { op: "set" });
+
+    await meter.flush();
+
+    const dp = metricsFrom(calls)[0].exponentialHistogram!.dataPoints[0];
+    expect(dp.positive.offset).toBe(4);
+    expect(dp.positive.bucketCounts).toEqual(["1", "0", "0", "0", "0", "0", "0", "0", "1"]);
+  });
+
+  it("splits series per attr-key, like the explicit histogram does", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    meter.histogramRecord("deco.cache.size", 512, { op: "set", profile: "a" });
+    meter.histogramRecord("deco.cache.size", 512, { op: "set", profile: "b" });
+
+    await meter.flush();
+
+    expect(metricsFrom(calls)[0].exponentialHistogram!.dataPoints).toHaveLength(2);
+    expect(meter.pendingDatapointCount()).toBe(2);
+  });
+
+  it("folds non-positive observations into zeroCount instead of a bucket", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META });
+
+    meter.histogramRecord("deco.cache.size", 0, { op: "set" });
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+
+    await meter.flush();
+
+    const dp = metricsFrom(calls)[0].exponentialHistogram!.dataPoints[0];
+    expect(dp.zeroCount).toBe("1");
+    expect(dp.count).toBe("2");
+    expect(dp.positive.bucketCounts).toEqual(["1"]);
+  });
+
+  it("leaves histograms without exponential metadata on the explicit-bounds path", async () => {
+    const { impl, calls } = captureFetch();
+    const meter = buildAdapter({
+      fetchImpl: impl,
+      histogramBounds: [10, 100],
+      metricMetadata: CACHE_SIZE_META,
+    });
+
+    meter.histogramRecord("deco.loader.duration", 50, { name: "x" });
+
+    await meter.flush();
+
+    const m = metricsFrom(calls)[0] as ExpHistogramMetric & {
+      histogram?: { dataPoints: Array<{ bucketCounts: string[]; explicitBounds: number[] }> };
+    };
+    expect(m.exponentialHistogram).toBeUndefined();
+    expect(m.histogram!.dataPoints[0].explicitBounds).toEqual([10, 100]);
+    expect(m.histogram!.dataPoints[0].bucketCounts).toEqual(["0", "1", "0"]);
+  });
+
+  it("rejects reusing an exponential-histogram name as a counter", async () => {
+    const onError = vi.fn();
+    const { impl } = captureFetch();
+    const meter = buildAdapter({ fetchImpl: impl, metricMetadata: CACHE_SIZE_META, onError });
+
+    meter.histogramRecord("deco.cache.size", 512, { op: "set" });
+    meter.counterInc("deco.cache.size", 1, { op: "set" });
+
+    expect(onError).toHaveBeenCalledWith("kind-mismatch", expect.any(Error));
+    expect(meter.pendingDatapointCount()).toBe(1);
+  });
+});

package/src/sdk/otelHttpMeter.ts

@@ -84,8 +84,19 @@ export interface OtlpHttpMeterOptions {
    * The framework owns the lookup; callers MUST NOT pass metadata at
    * record time. See `MetricNames` / `METRIC_METADATA` in
    * `middleware/observability.ts`.
+   *
+   * `aggregation: "exponential"` also routes `histogramRecord` for that name
+   * to a base-2 exponential histogram at `scale` — no separate adapter method,
+   * so call sites are identical for both aggregations.
    */
-  metricMetadata?: Record<string, { description?: string; unit?: string }>;
+  metricMetadata?: Record<string, MetricMetadata>;
+}
+
+export interface MetricMetadata {
+  description?: string;
+  unit?: string;
+  aggregation?: "explicit" | "exponential";
+  scale?: number;
 }
 
 export interface OtlpHttpMeter extends MeterAdapter {
@@ -103,7 +114,7 @@ export interface OtlpHttpMeter extends MeterAdapter {
 // Internal buffer shapes
 // ---------------------------------------------------------------------------
 
-type MetricKind = "counter" | "gauge" | "histogram";
+type MetricKind = "counter" | "gauge" | "histogram" | "expHistogram";
 
 interface CounterPoint {
   value: number;
@@ -125,11 +136,26 @@ interface HistogramPoint {
   startTimeUnixNano: string;
 }
 
+interface ExpHistogramPoint {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  zeroCount: number;
+  /** Sparse index -> count. Densified to `positive.bucketCounts` at flush. */
+  buckets: Map<number, number>;
+  attrs: Labels;
+  startTimeUnixNano: string;
+}
+
 interface MetricEntry {
   kind: MetricKind;
   counter?: Map<string, CounterPoint>;
   gauge?: Map<string, GaugePoint>;
   histogram?: Map<string, HistogramPoint>;
+  expHistogram?: Map<string, ExpHistogramPoint>;
+  /** Only set for `expHistogram`, captured from metadata at first record. */
+  scale?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -143,6 +169,18 @@ const DEFAULT_HISTOGRAM_BOUNDS = [
   5, 10, 25, 50, 75, 100, 250, 500, 1000,
 ];
 
+/** Fallback scale when a metric declares `exponential` without one: base 2. */
+const DEFAULT_EXPONENTIAL_SCALE = 0;
+
+/**
+ * Defensive cap on distinct buckets per exponential series. At the scales we
+ * use (base 4 for byte sizes) the real range needs ~9, so hitting this means
+ * the metric is being fed values it wasn't sized for. Rather than let the
+ * sparse Map grow unbounded per isolate, clamp out-of-range indices into the
+ * edge buckets — the distribution's tails stay visible, the memory doesn't.
+ */
+const MAX_EXPONENTIAL_BUCKETS = 160;
+
 export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpHttpMeter {
   const endpoint = options.endpoint;
   const resourceAttributes = options.resourceAttributes;
@@ -206,6 +244,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     const entry: MetricEntry = { kind };
     if (kind === "counter") entry.counter = new Map();
     else if (kind === "gauge") entry.gauge = new Map();
+    else if (kind === "expHistogram") entry.expHistogram = new Map();
     else entry.histogram = new Map();
     metrics.set(name, entry);
     return entry;
@@ -217,6 +256,7 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
       if (entry.counter) n += entry.counter.size;
       if (entry.gauge) n += entry.gauge.size;
       if (entry.histogram) n += entry.histogram.size;
+      if (entry.expHistogram) n += entry.expHistogram.size;
     }
     return n;
   }
@@ -263,6 +303,10 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
   }
 
   function histogramRecord(name: string, value: number, labels?: Labels) {
+    if (metricMetadata[name]?.aggregation === "exponential") {
+      expHistogramRecord(name, value, labels);
+      return;
+    }
     const { entry: existing, isNewName } = checkAdmissibility(name, "histogram");
     if (existing === null && !isNewName) return; // kind mismatch
     const key = attrKey(labels);
@@ -301,6 +345,61 @@ export function createOtlpHttpMeterAdapter(options: OtlpHttpMeterOptions): OtlpH
     point.bucketCounts[bucketIdx] += 1;
   }
 
+  function expHistogramRecord(name: string, value: number, labels?: Labels) {
+    const { entry: existing, isNewName } = checkAdmissibility(name, "expHistogram");
+    if (existing === null && !isNewName) return; // kind mismatch
+    const key = attrKey(labels);
+    const isNewDatapoint = !existing?.expHistogram?.has(key);
+    if (isNewDatapoint && pendingDatapointCount() >= maxBuffer) {
+      onError?.("overflow", new Error(`metric buffer at cap (${maxBuffer}) — dropping "${name}"`));
+      return;
+    }
+    const entry = existing ?? materializeEntry(name, "expHistogram");
+    if (!entry.expHistogram) return;
+    const scale = metricMetadata[name]?.scale ?? DEFAULT_EXPONENTIAL_SCALE;
+    entry.scale = scale;
+    let point = entry.expHistogram.get(key);
+    if (!point) {
+      point = {
+        count: 0,
+        sum: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY,
+        zeroCount: 0,
+        buckets: new Map(),
+        attrs: labels ? { ...labels } : {},
+        startTimeUnixNano: msToNs(isolateStartMs),
+      };
+      entry.expHistogram.set(key, point);
+    }
+    point.count += 1;
+    point.sum += value;
+    if (value < point.min) point.min = value;
+    if (value > point.max) point.max = value;
+
+    // Non-positive values have no base-2 bucket. Per the OTel spec zero goes to
+    // `zeroCount`; we send negatives there too rather than emit a `negative`
+    // range no metric of ours can produce.
+    if (value <= 0) {
+      point.zeroCount += 1;
+      return;
+    }
+
+    // Spec mapping for base 2^(2^-scale): bucket `i` covers (base^i, base^(i+1)],
+    // i.e. upper-inclusive, so an exact power of the base lands in the LOWER
+    // bucket. Hence ceil(...) - 1 and not floor(...).
+    let index = Math.ceil(Math.log2(value) * 2 ** scale) - 1;
+    // Clamp into the existing range once the series is at its bucket budget —
+    // see MAX_EXPONENTIAL_BUCKETS.
+    if (!point.buckets.has(index) && point.buckets.size >= MAX_EXPONENTIAL_BUCKETS) {
+      const indices = [...point.buckets.keys()];
+      const lo = Math.min(...indices);
+      const hi = Math.max(...indices);
+      index = index < lo ? lo : hi;
+    }
+    point.buckets.set(index, (point.buckets.get(index) ?? 0) + 1);
+  }
+
   async function doFlush(): Promise<void> {
     if (metrics.size === 0) return;
 
@@ -410,7 +509,7 @@ interface SerializeOpts {
   scopeVersion: string;
   histogramBounds: number[];
   flushAtNs: string;
-  metricMetadata: Record<string, { description?: string; unit?: string }>;
+  metricMetadata: Record<string, MetricMetadata>;
 }
 
 function serializeOtlp(
@@ -482,6 +581,44 @@ function serializeOtlp(
           dataPoints,
         },
       });
+    } else if (entry.kind === "expHistogram" && entry.expHistogram) {
+      const dataPoints: unknown[] = [];
+      for (const point of entry.expHistogram.values()) {
+        // Densify the sparse index->count map into OTLP's
+        // `positive: { offset, bucketCounts }`: counts run contiguously from
+        // `offset`, so gaps between populated indices must be filled with 0.
+        const indices = [...point.buckets.keys()].sort((a, b) => a - b);
+        const lo = indices[0] ?? 0;
+        const hi = indices[indices.length - 1] ?? -1;
+        const bucketCounts: string[] = [];
+        for (let i = lo; i <= hi; i++) bucketCounts.push(String(point.buckets.get(i) ?? 0));
+        dataPoints.push({
+          attributes: attrsToOtlp(point.attrs),
+          startTimeUnixNano: point.startTimeUnixNano,
+          timeUnixNano: opts.flushAtNs,
+          count: String(point.count),
+          sum: point.sum,
+          min: point.min === Number.POSITIVE_INFINITY ? 0 : point.min,
+          max: point.max === Number.NEGATIVE_INFINITY ? 0 : point.max,
+          scale: entry.scale ?? 0,
+          zeroCount: String(point.zeroCount),
+          // OTLP: bucketCounts[i] counts values in
+          // (base^(offset+i), base^(offset+i+1)] — the same half-open interval
+          // our record-time index uses, so offset is the first index as-is.
+          positive: { offset: lo, bucketCounts },
+          // No `negative` range: every metric on this path is non-negative,
+          // and sub-zero observations are folded into zeroCount at record time.
+        });
+      }
+      otlpMetrics.push({
+        name,
+        description,
+        unit,
+        exponentialHistogram: {
+          aggregationTemporality: 2, // CUMULATIVE
+          dataPoints,
+        },
+      });
     }
   }