@decocms/blocks 7.0.0

package/src/sdk/otelAdapters/clickhouseCollector.ts

@@ -0,0 +1,65 @@
+/**
+ * Placeholder for a future OTel-collector based exporter that ships
+ * logs / metrics / traces from this Worker to a co-deployed OTel Collector
+ * gateway, which in turn batches into ClickHouse.
+ *
+ * **NOT IMPLEMENTED in 5.0.0.** The framework today defaults to CF-native
+ * observability: logs and traces appear in the Cloudflare dashboard
+ * (`observability.{logs,traces}` in `wrangler.jsonc`), and metrics go to
+ * Workers Analytics Engine. When the platform-side ClickHouse + collector
+ * deployment lands, this file gets the real OTLP/HTTP exporter wiring back
+ * — mirror the implementation that lived in `src/sdk/otelAdapters.ts` and
+ * `src/sdk/sampler.ts` at the pre-5.0.0 git tag.
+ *
+ * The expected shape (`endpoint`, optional `headers`, optional `resource`,
+ * `exportIntervalMillis`) is recorded here so site-side bootstrapping code
+ * can compile against the future surface today and we don't churn the
+ * `OtelOptions` type when the implementation lands.
+ *
+ * Reference: https://clickhouse.com/docs/observability/integrating-opentelemetry
+ *
+ * Expected wiring once implemented:
+ *  - Worker → OTLP/HTTP → OTel Collector (gateway, per region)
+ *  - Collector pipelines:
+ *      receivers[otlp] → processors[batch, memory_limiter] → exporters[clickhouse]
+ *  - The Worker uses the collector URL as `endpoint`, NOT a direct
+ *    ClickHouse URL. The collector owns the credentials, retry policy,
+ *    and schema mapping.
+ */
+
+export interface ClickhouseCollectorOptions {
+  /**
+   * OTel Collector OTLP/HTTP endpoint, e.g. `https://otel-collector.internal`.
+   * The Worker never talks to ClickHouse directly — it talks to the collector.
+   */
+  endpoint: string;
+  /** Optional bearer token / mTLS identity headers — collector-defined. */
+  headers?: Record<string, string>;
+  /**
+   * Resource attributes to stamp on every emitted record. Keep narrow
+   * (`service.name`, `deco.runtime.version`, `deployment.environment`) —
+   * higher-cardinality attributes belong on individual spans / log records.
+   */
+  resource?: Record<string, string>;
+  /** Periodic metric reader push interval in ms. Defaults to 60_000 once wired. */
+  exportIntervalMillis?: number;
+}
+
+/**
+ * Returns nothing today — throws to make accidental usage loud and obvious.
+ *
+ * The intended return shape is `{ logger: LoggerAdapter, meter: MeterAdapter,
+ * tracer: TracerAdapter, flush: () => Promise<void> }` so the wiring inside
+ * `instrumentWorker` can compose this with the AE meter (dual-emit) and the
+ * default console logger. None of that ships in 5.0.0.
+ */
+export function createClickhouseCollectorAdapter(_options: ClickhouseCollectorOptions): never {
+  throw new Error(
+    "createClickhouseCollectorAdapter is not implemented in @decocms/start@5.x. " +
+      "ClickHouse + OTel-collector integration is on the roadmap. " +
+      "Until then, use Cloudflare-native observability " +
+      "(observability.{logs,traces} in wrangler.jsonc) plus the Workers " +
+      "Analytics Engine meter wired by instrumentWorker(). Track progress " +
+      "at https://github.com/decocms/deco-start/issues.",
+  );
+}

