@decocms/start 4.2.1 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

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.ts

@@ -42,16 +42,25 @@ 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 { configureLogger, defaultLoggerAdapter, type LogLevel, logger } from "./logger";
 import {
   createAnalyticsEngineMeterAdapter,
   createOtelLoggerAdapter,
   createOtelMeterAdapter,
+  flushOtelProviders,
   setRuntimeEnv,
 } from "./otelAdapters";
 import { RequestContext } from "./requestContext";
 import { createUrlBasedHeadSampler, decodeSamplingConfig } from "./sampler";
 
+const VALID_LOG_LEVELS: readonly LogLevel[] = ["debug", "info", "warn", "error"];
+
+function parseLogLevel(value: unknown): LogLevel | undefined {
+  if (typeof value !== "string") return undefined;
+  const lc = value.toLowerCase();
+  return VALID_LOG_LEVELS.find((l) => l === lc);
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -69,6 +78,15 @@ export interface OtelOptions {
   analyticsEngineEnabled?: boolean;
   /** Push interval for OTLP metrics, in ms. Defaults to env.OTEL_EXPORT_INTERVAL or 60_000. */
   metricsExportIntervalMillis?: number;
+  /**
+   * Minimum severity to forward to OTLP logs (HyperDX). Below the floor
+   * the framework still writes a structured JSON line to `console.*`
+   * (Cloudflare Workers Logs), so nothing is silently lost.
+   *
+   * Defaults to `"warn"`. Falls back to env `OTEL_LOG_MIN_SEVERITY` when
+   * unset. Set to `"debug"` to forward everything.
+   */
+  otlpMinSeverity?: LogLevel;
   /**
    * Version of `@decocms/start` to advertise as `deco.runtime.version`.
    * Falls back to a build-time constant; override only for tests.
@@ -179,12 +197,27 @@ export function instrumentWorker(
         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();
+      try {
+        // RequestContext may already be active (createDecoWorkerEntry sets it
+        // up). If so, run inline; otherwise wrap. Cheap to detect via current.
+        if (RequestContext.current) {
+          return await wrap();
+        }
+        return await RequestContext.run(request, wrap);
+      } finally {
+        // Drain OTLP logger + meter batches inside the post-response window
+        // the platform guarantees via `waitUntil`. Without this hook,
+        // BatchLogRecordProcessor (5s flush) and PeriodicExportingMetricReader
+        // (60s flush) batches usually die with the isolate before the timer
+        // fires and never reach HyperDX. `flushOtelProviders` is a no-op when
+        // OTLP isn't configured, so this is safe in every code path.
+        try {
+          ctx.waitUntil(flushOtelProviders());
+        } catch {
+          // `waitUntil` only throws if `ctx` isn't a real ExecutionContext
+          // (e.g. test stubs). Telemetry flush failures are not request-fatal.
+        }
       }
-      return RequestContext.run(request, wrap);
     },
   };
 
@@ -216,6 +249,9 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
   });
 
   // ---- Logger ----------------------------------------------------------
+  const otlpMinSeverity =
+    opts.otlpMinSeverity ?? parseLogLevel(env.OTEL_LOG_MIN_SEVERITY) ?? "warn";
+
   const otelLogger =
     otlpEndpoint != null
       ? createOtelLoggerAdapter({
@@ -223,6 +259,7 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
           headers: otlpHeaders,
           resource,
           name: serviceName,
+          minSeverity: otlpMinSeverity,
         })
       : null;
 
@@ -262,6 +299,7 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
   logger.info("observability booted", {
     service: serviceName,
     otlp: Boolean(otlpEndpoint),
+    otlpMinSeverity: otlpEndpoint != null ? otlpMinSeverity : null,
     analyticsEngine: aeEnabled,
     sampling: Boolean(env.OTEL_SAMPLING_CONFIG),
     runtimeVersion: opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION,

package/src/sdk/otelAdapters.test.ts

@@ -1,8 +1,13 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { LoggerProvider } from "@opentelemetry/sdk-logs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
+  _getFlushHandlerCountForTests,
+  _resetFlushHandlersForTests,
   createAnalyticsEngineMeterAdapter,
   createOtelLoggerAdapter,
   createOtelMeterAdapter,
+  flushOtelProviders,
+  registerOtelFlushHandler,
   setRuntimeEnv,
 } from "./otelAdapters";
 import { RequestContext } from "./requestContext";
@@ -40,7 +45,13 @@ describe("createOtelLoggerAdapter / createOtelMeterAdapter", () => {
   });
 
   it("logs without throwing for a variety of attribute shapes", () => {
-    const log = createOtelLoggerAdapter({ endpoint: "https://otel.example.invalid" });
+    // minSeverity:"debug" so the test exercises the actual emit path; the
+    // default "warn" floor would short-circuit before the OTel emit runs
+    // and the attribute-sanitization branch wouldn't be hit.
+    const log = createOtelLoggerAdapter({
+      endpoint: "https://otel.example.invalid",
+      minSeverity: "debug",
+    });
     expect(log).not.toBeNull();
     expect(() =>
       log!.log("info", "ok", {
@@ -58,6 +69,131 @@ describe("createOtelLoggerAdapter / createOtelMeterAdapter", () => {
   });
 });
 
+describe("createOtelLoggerAdapter — minSeverity floor", () => {
+  // Every call to `createOtelLoggerAdapter` constructs its own local
+  // `LoggerProvider`. The OTel global provider is set the first time
+  // (`setGlobalLoggerProvider` is "first wins"), so spying on the global
+  // doesn't observe later adapters' emits. Spying on the *prototype*
+  // sidesteps that — every provider instance, local or global, returns
+  // the same fake logger and we can count emits across all of them.
+  let emitSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    _resetFlushHandlersForTests();
+    emitSpy = vi.fn();
+    vi.spyOn(LoggerProvider.prototype, "getLogger").mockReturnValue({
+      emit: emitSpy,
+    } as unknown as ReturnType<LoggerProvider["getLogger"]>);
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    _resetFlushHandlersForTests();
+  });
+
+  function makeAdapter(minSeverity?: "debug" | "info" | "warn" | "error") {
+    const adapter = createOtelLoggerAdapter({
+      endpoint: "https://otel.example.invalid",
+      headers: { authorization: "test" },
+      ...(minSeverity ? { minSeverity } : {}),
+    });
+    expect(adapter).not.toBeNull();
+    return adapter!;
+  }
+
+  it("defaults to 'warn' — drops debug + info, keeps warn + error", () => {
+    const adapter = makeAdapter(undefined);
+    adapter.log("debug", "d");
+    adapter.log("info", "i");
+    adapter.log("warn", "w");
+    adapter.log("error", "e");
+    expect(emitSpy).toHaveBeenCalledTimes(2);
+    expect(emitSpy.mock.calls[0]?.[0].severityText).toBe("WARN");
+    expect(emitSpy.mock.calls[1]?.[0].severityText).toBe("ERROR");
+  });
+
+  it("explicit minSeverity='debug' lets every level through", () => {
+    const adapter = makeAdapter("debug");
+    adapter.log("debug", "d");
+    adapter.log("info", "i");
+    adapter.log("warn", "w");
+    adapter.log("error", "e");
+    expect(emitSpy).toHaveBeenCalledTimes(4);
+  });
+
+  it("explicit minSeverity='error' only forwards error", () => {
+    const adapter = makeAdapter("error");
+    adapter.log("debug", "d");
+    adapter.log("info", "i");
+    adapter.log("warn", "w");
+    adapter.log("error", "e");
+    expect(emitSpy).toHaveBeenCalledTimes(1);
+    expect(emitSpy.mock.calls[0]?.[0].severityText).toBe("ERROR");
+  });
+});
+
+describe("flushOtelProviders / registerOtelFlushHandler", () => {
+  beforeEach(() => _resetFlushHandlersForTests());
+  afterEach(() => {
+    vi.restoreAllMocks();
+    _resetFlushHandlersForTests();
+  });
+
+  it("resolves immediately when no handlers are registered", async () => {
+    expect(_getFlushHandlerCountForTests()).toBe(0);
+    await expect(flushOtelProviders()).resolves.toBeUndefined();
+  });
+
+  it("invokes every registered handler exactly once", async () => {
+    const a = vi.fn(() => Promise.resolve());
+    const b = vi.fn(() => Promise.resolve());
+    registerOtelFlushHandler(a);
+    registerOtelFlushHandler(b);
+    expect(_getFlushHandlerCountForTests()).toBe(2);
+    await flushOtelProviders();
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).toHaveBeenCalledOnce();
+  });
+
+  it("does NOT reject when a handler throws — uses Promise.allSettled", async () => {
+    const ok = vi.fn(() => Promise.resolve());
+    const fail = vi.fn(() => Promise.reject(new Error("OTLP 503")));
+    registerOtelFlushHandler(fail);
+    registerOtelFlushHandler(ok);
+    // Must resolve, not throw — flush failures are telemetry incidents,
+    // not request incidents. This is the surface contract callers rely on.
+    await expect(flushOtelProviders()).resolves.toBeUndefined();
+    expect(ok).toHaveBeenCalledOnce();
+    expect(fail).toHaveBeenCalledOnce();
+  });
+
+  it("createOtelLoggerAdapter registers exactly one flush handler", () => {
+    const before = _getFlushHandlerCountForTests();
+    const adapter = createOtelLoggerAdapter({
+      endpoint: "https://otel.example.invalid",
+    });
+    expect(adapter).not.toBeNull();
+    expect(_getFlushHandlerCountForTests()).toBe(before + 1);
+  });
+
+  it("createOtelMeterAdapter registers exactly one flush handler", () => {
+    const before = _getFlushHandlerCountForTests();
+    const meter = createOtelMeterAdapter({
+      endpoint: "https://otel.example.invalid",
+      exportIntervalMillis: 60_000,
+    });
+    expect(meter).not.toBeNull();
+    expect(_getFlushHandlerCountForTests()).toBe(before + 1);
+  });
+
+  it("returning-null factories register no handlers", () => {
+    expect(_getFlushHandlerCountForTests()).toBe(0);
+    createOtelLoggerAdapter(null);
+    createOtelLoggerAdapter({ endpoint: "" });
+    createOtelMeterAdapter(null);
+    expect(_getFlushHandlerCountForTests()).toBe(0);
+  });
+});
+
 describe("createAnalyticsEngineMeterAdapter", () => {
   afterEach(() => vi.restoreAllMocks());
 

package/src/sdk/otelAdapters.ts

@@ -39,6 +39,56 @@ import { MetricNames } from "../middleware/observability";
 import type { LoggerAdapter, LogLevel } from "./logger";
 import { RequestContext } from "./requestContext";
 
+// ---------------------------------------------------------------------------
+// Flush registry — per-request `ctx.waitUntil` hook target
+// ---------------------------------------------------------------------------
+
+/**
+ * Cloudflare Workers isolates are recycled aggressively (often before the
+ * next 5s `BatchLogRecordProcessor` tick or 60s `PeriodicExportingMetricReader`
+ * tick fires). Without a per-request flush, in-memory log/metric batches die
+ * with the isolate and never reach OTLP — observable as "spans show up in
+ * HyperDX, logs and metrics don't".
+ *
+ * Each OTLP adapter registers a `forceFlush` handler here at construction
+ * time. `instrumentWorker` calls `flushOtelProviders()` from
+ * `ctx.waitUntil(...)` after every response so the batch is drained inside
+ * the post-response window the platform guarantees.
+ *
+ * The registry is module-scoped (one entry per provider, not per request)
+ * and survives worker reloads — the boot guard in `bootObservability`
+ * prevents duplicate registration in steady state. Tests must call
+ * `_resetFlushHandlersForTests()` between fixtures to avoid leakage.
+ */
+const flushHandlers: Array<() => Promise<unknown>> = [];
+
+/** Register a `forceFlush()`-style handler. Idempotency is the caller's problem. */
+export function registerOtelFlushHandler(fn: () => Promise<unknown>): void {
+  flushHandlers.push(fn);
+}
+
+/**
+ * Drain every registered OTLP provider in parallel. Resolves once they
+ * all settle — never rejects, because flush failures are telemetry
+ * incidents, not request incidents.
+ *
+ * Safe to call when no adapters are registered (returns immediately).
+ */
+export async function flushOtelProviders(): Promise<void> {
+  if (flushHandlers.length === 0) return;
+  await Promise.allSettled(flushHandlers.map((fn) => fn()));
+}
+
+/** Test-only: clear the flush registry between fixtures. Do not call from app code. */
+export function _resetFlushHandlersForTests(): void {
+  flushHandlers.length = 0;
+}
+
+/** Test-only: introspect the registry size. Do not call from app code. */
+export function _getFlushHandlerCountForTests(): number {
+  return flushHandlers.length;
+}
+
 // ---------------------------------------------------------------------------
 // Env / binding access
 // ---------------------------------------------------------------------------
@@ -79,13 +129,37 @@ export interface OtelLoggerAdapterOptions {
   resource?: Resource;
   /** OTel logger name. Defaults to "@decocms/start". */
   name?: string;
+  /**
+   * Minimum severity to forward to OTLP. Calls below this floor are dropped
+   * by this adapter (and therefore don't ship to HyperDX or any other OTLP
+   * sink), but the framework's default console adapter still sees them, so
+   * they remain visible in Cloudflare Workers Logs.
+   *
+   * Defaults to `"warn"`. The reasoning: in Cloudflare Workers every OTLP
+   * emit eventually becomes an outbound subrequest (after batching). Routine
+   * `info` chatter compounded over many isolates can exhaust either the
+   * subrequest budget (if a hot loop logs) or the HyperDX log-ingest quota.
+   * Warn+ keeps the trace ↔ log correlation that matters during incidents
+   * without ingesting noise that's already captured by Cloudflare Logs.
+   *
+   * Override per-site via `OtelOptions.otlpMinSeverity` or the
+   * `OTEL_LOG_MIN_SEVERITY` env var. Set to `"debug"` to forward everything.
+   */
+  minSeverity?: LogLevel;
 }
 
 /**
- * Streams `logger.*` calls to an OTLP/HTTP logs endpoint (e.g. HyperDX).
+ * Streams `logger.*` calls (at or above `minSeverity`) to an OTLP/HTTP logs
+ * endpoint (e.g. HyperDX).
  *
  * Returns `null` when no endpoint is configured — `instrumentWorker()`
  * uses that signal to skip registering this adapter.
+ *
+ * Side effect: registers the underlying `LoggerProvider`'s `forceFlush()`
+ * with `registerOtelFlushHandler` so per-request hooks in `instrumentWorker`
+ * can drain the batch before the Workers isolate is recycled. Without that
+ * registration, `BatchLogRecordProcessor`'s 5s timer rarely fires before
+ * GC and log records are silently dropped.
  */
 export function createOtelLoggerAdapter(
   options: OtelLoggerAdapterOptions | null,
@@ -101,6 +175,7 @@ export function createOtelLoggerAdapter(
     resource: options.resource,
   });
   provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
+  registerOtelFlushHandler(() => provider.forceFlush());
 
   // Register globally so `@opentelemetry/api-logs` consumers (if any)
   // also pick it up. Idempotent — safe across multiple worker reloads.
@@ -111,10 +186,12 @@ export function createOtelLoggerAdapter(
   }
 
   const otelLogger = provider.getLogger(options.name ?? "@decocms/start");
+  const minSev = SEVERITY[options.minSeverity ?? "warn"].number;
 
   return {
     log(level, msg, attrs) {
       const sev = SEVERITY[level];
+      if (sev.number < minSev) return;
       otelLogger.emit({
         severityNumber: sev.number,
         severityText: sev.text,
@@ -229,6 +306,11 @@ export function createOtelMeterAdapter(
     readers: [reader],
     views,
   });
+  // See `flushHandlers` registry comment — `PeriodicExportingMetricReader`
+  // ticks every `exportIntervalMillis` (default 60s); without per-request
+  // forceFlush the metric batch typically dies with the Workers isolate
+  // before its first scheduled tick.
+  registerOtelFlushHandler(() => provider.forceFlush());
 
   try {
     metricsApi.setGlobalMeterProvider(provider);