@decocms/start 2.28.2 → 2.30.0

package/src/sdk/composite.ts

@@ -0,0 +1,114 @@
+/**
+ * Composite adapters — fan out to multiple backends with try/catch isolation.
+ *
+ * Used by `instrumentWorker()` so the same logger/meter can dual-emit to
+ * (e.g.) console-JSON + OTLP, or AE + OTLP, without any one backend's
+ * failure taking down the others.
+ *
+ * The "always include console-JSON logger" guarantee in the observability
+ * plan relies on this: even if HyperDX is down, the local console adapter
+ * still records the line.
+ */
+
+import type { MeterAdapter } from "../middleware/observability";
+import type { LoggerAdapter, LogLevel } from "./logger";
+
+type Labels = Record<string, string | number | boolean>;
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single LoggerAdapter that fans every call out to all
+ * provided adapters. Falsy entries (e.g. `otelEnabled ? otelAdapter : null`)
+ * are filtered out so call sites can write:
+ *
+ * ```ts
+ * createCompositeLogger([defaultLoggerAdapter, otelEnabled ? otelLogger : null]);
+ * ```
+ *
+ * Each downstream `.log()` call is isolated in try/catch so a thrown
+ * error in one backend cannot suppress the others.
+ */
+export function createCompositeLogger(
+  adapters: Array<LoggerAdapter | null | undefined | false>,
+): LoggerAdapter {
+  const list = adapters.filter((a): a is LoggerAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    log(level: LogLevel, msg: string, attrs?: Record<string, unknown>) {
+      for (const adapter of list) {
+        try {
+          adapter.log(level, msg, attrs);
+        } catch (error) {
+          // Use console.error directly — calling logger here would recurse.
+          try {
+            console.error("[composite-logger] adapter failed", String(error));
+          } catch {
+            /* swallow */
+          }
+        }
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Meter
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single MeterAdapter that fans counter/gauge/histogram writes
+ * out to all provided meters. Same semantics as `createCompositeLogger`:
+ * falsy entries are dropped, each downstream call is try/catch isolated.
+ */
+export function createCompositeMeter(
+  adapters: Array<MeterAdapter | null | undefined | false>,
+): MeterAdapter {
+  const list = adapters.filter((a): a is MeterAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    counterInc(name: string, value?: number, labels?: Labels) {
+      for (const m of list) {
+        try {
+          m.counterInc(name, value, labels);
+        } catch (error) {
+          warn("counterInc", name, error);
+        }
+      }
+    },
+    gaugeSet(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.gaugeSet) continue;
+        try {
+          m.gaugeSet(name, value, labels);
+        } catch (error) {
+          warn("gaugeSet", name, error);
+        }
+      }
+    },
+    histogramRecord(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.histogramRecord) continue;
+        try {
+          m.histogramRecord(name, value, labels);
+        } catch (error) {
+          warn("histogramRecord", name, error);
+        }
+      }
+    },
+  };
+}
+
+function warn(op: string, metric: string, error: unknown) {
+  try {
+    console.error(`[composite-meter] ${op}(${metric}) adapter failed`, String(error));
+  } catch {
+    /* swallow */
+  }
+}

package/src/sdk/instrumentedFetch.ts

@@ -16,6 +16,26 @@
  */
 
 import { getTracer } from "../middleware/observability";
+import { logger } from "./logger";
+
+/**
+ * Cloudflare / VTEX response headers that operators want to see as span
+ * attributes when debugging cache behavior. Mirrors `applyCustomAttributesOnSpan`
+ * in `deco-cx/deco/observability/otel/`.
+ */
+const CACHE_HEADERS_TO_SPAN: Array<{ header: string; attr: string }> = [
+  { header: "cf-cache-status", attr: "cf.cache.status" },
+  { header: "cf-ray", attr: "cf.ray" },
+  { header: "x-vtex-io-cluster-id", attr: "vtex.io.cluster.id" },
+  { header: "x-edge-cache-status", attr: "edge.cache.status" },
+];
+
+const TRUE_LITERAL = "true";
+
+function envFlag(name: string): boolean {
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+  return env?.[name] === TRUE_LITERAL;
+}
 
 export interface FetchInstrumentationOptions {
   /** Tag for log/trace grouping (e.g., "vtex", "shopify"). */
@@ -85,6 +105,32 @@ export function createInstrumentedFetch(
         );
       }
 
