@decocms/start 2.28.2 → 2.30.0

package/src/sdk/otelAdapters.ts

@@ -0,0 +1,401 @@
+/**
+ * OpenTelemetry adapter implementations for `@decocms/start`.
+ *
+ * These adapters plug into the framework's existing pluggable interfaces:
+ *  - `LoggerAdapter`  (from `./logger`)        ← OTLP logs
+ *  - `MeterAdapter`   (from `../middleware/observability`) ← OTLP metrics
+ *  - `MeterAdapter`                              ← Cloudflare Workers Analytics Engine
+ *
+ * Mirrors the metrics views and TTLs from `deco-cx/deco`'s
+ * `observability/otel/metrics.ts` so dashboards built against the Fresh
+ * stack keep working after the migration.
+ *
+ * All three adapters are no-op safe: missing env vars / missing AE binding
+ * means the adapter does nothing rather than throwing. The fan-out wrapper
+ * in `./composite` provides additional try/catch isolation.
+ */
+
+import {
+  type Counter,
+  type Histogram,
+  metrics as metricsApi,
+  type ObservableGauge,
+} from "@opentelemetry/api";
+import { type AnyValue, logs as logsApi, SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import type { Resource } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import {
+  type AggregationOption,
+  AggregationType,
+  InstrumentType,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  type ViewOptions,
+} from "@opentelemetry/sdk-metrics";
+import type { MeterAdapter } from "../middleware/observability";
+import { MetricNames } from "../middleware/observability";
+import type { LoggerAdapter, LogLevel } from "./logger";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Env / binding access
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-request access to the Cloudflare Worker `env` bag. Stashed by
+ * `instrumentWorker()` at the top of every request via
+ * `RequestContext.setBag("__deco_env", env)`.
+ *
+ * Adapters use this to look up the AE binding (or any future binding-driven
+ * destination) without forcing site code to thread `env` through every
+ * call site.
+ */
+const ENV_BAG_KEY = "__deco_env";
+
+export function setRuntimeEnv(env: Record<string, unknown>): void {
+  RequestContext.setBag(ENV_BAG_KEY, env);
+}
+
+export function getRuntimeEnv(): Record<string, unknown> | undefined {
+  return RequestContext.getBag<Record<string, unknown>>(ENV_BAG_KEY);
+}
+
+// ---------------------------------------------------------------------------
+// OtelLoggerAdapter
+// ---------------------------------------------------------------------------
+
+const SEVERITY: Record<LogLevel, { number: SeverityNumber; text: string }> = {
+  debug: { number: SeverityNumber.DEBUG, text: "DEBUG" },
+  info: { number: SeverityNumber.INFO, text: "INFO" },
+  warn: { number: SeverityNumber.WARN, text: "WARN" },
+  error: { number: SeverityNumber.ERROR, text: "ERROR" },
+};
+
+export interface OtelLoggerAdapterOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  resource?: Resource;
+  /** OTel logger name. Defaults to "@decocms/start". */
+  name?: string;
+}
+
+/**
+ * Streams `logger.*` calls 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.
+ */
+export function createOtelLoggerAdapter(
+  options: OtelLoggerAdapterOptions | null,
+): LoggerAdapter | null {
+  if (!options || !options.endpoint) return null;
+
+  const exporter = new OTLPLogExporter({
+    url: joinPath(options.endpoint, "/v1/logs"),
+    headers: options.headers,
+  });
+
+  const provider = new LoggerProvider({
+    resource: options.resource,
+  });
+  provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
+
+  // Register globally so `@opentelemetry/api-logs` consumers (if any)
+  // also pick it up. Idempotent — safe across multiple worker reloads.
+  try {
+    logsApi.setGlobalLoggerProvider(provider);
+  } catch {
+    /* already set */
+  }
+
+  const otelLogger = provider.getLogger(options.name ?? "@decocms/start");
+
+  return {
+    log(level, msg, attrs) {
+      const sev = SEVERITY[level];
+      otelLogger.emit({
+        severityNumber: sev.number,
+        severityText: sev.text,
+        body: msg,
+        attributes: attrs ? sanitizeAttributes(attrs) : undefined,
+      });
+    },
+  };
+}
+
+/**
+ * Coerce an arbitrary `Record<string, unknown>` into the strict `AnyValueMap`
+ * the OTel logs API expects. Drops anything that can't be safely
+ * represented (functions, symbols, circular structures via stringify guard).
+ */
+function sanitizeAttributes(attrs: Record<string, unknown>): Record<string, AnyValue> {
+  const out: Record<string, AnyValue> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    out[k] = toAnyValue(v);
+  }
+  return out;
+}
+
+function toAnyValue(v: unknown): AnyValue {
+  if (v === null || v === undefined) return undefined;
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  if (v instanceof Uint8Array) return v;
+  if (Array.isArray(v)) return v.map(toAnyValue);
+  if (typeof v === "object") {
+    const out: Record<string, AnyValue> = {};
+    for (const [k, vv] of Object.entries(v as Record<string, unknown>)) {
+      out[k] = toAnyValue(vv);
+    }
+    return out;
+  }
+  // Functions, symbols, bigint — stringify so the operator still sees something.
+  try {
+    return String(v);
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OtelMeterAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Histogram bucket boundaries for millisecond timings.
+ * Mirrors `deco-cx/deco/observability/otel/metrics.ts` so HyperDX
+ * panels built off the Fresh stack keep working unchanged.
+ */
+const MS_BOUNDARIES = [10, 100, 500, 1000, 5000, 10000, 15000];
+/** Histogram bucket boundaries for second timings. */
+const SECONDS_BOUNDARIES = [1, 5, 10, 50];
+
+export interface OtelMeterAdapterOptions {
+  endpoint: string;
+  headers?: Record<string, string>;
+  resource?: Resource;
+  /** Push interval in ms. Defaults to env.OTEL_EXPORT_INTERVAL or 60_000. */
+  exportIntervalMillis?: number;
+  /** OTel meter name. Defaults to "@decocms/start". */
+  name?: string;
+}
+
+/**
+ * Streams metric writes to an OTLP/HTTP metrics endpoint with a
+ * `PeriodicExportingMetricReader`.
+ *
+ * Two histogram views are pre-registered:
+ *  - any metric ending with `_ms` → millisecond bucket boundaries
+ *  - any metric ending with `_s`  → second bucket boundaries
+ *
+ * Returns `null` when no endpoint is configured.
+ */
+export function createOtelMeterAdapter(
+  options: OtelMeterAdapterOptions | null,
+): MeterAdapter | null {
+  if (!options || !options.endpoint) return null;
+
+  const exporter = new OTLPMetricExporter({
+    url: joinPath(options.endpoint, "/v1/metrics"),
+    headers: options.headers,
+  });
+
+  const reader = new PeriodicExportingMetricReader({
+    exporter,
+    exportIntervalMillis: options.exportIntervalMillis ?? 60_000,
+  });
+
+  const histogramAggregation = (boundaries: number[]): AggregationOption => ({
+    type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+    options: { boundaries, recordMinMax: true },
+  });
+
+  const views: ViewOptions[] = [
+    {
+      instrumentName: "*_ms",
+      instrumentType: InstrumentType.HISTOGRAM,
+      aggregation: histogramAggregation(MS_BOUNDARIES),
+    },
+    {
+      instrumentName: "*_s",
+      instrumentType: InstrumentType.HISTOGRAM,
+      aggregation: histogramAggregation(SECONDS_BOUNDARIES),
+    },
+  ];
+
+  const provider = new MeterProvider({
+    resource: options.resource,
+    readers: [reader],
+    views,
+  });
+
+  try {
+    metricsApi.setGlobalMeterProvider(provider);
+  } catch {
+    /* already set */
+  }
+
+  const meter = provider.getMeter(options.name ?? "@decocms/start");
+
+  // Lazy-create instruments by name so we don't pay the create cost on
+  // every recordRequestMetric / recordCacheMetric invocation.
+  const counters = new Map<string, Counter>();
+  const histograms = new Map<string, Histogram>();
+  const gauges = new Map<string, ObservableGauge>();
+  const gaugeValues = new Map<string, { value: number; labels?: Record<string, unknown> }>();
+
+  function getCounter(name: string): Counter {
+    let c = counters.get(name);
+    if (!c) {
+      c = meter.createCounter(name);
+      counters.set(name, c);
+    }
+    return c;
+  }
+  function getHistogram(name: string): Histogram {
+    let h = histograms.get(name);
+    if (!h) {
+      h = meter.createHistogram(name);
+      histograms.set(name, h);
+    }
+    return h;
+  }
+  function ensureGauge(name: string): void {
+    if (gauges.has(name)) return;
+    const g = meter.createObservableGauge(name);
+    g.addCallback((result) => {
+      const last = gaugeValues.get(name);
+      if (last)
+        result.observe(last.value, last.labels as Record<string, string | number | boolean>);
+    });
+    gauges.set(name, g);
+  }
+
+  return {
+    counterInc(name, value, labels) {
+      getCounter(name).add(value ?? 1, labels);
+    },
+    histogramRecord(name, value, labels) {
+      getHistogram(name).record(value, labels);
+    },
+    gaugeSet(name, value, labels) {
+      ensureGauge(name);
+      gaugeValues.set(name, { value, labels });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AnalyticsEngineMeterAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * Workers Analytics Engine binding shape. Defined here so we don't need
+ * `@cloudflare/workers-types` as a dep.
+ */
+interface AnalyticsEngineDataset {
+  writeDataPoint(point: { indexes?: string[]; blobs?: string[]; doubles?: number[] }): void;
+}
+
+export interface AnalyticsEngineMeterAdapterOptions {
+  /** Env var name holding the AE binding. Defaults to "DECO_METRICS". */
+  bindingName?: string;
+  /** Pre-resolved binding (mainly for tests). Bypasses RequestContext lookup. */
+  binding?: AnalyticsEngineDataset;
+}
+
+/**
+ * Writes one Analytics Engine data point per metric call.
+ *
+ * Schema (must stay stable — dashboards and SQL queries depend on it):
+ *  - `indexes[0]`: a low-cardinality dimension. For request metrics that's
+ *    the normalized URL path; for cache/resolve metrics that's the metric
+ *    name itself.
+ *  - `blobs[0]`: metric name (so a single dataset can hold many metrics).
+ *  - `blobs[1..]`: stringified label values, in stable label-name order.
+ *  - `doubles[0]`: the metric value (count, ms, gauge value).
+ *
+ * AE truncates / charges per data point, so this adapter is intentionally
+ * coarse: one point per `counterInc` / `histogramRecord` / `gaugeSet`.
+ */
+export function createAnalyticsEngineMeterAdapter(
+  options: AnalyticsEngineMeterAdapterOptions = {},
+): MeterAdapter {
+  const bindingName = options.bindingName ?? "DECO_METRICS";
+
+  function resolveBinding(): AnalyticsEngineDataset | null {
+    if (options.binding) return options.binding;
+    const env = getRuntimeEnv();
+    const b = env?.[bindingName] as AnalyticsEngineDataset | undefined;
+    return b ?? null;
+  }
+
+  function write(name: string, value: number, labels?: Record<string, unknown>): void {
+    const binding = resolveBinding();
+    if (!binding) return; // No-op when binding is missing — never throw.
+
+    const indexValue = pickIndex(name, labels);
+    const blobs: string[] = [name];
+    if (labels) {
+      // Stable order — sort keys so the same blob index always means the
+      // same label across requests. AE has no schema; we enforce one here.
+      const keys = Object.keys(labels).sort();
+      for (const k of keys) {
+        const v = labels[k];
+        if (v !== undefined && v !== null) blobs.push(String(v));
+      }
+    }
+
+    try {
+      binding.writeDataPoint({
+        indexes: indexValue ? [indexValue] : undefined,
+        blobs,
+        doubles: [value],
+      });
+    } catch {
+      /* AE write failed — never fail the request */
+    }
+  }
+
+  return {
+    counterInc(name, value, labels) {
+      write(name, value ?? 1, labels);
+    },
+    histogramRecord(name, value, labels) {
+      write(name, value, labels);
+    },
+    gaugeSet(name, value, labels) {
+      write(name, value, labels);
+    },
+  };
+}
+
+function pickIndex(metricName: string, labels?: Record<string, unknown>): string | undefined {
+  if (!labels) return metricName;
+  // For HTTP request metrics the natural index is the path (matches the
+  // plan: `indexes[0]=path`). For other metrics, fall back to the metric
+  // name so the dataset is always queryable by index.
+  if (
+    metricName === MetricNames.HTTP_REQUESTS_TOTAL ||
+    metricName === MetricNames.HTTP_REQUEST_DURATION_MS ||
+    metricName === MetricNames.HTTP_REQUEST_ERRORS
+  ) {
+    const p = labels.path;
+    if (typeof p === "string" && p.length > 0) return p;
+  }
+  return metricName;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function joinPath(base: string, path: string): string {
+  if (!base) return path;
+  if (base.endsWith("/")) base = base.slice(0, -1);
+  if (!path.startsWith("/")) path = "/" + path;
+  // Already includes the path? Don't double-append.
+  if (base.toLowerCase().endsWith(path.toLowerCase())) return base;
+  return base + path;
+}

package/src/sdk/sampler.test.ts

@@ -0,0 +1,127 @@
+import { ROOT_CONTEXT, SpanKind } from "@opentelemetry/api";
+import {
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  SamplingDecision,
+} from "@opentelemetry/sdk-trace-base";
+import { describe, expect, it } from "vitest";
+import { createUrlBasedHeadSampler, decodeSamplingConfig, URLBasedSampler } from "./sampler";
+
+const TRACE_ID = "0000000000000000ffffffffffffffff";
+
+function decide(sampler: URLBasedSampler, path: string) {
+  return sampler.shouldSample(
+    ROOT_CONTEXT,
+    TRACE_ID,
+    "span-name",
+    SpanKind.SERVER,
+    { "url.path": path },
+    [],
+  );
+}
+
+describe("URLBasedSampler", () => {
+  it("falls back to default ratio when no rule matches", () => {
+    const s = new URLBasedSampler({ default: 1.0 });
+    expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("first matching rule wins", () => {
+    const s = new URLBasedSampler({
+      default: 1.0,
+      rules: [
+        { pattern: "^/api/health", ratio: 0.0 },
+        { pattern: "^/api/", ratio: 1.0 },
+      ],
+    });
+    expect(decide(s, "/api/health").decision).toBe(SamplingDecision.NOT_RECORD);
+    expect(decide(s, "/api/orders").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("falls back to default when no path attribute is present", () => {
+    const s = new URLBasedSampler({ default: 1.0 });
+    const result = s.shouldSample(ROOT_CONTEXT, TRACE_ID, "noop", SpanKind.INTERNAL, {}, []);
+    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+
+  it("supports url.path, http.target, and http.url", () => {
+    const s = new URLBasedSampler({
+      default: 0.0,
+      rules: [{ pattern: "^/wanted", ratio: 1.0 }],
+    });
+    const ok = (attrs: Record<string, string>) =>
+      s.shouldSample(ROOT_CONTEXT, TRACE_ID, "n", SpanKind.SERVER, attrs, []);
+
+    expect(ok({ "url.path": "/wanted/x" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(ok({ "http.target": "/wanted/y" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(ok({ "http.url": "https://h.example/wanted/z?q=1" }).decision).toBe(
+      SamplingDecision.RECORD_AND_SAMPLED,
+    );
+  });
+});
+
+describe("decodeSamplingConfig", () => {
+  it("returns null on missing input", () => {
+    expect(decodeSamplingConfig(undefined)).toBeNull();
+    expect(decodeSamplingConfig("")).toBeNull();
+  });
+
+  it("decodes valid base64 JSON", () => {
+    const cfg = { default: 0.5, rules: [{ pattern: "^/x", ratio: 1.0 }] };
+    const enc = btoa(JSON.stringify(cfg));
+    const decoded = decodeSamplingConfig(enc);
+    expect(decoded).toEqual(cfg);
+  });
+
+  it("drops invalid rules but keeps the rest", () => {
+    const enc = btoa(
+      JSON.stringify({
+        default: 0.1,
+        rules: [
+          { pattern: "^/ok", ratio: 1.0 },
+          { pattern: "^[", ratio: 1.0 }, // invalid regex
+          { pattern: "^/yes", ratio: 0.5 },
+          { pattern: 7, ratio: 0.5 }, // wrong type
+        ],
+      }),
+    );
+    const decoded = decodeSamplingConfig(enc);
+    expect(decoded?.rules).toEqual([
+      { pattern: "^/ok", ratio: 1.0 },
+      { pattern: "^/yes", ratio: 0.5 },
+    ]);
+  });
+
+  it("returns null for non-JSON input", () => {
+    expect(decodeSamplingConfig("not-base64-not-json!!")).toBeNull();
+  });
+});
+
+describe("createUrlBasedHeadSampler", () => {
+  it("wraps the URL-based sampler in ParentBasedSampler", () => {
+    const sampler = createUrlBasedHeadSampler(null);
+    expect(sampler).toBeInstanceOf(ParentBasedSampler);
+  });
+
+  it("applies the default-ratio = 1.0 when config is null", () => {
+    // Smoke test only — sampler internals are validated above.
+    const sampler = createUrlBasedHeadSampler(null);
+    const result = sampler.shouldSample(
+      ROOT_CONTEXT,
+      TRACE_ID,
+      "n",
+      SpanKind.SERVER,
+      { "url.path": "/" },
+      [],
+    );
+    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+});
+
+describe("regression: AlwaysOnSampler still works", () => {
+  it("guards against accidental import-rename breakage", () => {
+    // If sdk-trace-base ever renames AlwaysOnSampler we want a loud failure.
+    const s = new AlwaysOnSampler();
+    expect(s.shouldSample().decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+  });
+});

package/src/sdk/sampler.ts

@@ -0,0 +1,183 @@
+/**
+ * URL-based head sampler — port of `deco-cx/deco/observability/otel/samplers/urlBased.ts`.
+ *
+ * Lets ops dial sampling rates per URL pattern without redeploying. Reads
+ * `OTEL_SAMPLING_CONFIG` (base64-encoded JSON) at boot and decides each
+ * trace's sample rate based on the matching pattern.
+ *
+ * Wrapped in `ParentBasedSampler` so a span inherits its parent's sampling
+ * decision when one exists (i.e. distributed traces are kept consistent end
+ * to end).
+ *
+ * @example
+ * ```jsonc
+ * // base64-encode this and set as OTEL_SAMPLING_CONFIG:
+ * {
+ *   "default": 0.05,
+ *   "rules": [
+ *     { "pattern": "^/checkout",   "ratio": 1.0 },
+ *     { "pattern": "^/api/health", "ratio": 0.0 },
+ *     { "pattern": "/p$",          "ratio": 0.1 }
+ *   ]
+ * }
+ * ```
+ */
+
+import { type Attributes, type Context, type Link, type SpanKind, trace } from "@opentelemetry/api";
+import {
+  AlwaysOffSampler,
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  type Sampler,
+  type SamplingResult,
+  TraceIdRatioBasedSampler,
+} from "@opentelemetry/sdk-trace-base";
+
+export interface SamplingRule {
+  /** ECMA RegExp pattern matched against the URL path. */
+  pattern: string;
+  /** Ratio in [0, 1]. */
+  ratio: number;
+}
+
+export interface SamplingConfig {
+  /** Default sample ratio applied when no rule matches. Defaults to 1.0 (always sample). */
+  default?: number;
+  /** Ordered list of rules. First match wins. */
+  rules?: SamplingRule[];
+}
+
+interface CompiledRule {
+  re: RegExp;
+  sampler: Sampler;
+}
+
+/**
+ * URL-pattern-driven head sampler. Implements the OTel `Sampler` interface
+ * directly so it can be plugged into `ParentBasedSampler`'s `root` slot.
+ */
+export class URLBasedSampler implements Sampler {
+  private readonly defaultSampler: Sampler;
+  private readonly rules: CompiledRule[];
+
+  constructor(config: SamplingConfig = {}) {
+    this.defaultSampler = ratioToSampler(config.default ?? 1.0);
+    this.rules = (config.rules ?? []).map((rule) => ({
+      re: new RegExp(rule.pattern),
+      sampler: ratioToSampler(rule.ratio),
+    }));
+  }
+
+  shouldSample(
+    context: Context,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[],
+  ): SamplingResult {
+    const path = extractPath(attributes);
+    if (path) {
+      for (const rule of this.rules) {
+        if (rule.re.test(path)) {
+          return rule.sampler.shouldSample(context, traceId, spanName, spanKind, attributes, links);
+        }
+      }
+    }
+    return this.defaultSampler.shouldSample(
+      context,
+      traceId,
+      spanName,
+      spanKind,
+      attributes,
+      links,
+    );
+  }
+
+  toString(): string {
+    return `URLBasedSampler(${this.rules.length} rules)`;
+  }
+}
+
+function ratioToSampler(ratio: number): Sampler {
+  if (ratio >= 1) return new AlwaysOnSampler();
+  if (ratio <= 0) return new AlwaysOffSampler();
+  return new TraceIdRatioBasedSampler(ratio);
+}
+
+function extractPath(attrs: Attributes): string | null {
+  // Prefer the OTel-standard `url.path` (semconv >= 1.21), fall back to
+  // legacy `http.target` and `http.url`.
+  const direct = attrs["url.path"] ?? attrs["http.target"];
+  if (typeof direct === "string") return direct;
+
+  const httpUrl = attrs["http.url"];
+  if (typeof httpUrl === "string") {
+    try {
+      return new URL(httpUrl).pathname;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Boot helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode a base64-encoded `OTEL_SAMPLING_CONFIG` value into a `SamplingConfig`.
+ * Returns `null` (caller falls back to default ratio 1.0) on:
+ *  - missing / empty input
+ *  - invalid base64
+ *  - JSON parse failure
+ *  - schema-mismatched payload
+ *
+ * Logs a warning to console when the env var is set but unparseable so the
+ * mistake is visible in CF Logs without crashing the worker boot.
+ */
+export function decodeSamplingConfig(raw: string | undefined): SamplingConfig | null {
+  if (!raw) return null;
+  try {
+    const json = atob(raw);
+    const parsed = JSON.parse(json) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const obj = parsed as { default?: unknown; rules?: unknown };
+
+    const defaultRatio = typeof obj.default === "number" ? obj.default : undefined;
+    const rawRules = Array.isArray(obj.rules) ? obj.rules : [];
+    const rules: SamplingRule[] = [];
+    for (const r of rawRules) {
+      if (!r || typeof r !== "object") continue;
+      const rec = r as { pattern?: unknown; ratio?: unknown };
+      if (typeof rec.pattern !== "string" || typeof rec.ratio !== "number") continue;
+      try {
+        // Eagerly validate the regex so a bad pattern fails at boot, not
+        // on the first matching request.
+        new RegExp(rec.pattern);
+        rules.push({ pattern: rec.pattern, ratio: rec.ratio });
+      } catch {
+        console.warn(`[sampler] dropping invalid pattern: ${rec.pattern}`);
+      }
+    }
+
+    return { default: defaultRatio, rules };
+  } catch (err) {
+    console.warn(`[sampler] failed to decode OTEL_SAMPLING_CONFIG`, String(err));
+    return null;
+  }
+}
+
+/**
+ * Build a `ParentBasedSampler` rooted at our URL-based sampler.
+ * Use as the `headSampler` for `@microlabs/otel-cf-workers`.
+ */
+export function createUrlBasedHeadSampler(config: SamplingConfig | null): Sampler {
+  const root = new URLBasedSampler(config ?? {});
+  return new ParentBasedSampler({ root });
+}
+
+// Re-export OTel API helper so callers can read `traceId` / build tags off
+// the active span without importing @opentelemetry/api directly.
+export { trace as _otelTrace };