@decocms/start 2.28.2 → 2.30.0

package/src/sdk/otel.ts

@@ -1,12 +1,19 @@
 /**
- * OpenTelemetry integration for Cloudflare Workers via @microlabs/otel-cf-workers.
+ * Single observability entry point for `@decocms/start` on Cloudflare Workers.
  *
- * Opt-in module that wraps a Worker handler with auto-instrumentation and
- * wires traces into @decocms/start's pluggable TracerAdapter.
+ * `instrumentWorker(handler, options)` wraps a Worker handler with:
+ *  - structured JSON logger (stdout → Cloudflare Logs / Logpush) — always
+ *  - OTLP/HTTP logs exporter (HyperDX) — when `OTEL_EXPORTER_OTLP_ENDPOINT` is set
+ *  - OTLP/HTTP metrics exporter (HyperDX) — same condition
+ *  - Workers Analytics Engine metrics — when `env.DECO_METRICS` binding exists
+ *  - OTel traces via `@microlabs/otel-cf-workers` — when OTLP endpoint is set,
+ *    or always-on for the framework's internal `withTracing()` calls.
+ *  - URL-based head sampler from `OTEL_SAMPLING_CONFIG`
+ *  - OTel `Resource` with service.* / cloud.* / deployment.environment /
+ *    deco.runtime.version attributes
  *
- * Requires peer dependencies:
- * - `@microlabs/otel-cf-workers`
- * - `@opentelemetry/api`
+ * Removing HyperDX = unsetting `OTEL_EXPORTER_OTLP_ENDPOINT`. The console-JSON
+ * logger and AE metrics keep flowing — this is the "no vendor lock-in" guarantee.
  *
  * @example
  * ```ts
@@ -18,30 +25,64 @@
  * export default instrumentWorker(handler, { serviceName: "my-store" });
  * ```
  *
- * Environment variables (read from `env` at request time):
- * - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint (e.g. `https://in-otel.hyperdx.io`)
- * - `OTEL_EXPORTER_OTLP_HEADERS` — comma-separated `key=value` auth headers
+ * Wrangler bindings to add when enabling OTLP + AE:
+ * ```jsonc
+ * "version_metadata":         { "binding": "CF_VERSION_METADATA" },
+ * "analytics_engine_datasets": [{ "binding": "DECO_METRICS", "dataset": "deco_metrics_my_site" }]
+ * ```
+ *
+ * Required Worker secrets when OTLP is enabled:
+ *   wrangler secret put OTEL_EXPORTER_OTLP_ENDPOINT  # https://in-otel.hyperdx.io
+ *   wrangler secret put OTEL_EXPORTER_OTLP_HEADERS   # authorization=<token>
  */
 
 import { instrument, type ResolveConfigFn } from "@microlabs/otel-cf-workers";
 import { trace } from "@opentelemetry/api";
-import { configureTracer } from "../middleware/observability";
+import { type Resource, resourceFromAttributes } from "@opentelemetry/resources";
+
+import { configureMeter, configureTracer } from "../middleware/observability";
+import { createCompositeLogger, createCompositeMeter } from "./composite";
+import { configureLogger, defaultLoggerAdapter, logger } from "./logger";
+import {
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  setRuntimeEnv,
+} from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+import { createUrlBasedHeadSampler, decodeSamplingConfig } from "./sampler";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
 export interface OtelOptions {
-  serviceName: string;
-  /** OTLP endpoint. Defaults to env.OTEL_EXPORTER_OTLP_ENDPOINT. */
+  /** Logical service name. Falls back to `env.DECO_SITE_NAME`, then "deco-site". */
+  serviceName?: string;
+  /** Override OTLP endpoint. Defaults to `env.OTEL_EXPORTER_OTLP_ENDPOINT`. */
   endpoint?: string;
-  /** OTLP auth headers. Defaults to env.OTEL_EXPORTER_OTLP_HEADERS parsed. */
+  /** Override OTLP auth headers. Defaults to parsed `env.OTEL_EXPORTER_OTLP_HEADERS`. */
   headers?: Record<string, string>;
+  /** Env var name holding the AE binding. Defaults to `"DECO_METRICS"`. */
+  analyticsEngineBindingName?: string;
+  /** Set to `false` to disable AE even when the binding is present. */
+  analyticsEngineEnabled?: boolean;
+  /** Push interval for OTLP metrics, in ms. Defaults to env.OTEL_EXPORT_INTERVAL or 60_000. */
+  metricsExportIntervalMillis?: number;
+  /**
+   * Version of `@decocms/start` to advertise as `deco.runtime.version`.
+   * Falls back to a build-time constant; override only for tests.
+   */
+  decoRuntimeVersion?: string;
+  /** Optional `@decocms/apps` version, advertised as `deco.apps.version`. */
+  decoAppsVersion?: string;
 }
 
