@decocms/start 4.5.0 → 5.0.0

package/src/sdk/otel.ts

@@ -4,21 +4,30 @@
  * `instrumentWorker(handler, options)` wraps a Worker handler with:
  *  - structured JSON logger (stdout → Cloudflare Workers Logs) — always
  *  - Workers Analytics Engine metrics — when `env.DECO_METRICS` binding exists
- *  - OTLP/HTTP metrics exporter (HyperDX) — when `OTEL_EXPORTER_OTLP_ENDPOINT`
- *    is set (CF doesn't support OTLP metrics export yet, so this stays app-side)
- *  - Per-request `ctx.waitUntil(forceFlush)` for any registered OTel batch
- *    processors so log/metric batches don't die with the isolate
  *  - Bridges framework-internal `withTracing()` calls onto the global
  *    `@opentelemetry/api` tracer, stamping `deco.*` attributes on every span
  *    so they survive Cloudflare's platform-managed trace export
  *
- * **Logs and traces export to HyperDX is now handled by Cloudflare** via the
- * `observability.{logs,traces}.destinations` block in `wrangler.jsonc`. CF
- * captures `console.*` output and `@opentelemetry/api` global tracer spans
- * out-of-band and ships them OTLP-encoded to whatever destination is
- * configured. This eliminates the in-Worker exporter SDK, the per-request
- * subrequest cost of pushing OTLP, and the entire class of bug PR #153 fixed
- * (batch processors that never flush before isolate recycling).
+ * **All export goes through Cloudflare.** Logs reach the dashboard via
+ * `console.*` capture; traces reach the dashboard via CF auto-instrumentation
+ * plus the global-tracer spans this module forwards. There is no in-Worker
+ * OTLP exporter and no third-party destination — the CF dashboard is the
+ * destination.
+ *
+ * Required `wrangler.jsonc` block (run `scripts/migrate-to-cf-observability.ts`
+ * to inject this automatically):
+ * ```jsonc
+ * "observability": {
+ *   "enabled": true,
+ *   "logs":   { "enabled": true, "invocation_logs": true,
+ *               "head_sampling_rate": 1,   "persist": true },
+ *   "traces": { "enabled": true,
+ *               "head_sampling_rate": 0.1, "persist": true }
+ * },
+ * "version_metadata":          { "binding": "CF_VERSION_METADATA" },
+ * "analytics_engine_datasets": [{ "binding": "DECO_METRICS",
+ *                                 "dataset":  "deco_metrics_my_site" }]
+ * ```
  *
  * @example
  * ```ts
@@ -30,54 +39,18 @@
  * export default instrumentWorker(handler, { serviceName: "my-store" });
  * ```
  *
- * Companion `wrangler.jsonc` block (run `scripts/migrate-to-cf-observability.ts`
- * to inject this automatically):
- * ```jsonc
- * "observability": {
- *   "logs":   { "enabled": true, "destinations": ["hyperdx-logs"],
- *               "head_sampling_rate": 1.0, "persist": false },
- *   "traces": { "enabled": true, "destinations": ["hyperdx-traces"],
- *               "head_sampling_rate": 0.1, "persist": false }
- * },
- * "version_metadata":          { "binding": "CF_VERSION_METADATA" },
- * "analytics_engine_datasets": [{ "binding": "DECO_METRICS",
- *                                 "dataset":  "deco_metrics_my_site" }]
- * ```
- *
- * **Back-compat seam.** Sites that need to keep app-side OTLP log export
- * (custom destination not covered by CF, custom batching, etc.) can opt back
- * in with `enableAppSideOtlpLogs: true` and the existing `OTEL_EXPORTER_OTLP_*`
- * secrets. Slated for removal in 5.0.0.
+ * **Future ClickHouse path.** When a co-deployed OTel collector lands, an
+ * exporter that pushes spans + logs + metrics to that collector will live in
+ * `./otelAdapters/clickhouseCollector.ts` (today: documented stub that throws).
+ * The `withTracing` / `recordRequestMetric` / `logger` instrumentation surface
+ * does not change — only the transport layer wires up.
  */
 
 import { trace } from "@opentelemetry/api";
-import { type Resource, resourceFromAttributes } from "@opentelemetry/resources";
 
 import { configureMeter, configureTracer } from "../middleware/observability";
-import { createCompositeLogger, createCompositeMeter } from "./composite";
-import {
-  configureLogger,
-  defaultLoggerAdapter,
-  type LogLevel,
-  logger,
-  setLoggerAttributeFloor,
-} from "./logger";
-import {
-  createAnalyticsEngineMeterAdapter,
-  createOtelLoggerAdapter,
-  createOtelMeterAdapter,
-  flushOtelProviders,
-  setRuntimeEnv,
-} from "./otelAdapters";
-import { RequestContext } from "./requestContext";
-
-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);
-}
+import { configureLogger, defaultLoggerAdapter, setLoggerAttributeFloor } from "./logger";
+import { createAnalyticsEngineMeterAdapter } from "./otelAdapters";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -86,49 +59,17 @@ function parseLogLevel(value: unknown): LogLevel | undefined {
 export interface OtelOptions {
   /** 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;
-  /** 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;
-  /**
-   * Minimum severity to forward to the **app-side OTLP** logger (only
-   * relevant when `enableAppSideOtlpLogs: true`). The default `console.*`
-   * adapter is unaffected and continues to capture every level for
-   * Cloudflare Workers Logs / CF-side OTLP export.
-   *
-   * Defaults to `"warn"`. Falls back to env `OTEL_LOG_MIN_SEVERITY` when
-   * unset. Set to `"debug"` to forward everything.
-   */
-  otlpMinSeverity?: LogLevel;
-  /**
-   * Opt-in: also wire an in-Worker OTLP logger that pushes log records to
-   * `OTEL_EXPORTER_OTLP_ENDPOINT`. Defaults to `false` — sites should
-   * prefer the platform-managed CF-side path
-   * (`observability.logs.destinations` in `wrangler.jsonc`), which is
-   * cheaper, has no flush-bug class, and consumes zero subrequest budget.
-   *
-   * Use this only when CF's OTLP logs export doesn't meet a specific need
-   * (e.g. shipping to a destination CF doesn't support, custom batching,
-   * staging-only debugging). Requires `OTEL_EXPORTER_OTLP_ENDPOINT` and
-   * `OTEL_EXPORTER_OTLP_HEADERS` to be set.
-   *
-   * Slated for removal in 5.0.0.
-   */
-  enableAppSideOtlpLogs?: boolean;
   /**
    * Version of `@decocms/start` to advertise as `deco.runtime.version`
-   * on every span (CF doesn't preserve it as a resource attribute since
-   * we no longer ship our own resource — we stamp it per-span instead).
-   * Falls back to a build-time constant; override only for tests.
+   * on every span and every log line. Falls back to a build-time constant;
+   * override only for tests.
    */
   decoRuntimeVersion?: string;
-  /** Optional `@decocms/apps` version, stamped as `deco.apps.version` on every span. */
+  /** Optional `@decocms/apps` version, stamped as `deco.apps.version`. */
   decoAppsVersion?: string;
 }
 
@@ -151,24 +92,12 @@ interface WorkerHandler {
 
 let booted = false;
 
-interface BootState {
-  serviceName: string;
-  otlpEndpoint: string | null;
-  otlpHeaders: Record<string, string>;
-  resource: Resource;
-}
-
-let bootState: BootState | null = null;
-
 /**
  * Per-span attribute floor — stamped on every span we create via
- * `configureTracer().startSpan(...)`. These match what the legacy resource
- * attributes used to carry (when `@microlabs/otel-cf-workers` shipped its
- * own OTel `Resource`); we now stamp them on each span so HyperDX panels
- * filtering on `deco.runtime.version`, `deco.apps.version`, or
- * `deployment.environment` keep working with CF-managed export, which only
- * preserves CF's own resource attribute set (`service.name`, `faas.name`,
- * `cloudflare.script_version.id`, etc.).
+ * `configureTracer().startSpan(...)`. CF's trace export emits its own
+ * resource attribute set (service.name=Worker name, faas.name,
+ * cloudflare.script_version.id, etc.) so framework-level dimensions like
+ * `deco.runtime.version` only survive when stamped per-span.
  *
  * Populated by `bootObservability` before any span is created. Stays an
  * empty object until then so early span creation is a no-op stamp.
@@ -182,19 +111,15 @@ let spanAttributeFloor: Record<string, string> = {};
 /**
  * Wraps a Cloudflare Worker handler with the @decocms/start observability
  * stack:
- *  - structured JSON logger (always)
+ *  - structured JSON logger to console.* (CF captures via observability.logs)
  *  - AE meter (when `DECO_METRICS` binding present)
- *  - optional app-side OTLP meter (when `OTEL_EXPORTER_OTLP_ENDPOINT` set)
- *  - optional app-side OTLP logger (when `enableAppSideOtlpLogs: true`)
- *  - per-request `ctx.waitUntil(forceFlush)` for any registered batch processors
  *  - bridge from framework-internal `withTracing()` to `@opentelemetry/api`
- *    global tracer, with `deco.*` attributes stamped on every span
+ *    global tracer (CF observability.traces ingests via auto-instrumentation
+ *    + the global-tracer hook)
  *
- * Logs and traces export to HyperDX (or any OTLP destination) is handled
- * by Cloudflare via `observability.{logs,traces}.destinations` in
- * `wrangler.jsonc`. This wrapper does NOT call `@microlabs/otel-cf-workers`
- * `instrument()` — CF's platform-managed export captures `console.*` output
- * and global-tracer spans out-of-band.
+ * No external destinations, no OTLP transport. Forwarding to a future
+ * OTel collector for ClickHouse will live behind a separate adapter
+ * (see `./otelAdapters/clickhouseCollector.ts`).
  */
 export function instrumentWorker(
   handler: WorkerHandler,
@@ -206,9 +131,9 @@ export function instrumentWorker(
   //
   // CF Workers Tracing (when `observability.traces.enabled = true` in
   // wrangler) installs its own TracerProvider into the @opentelemetry/api
-  // global, so these spans flow through to whatever OTLP destination is
-  // configured. Without CF tracing the global tracer is a no-op proxy and
-  // the spans simply drop — same outcome as before, no error.
+  // global, so these spans flow through to the CF dashboard. Without CF
+  // tracing the global tracer is a no-op proxy and the spans simply drop
+  // — same outcome as before, no error.
   configureTracer({
     startSpan: (name, attrs) => {
       const merged = { ...spanAttributeFloor, ...(attrs ?? {}) };
@@ -228,34 +153,10 @@ export function instrumentWorker(
       const opts =
         typeof options === "function" ? options(env as Record<string, unknown>) : options;
       bootObservability(opts, env as Record<string, unknown>);
-
-      // Stash env so request-scoped adapters (AE) can resolve their
-      // bindings. Done inside RequestContext.run wrapping in workerEntry.ts
-      // too, but we re-stash here in case `instrumentWorker` is wrapped
-      // over a handler that doesn't go through `createDecoWorkerEntry`.
-      const wrap = async () => {
-        setRuntimeEnv(env);
-        return handler.fetch(request, env, ctx);
-      };
-
-      try {
-        if (RequestContext.current) {
-          return await wrap();
-        }
-        return await RequestContext.run(request, wrap);
-      } finally {
-        // Drain OTLP meter (and OTLP logger, if `enableAppSideOtlpLogs`)
-        // batches inside the post-response window `waitUntil` guarantees.
-        // Without this hook, `PeriodicExportingMetricReader` (60s flush)
-        // batches usually die with the isolate before the timer fires.
-        // No-op when no batch processors are registered.
-        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.
-        }
-      }
+      // RequestContext.run + setRuntimeEnv(env) is handled inside
+      // workerEntry.ts on the inner handler — instrumentWorker does
+      // NOT re-wrap so we don't double-enter AsyncLocalStorage.
+      return handler.fetch(request, env, ctx);
     },
   };
 }
@@ -265,119 +166,47 @@ export function instrumentWorker(
 // ---------------------------------------------------------------------------
 
 function bootObservability(opts: OtelOptions, env: Record<string, unknown>): void {
-  if (booted && bootState) return;
+  if (booted) 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 decoRuntimeVersion = opts.decoRuntimeVersion ?? DECO_RUNTIME_VERSION;
   const deploymentEnvironment = (env.DECO_ENV_NAME as string | undefined) ?? "production";
 
-  const resource = buildResource({
-    serviceName,
-    serviceVersion: (env.CF_VERSION_METADATA as { id?: string } | undefined)?.id,
-    serviceInstanceId: cryptoRandomId(),
-    deploymentEnvironment,
-    decoRuntimeVersion,
-    decoAppsVersion: opts.decoAppsVersion,
-  });
-
-  // Stamp deco.* attributes on every span we create. CF-managed trace
-  // export emits its own resource attribute set (service.name=Worker name,
-  // faas.name, cloudflare.script_version.id, faas.version, etc.) so the
-  // legacy resource attrs from `buildResource` don't survive on the
-  // CF-side path. Stamping them per-span preserves the dimensions
-  // existing HyperDX dashboards filter on.
-  spanAttributeFloor = {
+  const floor: Record<string, string> = {
     "deco.runtime.version": decoRuntimeVersion,
     "deployment.environment": deploymentEnvironment,
-    ...(opts.decoAppsVersion ? { "deco.apps.version": opts.decoAppsVersion } : {}),
   };
+  if (opts.decoAppsVersion) floor["deco.apps.version"] = opts.decoAppsVersion;
 
-  // Same set, stamped on every log record. CF Workers Logs ships the JSON
-  // body verbatim (resource attrs from `buildResource` are NOT applied to
-  // logs in default mode), so HyperDX panels grouping by these dimensions
-  // would otherwise return empty. Caller-supplied `attrs` still win on key
-  // collision.
-  setLoggerAttributeFloor({
-    "deco.runtime.version": decoRuntimeVersion,
-    "deployment.environment": deploymentEnvironment,
-    ...(opts.decoAppsVersion ? { "deco.apps.version": opts.decoAppsVersion } : {}),
-  });
+  // Stamp on every span we create. CF-managed trace export emits its own
+  // resource attribute set, so legacy resource attrs don't survive.
+  // Stamping per-span preserves the dimensions dashboards / saved searches
+  // filter on.
+  spanAttributeFloor = floor;
 
-  // ---- Logger ----------------------------------------------------------
-  // Default mode: console JSON only. Cloudflare Workers Logs captures the
-  // output and ships it via `observability.logs.destinations` to whichever
-  // OTLP destination is configured in `wrangler.jsonc`. This is the
-  // recommended path: zero in-Worker exporter, no flush bug, no subrequest
-  // cost per emit.
-  //
-  // Opt-in mode (`enableAppSideOtlpLogs: true`): also wire the OTLP logger
-  // adapter for sites with destinations CF doesn't support. Requires
-  // `OTEL_EXPORTER_OTLP_ENDPOINT` to be set.
-  const otlpMinSeverity =
-    opts.otlpMinSeverity ?? parseLogLevel(env.OTEL_LOG_MIN_SEVERITY) ?? "warn";
-
-  const wantAppSideLogs = opts.enableAppSideOtlpLogs === true;
-  const otelLogger =
-    wantAppSideLogs && otlpEndpoint != null
-      ? createOtelLoggerAdapter({
-          endpoint: otlpEndpoint,
-          headers: otlpHeaders,
-          resource,
-          name: serviceName,
-          minSeverity: otlpMinSeverity,
-        })
-      : null;
+  // Stamp on every log record. CF Workers Logs ships the JSON body
+  // verbatim — without this floor, panels grouping logs by these
+  // dimensions return empty. Caller-supplied `attrs` still win on
+  // key collision (see logger.ts).
+  setLoggerAttributeFloor(floor);
 
-  configureLogger(createCompositeLogger([defaultLoggerAdapter, otelLogger]));
-
-  // ---- Meter -----------------------------------------------------------
-  // OTLP meter stays default-on when an endpoint is configured: CF doesn't
-  // support OTLP metrics export yet, so this is the only path to
-  // HyperDX-compatible metrics. Drop this branch when CF ships metrics.
-  const otelMeter =
-    otlpEndpoint != null
-      ? createOtelMeterAdapter({
-          endpoint: otlpEndpoint,
-          headers: otlpHeaders,
-          resource,
-          exportIntervalMillis:
-            opts.metricsExportIntervalMillis ?? numericEnv(env.OTEL_EXPORT_INTERVAL, 60_000),
-          name: serviceName,
-        })
-      : null;
+  // Logger: structured JSON to console.*, captured by CF observability.logs.
+  configureLogger(defaultLoggerAdapter);
 
+  // Meter: AE only. OTLP metrics path was removed in 5.0.0; will return
+  // via the ClickHouse collector adapter when that lands.
   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]));
+  if (aeEnabled) {
+    configureMeter(createAnalyticsEngineMeterAdapter({ bindingName: aeBindingName }));
+  }
 
-  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. Surfaces which export
-  // mode is active (CF-native vs app-side) so misconfigured sites are
-  // obvious from the first request.
-  logger.info("observability booted", {
+  // glance from CF Logs without enabling debug.
+  defaultLoggerAdapter.log("info", "observability booted", {
     service: serviceName,
-    mode: wantAppSideLogs ? "hybrid (app-side OTLP logs + CF traces)" : "cf-native",
-    otlpMeter: Boolean(otlpEndpoint),
-    otlpLogger: wantAppSideLogs && otlpEndpoint != null,
-    otlpMinSeverity: wantAppSideLogs && otlpEndpoint != null ? otlpMinSeverity : null,
     analyticsEngine: aeEnabled,
     runtimeVersion: decoRuntimeVersion,
     deploymentEnvironment,
@@ -390,37 +219,10 @@ function bootObservability(opts: OtelOptions, env: Record<string, unknown>): voi
  */
 export function _resetBootStateForTests(): void {
   booted = false;
-  bootState = null;
   spanAttributeFloor = {};
   setLoggerAttributeFloor({});
 }
 
-// ---------------------------------------------------------------------------
-// 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
 // ---------------------------------------------------------------------------
@@ -434,31 +236,4 @@ function buildResource(input: ResourceInput): Resource {
  * Drift is acceptable — this attribute is for operator triage, not for
  * billing / SLOs.
  */
-const DECO_RUNTIME_VERSION = "4.4.0";
-
-function parseHeaders(str?: string): Record<string, string> {
-  if (!str) return {};
-  return Object.fromEntries(
-    str
-      .split(",")
-      .map((kv) => {
-        const [k, ...v] = kv.split("=");
-        return [k.trim(), v.join("=").trim()] as const;
-      })
-      .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 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)}`;
-  }
-}
+const DECO_RUNTIME_VERSION = "5.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.",
+  );
+}