+      // Structured outgoing-fetch breadcrumb. Same field shape as the Fresh
+      // `@deco/deco/o11y` impl so log pipelines built off the old stack
+      // keep working unchanged. Off by default to avoid log explosion;
+      // enable with `OTEL_LOG_OUTGOING_FETCH=true`.
+      if (envFlag("OTEL_LOG_OUTGOING_FETCH")) {
+        let host = "";
+        let path = "";
+        try {
+          const u = new URL(url);
+          host = u.host;
+          path = u.pathname;
+        } catch {
+          /* unparseable URL — leave host/path blank */
+        }
+        logger.info("outgoing fetch", {
+          app: name,
+          host,
+          path,
+          method,
+          status: response.status,
+          ok: response.ok,
+          durationMs: Math.round(durationMs),
+          cached,
+        });
+      }
+
       onComplete?.({
         name,
         url,
@@ -108,6 +154,16 @@ export function createInstrumentedFetch(
 
         try {
           const response = await doFetch();
+          // Promote CF / VTEX cache headers as span attributes — the plan
+          // calls out these four. `@microlabs/otel-cf-workers` does not
+          // expose the response inside its own fetch span lifecycle, so
+          // capturing them here on our wrapper span is the practical
+          // place to do it.
+          for (const { header, attr } of CACHE_HEADERS_TO_SPAN) {
+            const value = response.headers.get(header);
+            if (value) span.setAttribute?.(attr, value);
+          }
+          span.setAttribute?.("http.status_code", response.status);
           span.end();
           return response;
         } catch (error) {

package/src/sdk/logger.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type LoggerAdapter,
+  logger,
+  setLogLevel,
+} from "./logger";
+
+describe("defaultLoggerAdapter", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("debug"); // permissive default for the rest of the suite
+  });
+
+  it("emits one JSON line per call", () => {
+    defaultLoggerAdapter.log("info", "hello", { foo: 1 });
+    expect(logSpy).toHaveBeenCalledOnce();
+    const arg = logSpy.mock.calls[0]?.[0] as string;
+    const parsed = JSON.parse(arg);
+    expect(parsed).toMatchObject({ level: "info", msg: "hello", foo: 1 });
+    expect(typeof parsed.timestamp).toBe("string");
+  });
+
+  it("routes by level so CF Logs colorises correctly", () => {
+    defaultLoggerAdapter.log("error", "boom");
+    defaultLoggerAdapter.log("warn", "careful");
+    defaultLoggerAdapter.log("debug", "details");
+    expect(errorSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(debugSpy).toHaveBeenCalledOnce();
+  });
+
+  it("never throws on circular refs (last-resort fallback)", () => {
+    const circ: any = { name: "x" };
+    circ.self = circ;
+    expect(() => defaultLoggerAdapter.log("info", "circ", { circ })).not.toThrow();
+    expect(logSpy).toHaveBeenCalledOnce();
+  });
+
+  it("does not let attrs override level/msg/timestamp keys", () => {
+    defaultLoggerAdapter.log("info", "real-msg", {
+      level: "tampered",
+      msg: "tampered",
+      timestamp: "tampered",
+    });
+    const parsed = JSON.parse(logSpy.mock.calls[0]?.[0] as string);
+    expect(parsed.level).toBe("info");
+    expect(parsed.msg).toBe("real-msg");
+    expect(parsed.timestamp).not.toBe("tampered");
+  });
+});
+
+describe("level filtering", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("drops calls below the active min level", () => {
+    setLogLevel("warn");
+    expect(getLogLevel()).toBe("warn");
+    logger.debug("d");
+    logger.info("i");
+    logger.warn("w");
+    logger.error("e");
+    expect(debugSpy).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled(); // info routes to console.log
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(errorSpy).toHaveBeenCalledOnce();
+  });
+});
+
+describe("configureLogger", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("dispatches to the configured adapter", () => {
+    const calls: Array<[string, string, unknown]> = [];
+    const test: LoggerAdapter = {
+      log(level, msg, attrs) {
+        calls.push([level, msg, attrs]);
+      },
+    };
+    configureLogger(test);
+    expect(getLoggerAdapter()).toBe(test);
+
+    logger.info("hello", { x: 1 });
+    expect(calls).toEqual([["info", "hello", { x: 1 }]]);
+  });
+
+  it("falls back to default adapter if active adapter throws", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const broken: LoggerAdapter = {
+      log() {
+        throw new Error("nope");
+      },
+    };
+    configureLogger(broken);
+    expect(() => logger.info("survives", { x: 1 })).not.toThrow();
+    // Default adapter was invoked as the fallback
+    expect(logSpy).toHaveBeenCalledOnce();
+    logSpy.mockRestore();
+  });
+});

package/src/sdk/logger.ts