package/src/sdk/otelAdapters.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Coverage for `createAnalyticsEngineMeterAdapter` and the
+ * `setRuntimeEnv` / `getRuntimeEnv` helpers.
+ *
+ * As of 5.0.0 this file no longer covers `createOtelLoggerAdapter` /
+ * `createOtelMeterAdapter` / `flushOtelProviders` — those exporters were
+ * removed when the framework converged on Cloudflare-native log + trace
+ * capture. AE remains the in-Worker metrics path.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAnalyticsEngineMeterAdapter, setRuntimeEnv } from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+
+describe("createAnalyticsEngineMeterAdapter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("no-ops when binding is missing (does not throw)", () => {
+    const meter = createAnalyticsEngineMeterAdapter({ bindingName: "MISSING" });
+    expect(() => meter.counterInc("foo", 1)).not.toThrow();
+    expect(() => meter.gaugeSet?.("bar", 5)).not.toThrow();
+    expect(() => meter.histogramRecord?.("baz", 100)).not.toThrow();
+  });
+
+  it("writes one data point per call to the resolved binding", () => {
+    const writeDataPoint = vi.fn();
+    const binding = { writeDataPoint };
+
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+
+    meter.counterInc("deco.cache.hits", 1, { profile: "product" });
+    meter.histogramRecord?.("http.server.request.duration", 150, {
+      method: "GET",
+      path: "/",
+      status: 200,
+    });
+    meter.gaugeSet?.("custom_gauge", 7, { region: "gru" });
+
+    expect(writeDataPoint).toHaveBeenCalledTimes(3);
+
+    // Non-HTTP counter falls back to the metric name as the index.
+    expect(writeDataPoint.mock.calls[0]?.[0].indexes).toEqual(["deco.cache.hits"]);
+    expect(writeDataPoint.mock.calls[0]?.[0].doubles).toEqual([1]);
+    expect(writeDataPoint.mock.calls[0]?.[0].blobs?.[0]).toBe("deco.cache.hits");
+
+    // For canonical HTTP server histogram, indexes[0] must be the path.
+    expect(writeDataPoint.mock.calls[1]?.[0].indexes).toEqual(["/"]);
+    expect(writeDataPoint.mock.calls[1]?.[0].doubles).toEqual([150]);
+
+    // Non-HTTP metrics fall back to the metric name as the index.
+    expect(writeDataPoint.mock.calls[2]?.[0].indexes).toEqual(["custom_gauge"]);
+    expect(writeDataPoint.mock.calls[2]?.[0].doubles).toEqual([7]);
+  });
+
+  it("resolves binding via RequestContext when not provided directly", () => {
+    const writeDataPoint = vi.fn();
+    const env = { DECO_METRICS: { writeDataPoint } };
+
+    RequestContext.run(new Request("https://x.example/"), () => {
+      setRuntimeEnv(env);
+      const meter = createAnalyticsEngineMeterAdapter();
+      // Canonical HTTP server histogram → path is promoted to index[0].
+      meter.histogramRecord?.("http.server.request.duration", 1, { path: "/x" });
+      expect(writeDataPoint).toHaveBeenCalledOnce();
+      expect(writeDataPoint.mock.calls[0]?.[0].indexes).toEqual(["/x"]);
+    });
+  });
+
+  it("never throws when binding throws", () => {
+    const binding = {
+      writeDataPoint: () => {
+        throw new Error("AE down");
+      },
+    };
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+    expect(() => meter.counterInc("x", 1)).not.toThrow();
+  });
+
+  it("orders blob columns deterministically by sorted label keys", () => {
+    const writeDataPoint = vi.fn();
+    const binding = { writeDataPoint };
+    const meter = createAnalyticsEngineMeterAdapter({ binding });
+
+    meter.counterInc("metric", 1, { z: "last", a: "first", m: "mid" });
+
+    const blobs = writeDataPoint.mock.calls[0]?.[0].blobs as string[];
+    // blobs[0] is metric name; remaining must follow sorted label-key order: a, m, z
+    expect(blobs).toEqual(["metric", "first", "mid", "last"]);
+  });
+});

package/src/sdk/otelAdapters.ts

