@decocms/start 4.1.0 → 4.2.0

package/package.json

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

package/src/sdk/sampler.test.ts

@@ -5,14 +5,29 @@ import {
   SamplingDecision,
 } from "@opentelemetry/sdk-trace-base";
 import { describe, expect, it } from "vitest";
-import { createUrlBasedHeadSampler, decodeSamplingConfig, URLBasedSampler } from "./sampler";
+import {
+  createUrlBasedHeadSampler,
+  DEFAULT_SAMPLE_RATIO,
+  decodeSamplingConfig,
+  URLBasedSampler,
+} from "./sampler";
 
-const TRACE_ID = "0000000000000000ffffffffffffffff";
+// 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) {
+function decide(sampler: URLBasedSampler, path: string, traceId = LOW_TRACE_ID) {
   return sampler.shouldSample(
     ROOT_CONTEXT,
-    TRACE_ID,
+    traceId,
     "span-name",
     SpanKind.SERVER,
     { "url.path": path },
@@ -21,7 +36,28 @@ function decide(sampler: URLBasedSampler, path: string) {
 }
 
 describe("URLBasedSampler", () => {
-  it("falls back to default ratio when no rule matches", () => {
+  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);
   });
@@ -40,7 +76,7 @@ describe("URLBasedSampler", () => {
 
   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, {}, []);
+    const result = s.shouldSample(ROOT_CONTEXT, LOW_TRACE_ID, "noop", SpanKind.INTERNAL, {}, []);
     expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
   });
 
@@ -50,7 +86,7 @@ describe("URLBasedSampler", () => {
       rules: [{ pattern: "^/wanted", ratio: 1.0 }],
     });
     const ok = (attrs: Record<string, string>) =>
-      s.shouldSample(ROOT_CONTEXT, TRACE_ID, "n", SpanKind.SERVER, attrs, []);
+      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);
@@ -103,18 +139,20 @@ describe("createUrlBasedHeadSampler", () => {
     expect(sampler).toBeInstanceOf(ParentBasedSampler);
   });
 
-  it("applies the default-ratio = 1.0 when config is null", () => {
-    // Smoke test only — sampler internals are validated above.
+  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,
-      TRACE_ID,
+      HIGH_TRACE_ID,
       "n",
       SpanKind.SERVER,
       { "url.path": "/" },
       [],
     );
-    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(result.decision).toBe(SamplingDecision.NOT_RECORD);
   });
 });
 

package/src/sdk/sampler.ts

@@ -9,6 +9,13 @@
  * decision when one exists (i.e. distributed traces are kept 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:
@@ -41,12 +48,23 @@ export interface SamplingRule {
 }
 
 export interface SamplingConfig {
-  /** Default sample ratio applied when no rule matches. Defaults to 1.0 (always sample). */
+  /**
+   * 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;
@@ -61,7 +79,7 @@ export class URLBasedSampler implements Sampler {
   private readonly rules: CompiledRule[];
 
   constructor(config: SamplingConfig = {}) {
-    this.defaultSampler = ratioToSampler(config.default ?? 1.0);
+    this.defaultSampler = ratioToSampler(config.default ?? DEFAULT_SAMPLE_RATIO);
     this.rules = (config.rules ?? []).map((rule) => ({
       re: new RegExp(rule.pattern),
       sampler: ratioToSampler(rule.ratio),
@@ -128,7 +146,7 @@ function extractPath(attrs: Attributes): string | null {
 
 /**
  * Decode a base64-encoded `OTEL_SAMPLING_CONFIG` value into a `SamplingConfig`.
- * Returns `null` (caller falls back to default ratio 1.0) on:
+ * Returns `null` (caller falls back to `DEFAULT_SAMPLE_RATIO`, currently 0.1) on:
  *  - missing / empty input
  *  - invalid base64
  *  - JSON parse failure