@@ -0,0 +1,166 @@
+/**
+ * Pluggable structured logger for @decocms/start.
+ *
+ * Mirrors the public shape of `@deco/deco/o11y` logger so site code that
+ * does `logger.info("...", { key: "value" })` keeps working unchanged
+ * after the Fresh → TanStack migration.
+ *
+ * Backed by a `LoggerAdapter`. The default adapter writes one JSON line
+ * to `console.log` per call — that line is what Cloudflare Logs / Logpush
+ * captures, so logging works out of the box on Workers without any
+ * additional configuration.
+ *
+ * To dual-emit to OTLP (HyperDX, etc.), wrap the default with
+ * `createCompositeLogger([defaultLoggerAdapter, otelLoggerAdapter])`
+ * inside `instrumentWorker()`.
+ *
+ * @example
+ * ```ts
+ * import { logger } from "@decocms/start/sdk/logger";
+ *
+ * logger.info("checkout started", { orderFormId, items: cart.items.length });
+ * logger.warn("retrying vtex call", { attempt, host });
+ * logger.error("payment failed", { reason, code, traceId });
+ * ```
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export interface LoggerAdapter {
+  log(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Default adapter — structured JSON to console.log
+// ---------------------------------------------------------------------------
+
+/**
+ * Cloudflare-Logs-friendly default. One JSON object per call, on stdout.
+ * Always safe to use — never throws, never depends on env, never makes
+ * a network call.
+ */
+export const defaultLoggerAdapter: LoggerAdapter = {
+  log(level, msg, attrs) {
+    const payload: Record<string, unknown> = {
+      level,
+      msg,
+      timestamp: new Date().toISOString(),
+    };
+    if (attrs) {
+      // Spread last so explicit attrs win over our defaults except
+      // for `level` / `msg` / `timestamp` which we always want canonical.
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k !== "level" && k !== "msg" && k !== "timestamp") {
+          payload[k] = v;
+        }
+      }
+    }
+    // Route by level so Cloudflare's log dashboard colorises correctly.
+    const fn =
+      level === "error"
+        ? console.error
+        : level === "warn"
+          ? console.warn
+          : level === "debug"
+            ? console.debug
+            : console.log;
+    try {
+      fn(JSON.stringify(payload));
+    } catch {
+      // Last-resort: fall back to plain string. Never crash the request
+      // because of a circular-ref or non-serialisable attribute.
+      fn(`${level} ${msg}`);
+    }
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Configurable global state
+// ---------------------------------------------------------------------------
+
+let activeAdapter: LoggerAdapter = defaultLoggerAdapter;
+let minLevel: LogLevel = "info";
+
+/**
+ * Replace the active logger adapter.
+ * Call once at worker boot from `instrumentWorker()`.
+ */
+export function configureLogger(adapter: LoggerAdapter): void {
+  activeAdapter = adapter;
+}
+
+/**
+ * Get the current active logger adapter (for tests / advanced wiring).
+ */
+export function getLoggerAdapter(): LoggerAdapter {
+  return activeAdapter;
+}
+
+/**
+ * Set the minimum log level. Calls below this level are dropped before
+ * reaching any adapter — useful to silence `debug` in production.
+ *
+ * Defaults to `info`. Override per environment via `setLogLevel("debug")`
+ * or by reading an env var at boot.
+ */
+export function setLogLevel(level: LogLevel): void {
+  minLevel = level;
+}
+
+export function getLogLevel(): LogLevel {
+  return minLevel;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_RANK[level] >= LEVEL_RANK[minLevel];
+}
+
+// ---------------------------------------------------------------------------
+// Public logger surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirrors `@deco/deco/o11y` logger:
+ *  - first arg is the message
+ *  - optional second arg is a flat attributes object
+ *
+ * Adapters decide the destination (stdout JSON, OTLP, both, …).
+ */
+export interface Logger {
+  debug(msg: string, attrs?: Record<string, unknown>): void;
+  info(msg: string, attrs?: Record<string, unknown>): void;
+  warn(msg: string, attrs?: Record<string, unknown>): void;
+  error(msg: string, attrs?: Record<string, unknown>): void;
+}
+
+function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void {
+  if (!shouldLog(level)) return;
+  try {
+    activeAdapter.log(level, msg, attrs);
+  } catch {
+    // Adapter blew up. Fall back to default so we don't lose the line.
+    if (activeAdapter !== defaultLoggerAdapter) {
+      try {
+        defaultLoggerAdapter.log(level, msg, attrs);
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+export const logger: Logger = {
+  debug: (msg, attrs) => emit("debug", msg, attrs),
+  info: (msg, attrs) => emit("info", msg, attrs),
+  warn: (msg, attrs) => emit("warn", msg, attrs),
+  error: (msg, attrs) => emit("error", msg, attrs),
+};
+
+export default logger;

package/src/sdk/observability.ts

@@ -0,0 +1,75 @@
+/**
+ * One-stop import for everything observability-related in `@decocms/start`.
+ *
+ * Consumers (sites, apps) should prefer importing from here so future
+ * re-organisations don't ripple through every site:
+ *
+ * ```ts
+ * import {
+ *   instrumentWorker,
+ *   logger,
+ *   setLogLevel,
+ *   withTracing,
+ *   recordRequestMetric,
+ *   recordCacheMetric,
+ *   MetricNames,
+ * } from "@decocms/start/sdk/observability";
+ * ```
+ *
+ * The granular modules (`@decocms/start/sdk/logger`, `.../otelAdapters`,
+ * `.../sampler`) remain importable for advanced use cases (custom adapters,
+ * tests, etc.) but the common path stays here.
+ */
+
+// Tracer / meter / request log primitives (re-exported from the middleware)
+export {
+  configureMeter,
+  configureTracer,
+  getActiveSpan,
+  getMeter,
+  getTracer,
+  logRequest,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordRequestMetric,
+  type Span,
+  setSpanAttribute,
+  type TracerAdapter,
+  withTracing,
+} from "../middleware/observability";
+// Composite helpers (for advanced multi-backend wiring)
+export { createCompositeLogger, createCompositeMeter } from "./composite";
+// Logger surface
+export {
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type Logger,
+  type LoggerAdapter,
+  type LogLevel,
+  logger,
+  setLogLevel,
+} from "./logger";
+// Worker-entry wrapper + adapter wiring
+export { instrumentWorker, type OtelOptions } from "./otel";
+// Adapters (for tests / custom wiring)
+export {
+  type AnalyticsEngineMeterAdapterOptions,
+  createAnalyticsEngineMeterAdapter,
+  createOtelLoggerAdapter,
+  createOtelMeterAdapter,
+  getRuntimeEnv,
+  type OtelLoggerAdapterOptions,
+  type OtelMeterAdapterOptions,
+  setRuntimeEnv,
+} from "./otelAdapters";
+// Sampler
+export {
+  createUrlBasedHeadSampler,
+  decodeSamplingConfig,
+  type SamplingConfig,
+  type SamplingRule,
+  URLBasedSampler,
+} from "./sampler";

package/src/sdk/otel.test.ts

@@ -0,0 +1,59 @@
+/**
+ * NOTE: full `instrumentWorker(...)` integration tests aren't feasible in
+ * plain vitest because `@microlabs/otel-cf-workers` imports `cloudflare:workers`,
+ * which only exists in the Workers runtime.
+ *
+ * The wiring is validated end-to-end on the lebiscuit canary (Section 2 of
+ * the otel-hyperdx-parity plan): hit the deployed preview, confirm log
+ * lines via `wrangler tail`, traces via the HyperDX UI, and AE data points
+ * via `wrangler analytics-engine sql`. If we ever migrate the framework
+ * test suite to `@cloudflare/vitest-pool-workers`, restore the in-process
+ * smoke test here.
+ *
+ * Until then this file just guards the public API shape of the granular
+ * modules so refactors that break the export surface fail loudly in CI.
+ * (We deliberately don't import `./observability` here — it transitively
+ * pulls in `@microlabs/otel-cf-workers` and therefore `cloudflare:workers`.)
+ */
+import { describe, expect, it } from "vitest";
+import * as observability from "../middleware/observability";
+import * as composite from "./composite";
+import * as logger from "./logger";
+import * as adapters from "./otelAdapters";
+import * as sampler from "./sampler";
+
+describe("observability granular modules", () => {
+  it("exports the logger surface", () => {
+    expect(typeof logger.logger.info).toBe("function");
+    expect(typeof logger.configureLogger).toBe("function");
+    expect(typeof logger.setLogLevel).toBe("function");
+    expect(typeof logger.defaultLoggerAdapter.log).toBe("function");
+  });
+
+  it("exports composite helpers", () => {
+    expect(typeof composite.createCompositeLogger).toBe("function");
+    expect(typeof composite.createCompositeMeter).toBe("function");
+  });
+
+  it("exports OTel adapter factories", () => {
+    expect(typeof adapters.createOtelLoggerAdapter).toBe("function");
+    expect(typeof adapters.createOtelMeterAdapter).toBe("function");
+    expect(typeof adapters.createAnalyticsEngineMeterAdapter).toBe("function");
+    expect(typeof adapters.setRuntimeEnv).toBe("function");
+    expect(typeof adapters.getRuntimeEnv).toBe("function");
+  });
+
+  it("exports sampler API", () => {
+    expect(typeof sampler.URLBasedSampler).toBe("function");
+    expect(typeof sampler.decodeSamplingConfig).toBe("function");
+    expect(typeof sampler.createUrlBasedHeadSampler).toBe("function");
+  });
+
+  it("exports observability primitives from middleware/observability", () => {
+    expect(typeof observability.withTracing).toBe("function");
+    expect(typeof observability.recordRequestMetric).toBe("function");
+    expect(typeof observability.recordCacheMetric).toBe("function");
+    expect(observability.MetricNames.HTTP_REQUEST_DURATION_MS).toBe("http_request_duration_ms");
+    expect(observability.MetricNames.RESOLVE_DURATION_MS).toBe("resolve_duration_ms");
+  });
+});