@@ -0,0 +1,144 @@
+/**
+ * Metric adapters for `@decocms/start`.
+ *
+ * The OTLP logger and OTLP meter adapters that lived here through 4.x were
+ * removed in 5.0.0. The framework now relies on:
+ *  - Cloudflare's platform-managed log capture (`console.*` → CF dashboard
+ *    via `observability.logs`) for log shipping
+ *  - Cloudflare's auto-instrumented + global-tracer-bridged trace export
+ *    (`observability.traces`) for trace shipping
+ *  - Workers Analytics Engine — implemented in this file — for metrics
+ *
+ * Forwarding to a co-deployed OTel collector (the path to ClickHouse)
+ * lives in `./otelAdapters/clickhouseCollector.ts`. That file is a
+ * documented stub today; the implementation will reintroduce a thin
+ * OTLP/HTTP exporter aimed at the collector — never directly at a
+ * destination — when the collector is deployed.
+ *
+ * The `setRuntimeEnv` / `getRuntimeEnv` helpers stay here because
+ * `workerEntry.ts` and the AE adapter both depend on them.
+ */
+
+import type { MeterAdapter } from "../middleware/observability";
+import { MetricNames } from "../middleware/observability";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Env / binding access
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-request access to the Cloudflare Worker `env` bag. Stashed by
+ * `workerEntry.ts` at the top of every request via
+ * `RequestContext.setBag("__deco_env", env)`.
+ *
+ * Adapters use this to look up the AE binding (or any future binding-driven
+ * destination) without forcing site code to thread `env` through every
+ * call site.
+ */
+const ENV_BAG_KEY = "__deco_env";
+
+export function setRuntimeEnv(env: Record<string, unknown>): void {
+  RequestContext.setBag(ENV_BAG_KEY, env);
+}
+
+export function getRuntimeEnv(): Record<string, unknown> | undefined {
+  return RequestContext.getBag<Record<string, unknown>>(ENV_BAG_KEY);
+}
+
+// ---------------------------------------------------------------------------
+// AnalyticsEngineMeterAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Workers Analytics Engine binding shape. Defined here so we don't need
+ * `@cloudflare/workers-types` as a dep.
+ */
+export interface AnalyticsEngineDataset {
+  writeDataPoint(point: { indexes?: string[]; blobs?: string[]; doubles?: number[] }): void;
+}
+
+export interface AnalyticsEngineMeterAdapterOptions {
+  /** Env var name holding the AE binding. Defaults to "DECO_METRICS". */
+  bindingName?: string;
+  /** Pre-resolved binding (mainly for tests). Bypasses RequestContext lookup. */
+  binding?: AnalyticsEngineDataset;
+}
+
+/**
+ * Writes one Analytics Engine data point per metric call.
+ *
+ * Schema (must stay stable — dashboards and SQL queries depend on it):
+ *  - `indexes[0]`: a low-cardinality dimension. For request metrics that's
+ *    the normalized URL path; for cache/resolve metrics that's the metric
+ *    name itself.
+ *  - `blobs[0]`: metric name (so a single dataset can hold many metrics).
+ *  - `blobs[1..]`: stringified label values, in stable label-name order.
+ *  - `doubles[0]`: the metric value (count, ms, gauge value).
+ *
+ * AE truncates / charges per data point, so this adapter is intentionally
+ * coarse: one point per `counterInc` / `histogramRecord` / `gaugeSet`.
+ */
+export function createAnalyticsEngineMeterAdapter(
+  options: AnalyticsEngineMeterAdapterOptions = {},
+): MeterAdapter {
+  const bindingName = options.bindingName ?? "DECO_METRICS";
+
+  function resolveBinding(): AnalyticsEngineDataset | null {
+    if (options.binding) return options.binding;
+    const env = getRuntimeEnv();
+    const b = env?.[bindingName] as AnalyticsEngineDataset | undefined;
+    return b ?? null;
+  }
+
+  function write(name: string, value: number, labels?: Record<string, unknown>): void {
+    const binding = resolveBinding();
+    if (!binding) return; // No-op when binding is missing — never throw.
+
+    const indexValue = pickIndex(name, labels);
+    const blobs: string[] = [name];
+    if (labels) {
+      // Stable order — sort keys so the same blob index always means the
+      // same label across requests. AE has no schema; we enforce one here.
+      const keys = Object.keys(labels).sort();
+      for (const k of keys) {
+        const v = labels[k];
+        if (v !== undefined && v !== null) blobs.push(String(v));
+      }
+    }
+
+    try {
+      binding.writeDataPoint({
+        indexes: indexValue ? [indexValue] : undefined,
+        blobs,
+        doubles: [value],
+      });
+    } catch {
+      /* AE write failed — never fail the request */
+    }
+  }
+
+  return {
+    counterInc(name, value, labels) {
+      write(name, value ?? 1, labels);
+    },
+    histogramRecord(name, value, labels) {
+      write(name, value, labels);
+    },
+    gaugeSet(name, value, labels) {
+      write(name, value, labels);
+    },
+  };
+}
+
+function pickIndex(metricName: string, labels?: Record<string, unknown>): string | undefined {
+  if (!labels) return metricName;
+  // For HTTP request metrics the natural index is the path (matches the
+  // schema: `indexes[0]=path`). For other metrics, fall back to the metric
+  // name so the dataset is always queryable by index.
+  if (metricName === MetricNames.HTTP_SERVER_REQUEST_DURATION) {
+    const p = labels.path;
+    if (typeof p === "string" && p.length > 0) return p;
+  }
+  return metricName;
+}