@decocms/start 4.2.1 → 4.4.0

package/src/sdk/logger.ts

@@ -88,6 +88,20 @@ export const defaultLoggerAdapter: LoggerAdapter = {
 let activeAdapter: LoggerAdapter = defaultLoggerAdapter;
 let minLevel: LogLevel = "info";
 
+/**
+ * Per-record attribute floor — merged into every log line BEFORE the
+ * caller's `attrs` (caller wins). Used to stamp `deco.runtime.version`,
+ * `deco.apps.version`, `deployment.environment` on every log so HyperDX
+ * panels filtering on these dimensions keep working under
+ * Cloudflare-managed log export (which otherwise strips our resource
+ * attributes — only the JSON record body survives).
+ *
+ * Set via `setLoggerAttributeFloor(...)` at boot from
+ * `instrumentWorker()`. Default empty so the logger is a no-op for sites
+ * that don't wire `instrumentWorker`.
+ */
+let attributeFloor: Record<string, unknown> = {};
+
 /**
  * Replace the active logger adapter.
  * Call once at worker boot from `instrumentWorker()`.
@@ -96,6 +110,22 @@ export function configureLogger(adapter: LoggerAdapter): void {
   activeAdapter = adapter;
 }
 
+/**
+ * Replace the per-record attribute floor — keys here will be added to
+ * every log line UNLESS the caller passes the same key in their `attrs`
+ * (caller wins). Set once at worker boot from `instrumentWorker()`.
+ */
+export function setLoggerAttributeFloor(attrs: Record<string, unknown>): void {
+  attributeFloor = { ...attrs };
+}
+
+/**
+ * Test-only: read the current attribute floor. Do not call from app code.
+ */
+export function _getLoggerAttributeFloorForTests(): Record<string, unknown> {
+  return { ...attributeFloor };
+}
+
 /**
  * Get the current active logger adapter (for tests / advanced wiring).
  */
@@ -197,13 +227,21 @@ export function serializeError(err: unknown): SerializedError {
 
 function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void {
   if (!shouldLog(level)) return;
+  // Merge floor → caller attrs so caller can override any floor key.
+  // Skipped entirely when the floor is empty so the no-op path stays cheap.
+  const merged: Record<string, unknown> | undefined =
+    Object.keys(attributeFloor).length === 0
+      ? attrs
+      : attrs
+        ? { ...attributeFloor, ...attrs }
+        : { ...attributeFloor };
   try {
-    activeAdapter.log(level, msg, attrs);
+    activeAdapter.log(level, msg, merged);
   } catch {
     // Adapter blew up. Fall back to default so we don't lose the line.
     if (activeAdapter !== defaultLoggerAdapter) {
       try {
-        defaultLoggerAdapter.log(level, msg, attrs);
+        defaultLoggerAdapter.log(level, msg, merged);
       } catch {
         /* swallow */
       }

package/src/sdk/observability.ts

@@ -60,9 +60,11 @@ export {
   createAnalyticsEngineMeterAdapter,
   createOtelLoggerAdapter,
   createOtelMeterAdapter,
+  flushOtelProviders,
   getRuntimeEnv,
   type OtelLoggerAdapterOptions,
   type OtelMeterAdapterOptions,
+  registerOtelFlushHandler,
   setRuntimeEnv,
 } from "./otelAdapters";
 // Sampler

package/src/sdk/otel.test.ts

@@ -1,27 +1,38 @@
 /**
- * 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.
+ * Coverage for `instrumentWorker` and the public observability surface.
  *
- * 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`.)
+ * As of 4.4.0 the framework no longer wraps with `@microlabs/otel-cf-workers`
+ * (`cloudflare:workers`-only), so importing `./otel` and `./observability`
+ * works in plain vitest. Earlier versions of this file documented that
+ * constraint — it's gone.
  */
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import * as observability from "../middleware/observability";
 import * as composite from "./composite";
 import * as logger from "./logger";
+import { _resetBootStateForTests, instrumentWorker } from "./otel";
 import * as adapters from "./otelAdapters";
 import * as sampler from "./sampler";
 
+interface TestEnv extends Record<string, unknown> {
+  DECO_SITE_NAME?: string;
+  OTEL_EXPORTER_OTLP_ENDPOINT?: string;
+  OTEL_EXPORTER_OTLP_HEADERS?: string;
+  DECO_METRICS?: { writeDataPoint: () => void };
+  CF_VERSION_METADATA?: { id: string };
+}
+
+function fakeCtx() {
+  const waited: Array<Promise<unknown>> = [];
+  return {
+    waitUntil: (p: Promise<unknown>) => {
+      waited.push(p);
+    },
+    passThroughOnException: () => {},
+    waited,
+  };
+}
+
 describe("observability granular modules", () => {
   it("exports the logger surface", () => {
     expect(typeof logger.logger.info).toBe("function");
@@ -41,6 +52,8 @@ describe("observability granular modules", () => {
     expect(typeof adapters.createAnalyticsEngineMeterAdapter).toBe("function");
     expect(typeof adapters.setRuntimeEnv).toBe("function");
     expect(typeof adapters.getRuntimeEnv).toBe("function");
+    expect(typeof adapters.flushOtelProviders).toBe("function");
+    expect(typeof adapters.registerOtelFlushHandler).toBe("function");
   });
 
   it("exports sampler API", () => {
@@ -57,3 +70,103 @@ describe("observability granular modules", () => {
     expect(observability.MetricNames.RESOLVE_DURATION_MS).toBe("resolve_duration_ms");
   });
 });
+
+describe("instrumentWorker — CF-native default boot", () => {
+  beforeEach(() => {
+    _resetBootStateForTests();
+    adapters._resetFlushHandlersForTests();
+  });
+
+  afterEach(() => {
+    _resetBootStateForTests();
+    adapters._resetFlushHandlersForTests();
+  });
+
+  it("default mode (no opts, only OTLP endpoint set): wires meter flush only, NOT logger flush", async () => {
+    const handler = { fetch: vi.fn().mockResolvedValue(new Response("ok")) };
+    const wrapped = instrumentWorker(handler);
+
+    const env: TestEnv = {
+      OTEL_EXPORTER_OTLP_ENDPOINT: "https://in-otel.hyperdx.io",
+      OTEL_EXPORTER_OTLP_HEADERS: "authorization=Bearer test",
+    };
+    const ctx = fakeCtx();
+    await wrapped.fetch(new Request("https://example.test/"), env, ctx);
+
+    // Exactly one provider registered: the OTLP meter. The OTLP logger is
+    // gated behind `enableAppSideOtlpLogs` opt-in and CF handles log export.
+    expect(adapters._getFlushHandlerCountForTests()).toBe(1);
+    expect(handler.fetch).toHaveBeenCalledOnce();
+    expect(ctx.waited).toHaveLength(1);
+  });
+
+  it("default mode without OTLP endpoint: no flush handlers registered (pure CF-native)", async () => {
+    const handler = { fetch: vi.fn().mockResolvedValue(new Response("ok")) };
+    const wrapped = instrumentWorker(handler);
+
+    const env: TestEnv = {};
+    const ctx = fakeCtx();
+    await wrapped.fetch(new Request("https://example.test/"), env, ctx);
+
+    expect(adapters._getFlushHandlerCountForTests()).toBe(0);
+    // ctx.waitUntil still called with the no-op flush, but the handler array is empty.
+    expect(ctx.waited).toHaveLength(1);
+  });
+
+  it("opt-in mode (enableAppSideOtlpLogs: true): wires BOTH logger and meter flush", async () => {
+    const handler = { fetch: vi.fn().mockResolvedValue(new Response("ok")) };
+    const wrapped = instrumentWorker(handler, { enableAppSideOtlpLogs: true });
+
+    const env: TestEnv = {
+      OTEL_EXPORTER_OTLP_ENDPOINT: "https://in-otel.hyperdx.io",
+      OTEL_EXPORTER_OTLP_HEADERS: "authorization=Bearer test",
+    };
+    const ctx = fakeCtx();
+    await wrapped.fetch(new Request("https://example.test/"), env, ctx);
+
+    expect(adapters._getFlushHandlerCountForTests()).toBe(2);
+  });
+
+  it("flush is awaited via ctx.waitUntil even when fetch throws", async () => {
+    const handler = { fetch: vi.fn().mockRejectedValue(new Error("boom")) };
+    const wrapped = instrumentWorker(handler);
+
+    const env: TestEnv = {};
+    const ctx = fakeCtx();
+    await expect(wrapped.fetch(new Request("https://example.test/"), env, ctx)).rejects.toThrow(
+      "boom",
+    );
+
+    expect(ctx.waited).toHaveLength(1);
+  });
+
+  it("boot is idempotent across requests: flush handler count stable", async () => {
+    const handler = { fetch: vi.fn().mockResolvedValue(new Response("ok")) };
+    const wrapped = instrumentWorker(handler);
+
+    const env: TestEnv = {
+      OTEL_EXPORTER_OTLP_ENDPOINT: "https://in-otel.hyperdx.io",
+    };
+
+    for (let i = 0; i < 3; i++) {
+      await wrapped.fetch(new Request("https://example.test/"), env, fakeCtx());
+    }
+
+    expect(adapters._getFlushHandlerCountForTests()).toBe(1);
+    expect(handler.fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("AE meter is wired without OTLP when DECO_METRICS binding is present", async () => {
+    const writeDataPoint = vi.fn();
+    const handler = { fetch: vi.fn().mockResolvedValue(new Response("ok")) };
+    const wrapped = instrumentWorker(handler);
+
+    const env: TestEnv = { DECO_METRICS: { writeDataPoint } };
+    const ctx = fakeCtx();
+    await wrapped.fetch(new Request("https://example.test/"), env, ctx);
+
+    // AE adapter doesn't register a flush (writeDataPoint is fire-and-forget),
+    // so no providers should be registered when only AE is wired.
+    expect(adapters._getFlushHandlerCountForTests()).toBe(0);
+  });
+});