@decocms/start 4.6.0 → 5.0.0

package/src/sdk/sampler.test.ts

@@ -1,165 +0,0 @@
-import { ROOT_CONTEXT, SpanKind } from "@opentelemetry/api";
-import {
-  AlwaysOnSampler,
-  ParentBasedSampler,
-  SamplingDecision,
-} from "@opentelemetry/sdk-trace-base";
-import { describe, expect, it } from "vitest";
-import {
-  createUrlBasedHeadSampler,
-  DEFAULT_SAMPLE_RATIO,
-  decodeSamplingConfig,
-  URLBasedSampler,
-} from "./sampler";
-
-// Two trace IDs at opposite ends of the TraceIdRatioBased accumulator.
-// `accumulate(traceId)` xors the trace ID in 8-hex-char chunks; threshold at
-// ratio R is `floor(R * 0xffffffff)`. See
-// `@opentelemetry/sdk-trace-base/src/sampler/TraceIdRatioBasedSampler`.
-//
-//   LOW:  0x00000000 ^ 0x00000000 ^ 0xffffffff ^ 0xffffffff = 0
-//         → 0 < threshold for any ratio > 0 → SAMPLED at any ratio > 0
-//   HIGH: 0xffffffff ^ 0x00000000 ^ 0x00000000 ^ 0x00000000 = 0xffffffff
-//         → never below threshold for ratio < 1.0 → DROPPED at any ratio < 1
-const LOW_TRACE_ID = "0000000000000000ffffffffffffffff";
-const HIGH_TRACE_ID = "ffffffff000000000000000000000000";
-
-function decide(sampler: URLBasedSampler, path: string, traceId = LOW_TRACE_ID) {
-  return sampler.shouldSample(
-    ROOT_CONTEXT,
-    traceId,
-    "span-name",
-    SpanKind.SERVER,
-    { "url.path": path },
-    [],
-  );
-}
-
-describe("URLBasedSampler", () => {
-  it("exposes 0.1 as the framework-wide default sample ratio", () => {
-    expect(DEFAULT_SAMPLE_RATIO).toBe(0.1);
-  });
-
-  it("defaults to DEFAULT_SAMPLE_RATIO (0.1) when config omits `default`", () => {
-    const s = new URLBasedSampler();
-    // LOW_TRACE_ID accumulates to 0 — sampled at any ratio > 0, including 0.1.
-    expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
-    // HIGH_TRACE_ID accumulates to ~uint32 max — dropped at 0.1, would be
-    // kept only at ratio ~= 1. This is the assertion that catches an
-    // accidental revert to the old `?? 1.0` fallback.
-    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(SamplingDecision.NOT_RECORD);
-  });
-
-  it("explicit `default: 1` opts in to AlwaysOn (records every trace)", () => {
-    const s = new URLBasedSampler({ default: 1 });
-    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(
-      SamplingDecision.RECORD_AND_SAMPLED,
-    );
-  });
-
-  it("falls back to provided 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, LOW_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, LOW_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 DEFAULT_SAMPLE_RATIO when config is null", () => {
-    const sampler = createUrlBasedHeadSampler(null);
-    // High-accumulating trace ID is dropped at 0.1 — proves the ParentBased
-    // wrapper inherits the URLBasedSampler default and isn't accidentally
-    // forcing AlwaysOn.
-    const result = sampler.shouldSample(
-      ROOT_CONTEXT,
-      HIGH_TRACE_ID,
-      "n",
-      SpanKind.SERVER,
-      { "url.path": "/" },
-      [],
-    );
-    expect(result.decision).toBe(SamplingDecision.NOT_RECORD);
-  });
-});
-
-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

@@ -1,213 +0,0 @@
-/**
- * URL-based head sampler — port of `deco-cx/deco/observability/otel/samplers/urlBased.ts`.
- *
- * **No longer wired into `instrumentWorker` by default.** As of 4.4.0 the
- * recommended path for trace sampling is Cloudflare's wrangler-level
- * `observability.traces.head_sampling_rate`, which is one global rate per
- * Worker. This module stays as an opt-in escape hatch for sites that need
- * URL-pattern-aware sampling (e.g. always trace `/checkout`, sample
- * homepages at 1%) — those sites must wire OTel themselves outside the
- * default `instrumentWorker` flow.
- *
- * The sampler reads `OTEL_SAMPLING_CONFIG` (base64-encoded JSON) 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 stay consistent end
- * to end).
- *
- * **Default ratio.** When no `default` is provided in the config (or the env
- * var is unset entirely), the sampler keeps **10%** of traces. Production
- * storefront traffic at full sampling will burn HyperDX ingest quotas
- * quickly — for an unconfigured site we'd rather drop 90% than overspend by
- * default. Sites that genuinely want every trace recorded must opt-in
- * explicitly with `OTEL_SAMPLING_CONFIG` setting `default: 1`.
- *
- * @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 }
- *   ]
- * }
- * ```
- *
- * @deprecated Slated for removal in 5.0.0 unless a site declares an active
- *   need. Use Cloudflare's `head_sampling_rate` first.
- */
-
-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 **0.1**
-   * (10% sampled) when omitted. Set to `1` to record every trace
-   * (only do this when you need a full debug stream and accept the cost).
-   */
-  default?: number;
-  /** Ordered list of rules. First match wins. */
-  rules?: SamplingRule[];
-}
-
-/**
- * Default ratio applied by `URLBasedSampler` when neither the config nor a
- * matching rule specifies one. Centralised so tests + docs share a single
- * source of truth.
- */
-export const DEFAULT_SAMPLE_RATIO = 0.1;
-
-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 ?? DEFAULT_SAMPLE_RATIO);
-    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_SAMPLE_RATIO`, currently 0.1) 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.
- * Wire as the `headSampler` for any custom OTel SDK setup (e.g. a site
- * that opts back into `@microlabs/otel-cf-workers` outside the default
- * `instrumentWorker` flow).
- */
-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 };