-/** Minimal Cloudflare Worker execution context. */
 interface WorkerExecutionContext {
   waitUntil(promise: Promise<unknown>): void;
   passThroughOnException(): void;
 }
 
-/** Handler shape returned by createDecoWorkerEntry. */
 interface WorkerHandler {
   fetch(
     request: Request,
@@ -50,19 +91,40 @@ interface WorkerHandler {
   ): Promise<Response>;
 }
 
+// ---------------------------------------------------------------------------
+// Boot state — guard against double-init across worker reloads
+// ---------------------------------------------------------------------------
+
+let booted = false;
+
+interface BootState {
+  serviceName: string;
+  otlpEndpoint: string | null;
+  otlpHeaders: Record<string, string>;
+  resource: Resource;
+}
+
+let bootState: BootState | null = null;
+
+// ---------------------------------------------------------------------------
+// instrumentWorker
+// ---------------------------------------------------------------------------
+
 /**
- * Wraps a Cloudflare Worker handler with OpenTelemetry auto-instrumentation
- * (fetch, KV, D1, waitUntil) and connects to @decocms/start's TracerAdapter
- * so that `withTracing()` / `createInstrumentedFetch()` emit real OTel spans.
+ * Wraps a Cloudflare Worker handler with the full @decocms/start
+ * observability stack. Idempotent — calling twice on the same handler
+ * is a no-op (returns the already-instrumented handler).
  */
 export function instrumentWorker(
   handler: WorkerHandler,
-  options: OtelOptions | ((env: Record<string, unknown>) => OtelOptions),
-) {
-  // Bridge @decocms/start TracerAdapter → @opentelemetry/api
+  options: OtelOptions | ((env: Record<string, unknown>) => OtelOptions) = {},
+): WorkerHandler {
+  // Bridge our pluggable TracerAdapter onto @opentelemetry/api so
+  // framework-internal `withTracing()` calls produce real OTel spans
+  // for whatever exporter is configured (OTLP, console, etc.).
   configureTracer({
     startSpan: (name, attrs) => {
-      const span = trace.getTracer("deco").startSpan(name, { attributes: attrs });
+      const span = trace.getTracer("@decocms/start").startSpan(name, { attributes: attrs });
       return {
         end: () => span.end(),
         setError: (error) => {
@@ -75,21 +137,178 @@ export function instrumentWorker(
 
   const resolveConfig: ResolveConfigFn = (env, _trigger) => {
     const opts = typeof options === "function" ? options(env as Record<string, unknown>) : options;
-    const endpoint = opts.endpoint || (env.OTEL_EXPORTER_OTLP_ENDPOINT as string);
-    const headers = opts.headers || parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS as string | undefined);
+    bootObservability(opts, env as Record<string, unknown>);
+
+    const state = bootState!;
+
+    // Sampling — base64 JSON via OTEL_SAMPLING_CONFIG, see sdk/sampler.ts
+    const samplingConfig = decodeSamplingConfig(env.OTEL_SAMPLING_CONFIG as string | undefined);
+    const headSampler = createUrlBasedHeadSampler(samplingConfig);
+
+    // microlabs requires an exporter even when we only want internal
+    // tracing. When OTLP isn't configured, we still set up a no-op
+    // collector — the URL we'd never reach so spans simply drop.
+    const exporterUrl = state.otlpEndpoint ?? "http://127.0.0.1:0/v1/traces";
 
     return {
-      exporter: { url: endpoint, headers },
-      service: { name: opts.serviceName },
+      exporter: {
+        url: joinPath(exporterUrl, "/v1/traces"),
+        headers: state.otlpHeaders,
+      },
+      service: {
+        name: state.serviceName,
+        version: (env.CF_VERSION_METADATA as { id?: string } | undefined)?.id,
+      },
+      sampling: { headSampler },
+      // microlabs auto-instruments globalThis.fetch + KV + waitUntil.
+      instrumentation: {
+        instrumentGlobalFetch: true,
+        instrumentGlobalCache: true,
+      },
     };
   };
 
-  // Cast through `any` — @microlabs/otel-cf-workers expects Cloudflare's
-  // ExportedHandler type, but we avoid depending on @cloudflare/workers-types.
+  const innerHandler: WorkerHandler = {
+    async fetch(request, env, ctx) {
+      // Stash env so request-scoped adapters (AE) can resolve their bindings.
+      // Done inside RequestContext.run wrapping in workerEntry.ts as well, but
+      // for instrumentWorker we re-stash in case this handler is wrapped over
+      // the top of a Worker that doesn't go through createDecoWorkerEntry.
+      const wrap = async () => {
+        setRuntimeEnv(env);
+        return handler.fetch(request, env, ctx);
+      };
+
+      // RequestContext may already be active (createDecoWorkerEntry sets it
+      // up). If so, run inline; otherwise wrap. Cheap to detect via current.
+      if (RequestContext.current) {
+        return wrap();
+      }
+      return RequestContext.run(request, wrap);
+    },
+  };
+
   // deno-lint-ignore no-explicit-any
-  return instrument(handler as any, resolveConfig);
+  return instrument(innerHandler as any, resolveConfig) as unknown as WorkerHandler;
+}
+
+// ---------------------------------------------------------------------------
+// Boot — wires the loggers/meters once (per worker isolate)
+// ---------------------------------------------------------------------------
+
+function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
+  if (booted && bootState) return;
+
+  const serviceName = opts.serviceName ?? (env.DECO_SITE_NAME as string | undefined) ?? "deco-site";
+
+  const otlpEndpoint =
+    opts.endpoint ?? (env.OTEL_EXPORTER_OTLP_ENDPOINT as string | undefined) ?? null;
+  const otlpHeaders =
+    opts.headers ?? parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS as string | undefined);
+
+  const resource = buildResource({
+    serviceName,
+    serviceVersion: (env.CF_VERSION_METADATA as { id?: string } | undefined)?.id,
+    serviceInstanceId: cryptoRandomId(),
+    deploymentEnvironment: (env.DECO_ENV_NAME as string | undefined) ?? "production",
+    decoRuntimeVersion: opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION,
+    decoAppsVersion: opts.decoAppsVersion,
+  });
+
+  // ---- Logger ----------------------------------------------------------
+  const otelLogger =
+    otlpEndpoint != null
+      ? createOtelLoggerAdapter({
+          endpoint: otlpEndpoint,
+          headers: otlpHeaders,
+          resource,
+          name: serviceName,
+        })
+      : null;
+
+  configureLogger(createCompositeLogger([defaultLoggerAdapter, otelLogger]));
+
+  // ---- Meter -----------------------------------------------------------
+  const otelMeter =
+    otlpEndpoint != null
+      ? createOtelMeterAdapter({
+          endpoint: otlpEndpoint,
+          headers: otlpHeaders,
+          resource,
+          exportIntervalMillis:
+            opts.metricsExportIntervalMillis ?? numericEnv(env.OTEL_EXPORT_INTERVAL, 60_000),
+          name: serviceName,
+        })
+      : null;
+
+  const aeBindingName = opts.analyticsEngineBindingName ?? "DECO_METRICS";
+  const aeEnabled = opts.analyticsEngineEnabled !== false && Boolean(env[aeBindingName]);
+  const aeMeter = aeEnabled
+    ? createAnalyticsEngineMeterAdapter({ bindingName: aeBindingName })
+    : null;
+
+  configureMeter(createCompositeMeter([aeMeter, otelMeter]));
+
+  bootState = {
+    serviceName,
+    otlpEndpoint,
+    otlpHeaders,
+    resource,
+  };
+  booted = true;
+
+  // Single boot-time breadcrumb so operators can confirm the wiring at a
+  // glance from CF Logs without enabling debug.
+  logger.info("observability booted", {
+    service: serviceName,
+    otlp: Boolean(otlpEndpoint),
+    analyticsEngine: aeEnabled,
+    sampling: Boolean(env.OTEL_SAMPLING_CONFIG),
+    runtimeVersion: opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION,
+  });
 }
 
+// ---------------------------------------------------------------------------
+// Resource attributes
+// ---------------------------------------------------------------------------
+
+interface ResourceInput {
+  serviceName: string;
+  serviceVersion?: string;
+  serviceInstanceId: string;
+  deploymentEnvironment: string;
+  decoRuntimeVersion: string;
+  decoAppsVersion?: string;
+}
+
+function buildResource(input: ResourceInput): Resource {
+  const attrs: Record<string, string> = {
+    "service.name": input.serviceName,
+    "service.version": input.serviceVersion ?? "unknown",
+    "service.instance.id": input.serviceInstanceId,
+    "cloud.provider": "cloudflare",
+    "deployment.environment": input.deploymentEnvironment,
+    "deco.runtime.version": input.decoRuntimeVersion,
+  };
+  if (input.decoAppsVersion) attrs["deco.apps.version"] = input.decoAppsVersion;
+  return resourceFromAttributes(attrs);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build-time @decocms/start version. Hand-bumped at release; we deliberately
+ * avoid `import("../../package.json")` to keep the module side-effect-free
+ * and JSON-import-quirk-free across the various build pipelines that
+ * consume @decocms/start.
+ *
+ * Drift is acceptable — this attribute is for operator triage, not for
+ * billing / SLOs.
+ */
+const DECO_RUNTIME_VERSION = "2.28.2";
+
 function parseHeaders(str?: string): Record<string, string> {
   if (!str) return {};
   return Object.fromEntries(
@@ -102,3 +321,25 @@ function parseHeaders(str?: string): Record<string, string> {
       .filter(([k]) => k.length > 0),
   );
 }
+
+function numericEnv(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function joinPath(base: string, path: string): string {
+  if (!base) return path;
+  if (base.endsWith("/")) base = base.slice(0, -1);
+  if (!path.startsWith("/")) path = "/" + path;
+  if (base.toLowerCase().endsWith(path.toLowerCase())) return base;
+  return base + path;
+}
+
+function cryptoRandomId(): string {
+  // crypto.randomUUID is universally available in CF Workers + Node 19+.
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `inst-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  }
+}

package/src/sdk/otelAdapters.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  setRuntimeEnv,
+} from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+
+describe("createOtelLoggerAdapter / createOtelMeterAdapter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("returns null when no endpoint is provided (no-op safe)", () => {
+    expect(createOtelLoggerAdapter(null)).toBeNull();
+    expect(createOtelLoggerAdapter({ endpoint: "" })).toBeNull();
+    expect(createOtelMeterAdapter(null)).toBeNull();
+  });
+
+  it("constructs without throwing when an endpoint is provided", () => {
+    // We don't want this test to actually open a network connection.
+    // The exporters lazy-initialize their HTTP client and only POST on
+    // batch flush, so simply constructing must not throw.
+    const log = createOtelLoggerAdapter({
+      endpoint: "https://otel.example.invalid",
+      headers: { authorization: "test" },
+      name: "test-svc",
+    });
+    expect(log).not.toBeNull();
+    expect(typeof log!.log).toBe("function");
+
+    const meter = createOtelMeterAdapter({
+      endpoint: "https://otel.example.invalid",
+      headers: { authorization: "test" },
+      exportIntervalMillis: 60_000,
+      name: "test-svc",
+    });
+    expect(meter).not.toBeNull();
+    expect(typeof meter!.counterInc).toBe("function");
+    expect(typeof meter!.histogramRecord).toBe("function");
+  });
+
+  it("logs without throwing for a variety of attribute shapes", () => {
+    const log = createOtelLoggerAdapter({ endpoint: "https://otel.example.invalid" });
+    expect(log).not.toBeNull();
+    expect(() =>
+      log!.log("info", "ok", {
+        s: "x",
+        n: 1,
+        b: true,
+        arr: [1, "two", true],
+        nested: { a: 1, b: { c: "d" } },
+        nullV: null,
+        undef: undefined,
+        fn: () => {},
+        sym: Symbol("s") as unknown as string,
+      }),
+    ).not.toThrow();
+  });
+});
+
+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("http_requests_total", 1, { method: "GET", path: "/", status: 200 });
+    meter.histogramRecord?.("http_request_duration_ms", 150, {
+      method: "GET",
+      path: "/",
+      status: 200,
+    });
+    meter.gaugeSet?.("custom_gauge", 7, { region: "gru" });
+
+    expect(writeDataPoint).toHaveBeenCalledTimes(3);
+
+    // For HTTP request metrics, indexes[0] must be the path.
+    expect(writeDataPoint.mock.calls[0]?.[0].indexes).toEqual(["/"]);
+    expect(writeDataPoint.mock.calls[0]?.[0].doubles).toEqual([1]);
+    expect(writeDataPoint.mock.calls[0]?.[0].blobs?.[0]).toBe("http_requests_total");
+
+    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();
+      // Use a known HTTP metric name so path is promoted to index[0].
+      meter.counterInc("http_requests_total", 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"]);
+  });
+});