feat(telemetry): sample rates are code defaults; the CMS block's win

Merged
TL
3h ago
+280-165

Why

telemetry.limits capped the CMS block's sample rates at min(content, code), with code's cap defaulting to 0.1 for errors and 0 for traces. So errorSampleRate: 1 saved in Studio silently became 10%, and no site could turn on traces from content. We want a merge instead: code sets defaults, and the CMS wins when it sets a rate.

Change

  • createCMS({ telemetry: { defaults: { errorSampleRate?, traceSampleRate? } } }) replaces limits. It gives the rates content doesn't save, each falling back to the built-in 0.05 and 0. A rate content saves wins, from 0 to 1, up or down, with no cap.
  • limits is gone from TelemetryConfig. A config that still passes it (JS, or a cast) throws a TypeError at createCMS naming telemetry.defaults. Released as a minor (8.17.0) on purpose. No known site passes limits; osklen and demo-storefront don't.
  • cms.settings() fills each unsaved rate from code's defaults. The built-in cms-settings block can't see code's config, so it now returns the telemetry switches filled in and the sample rates only as saved.
  • TelemetryPipeline.apply falls back to the destination's defaults; the pipeline starts on them.
  • The per-batch limits (MAX_LOGS 200, MAX_SPANS 1,000 per 10 s flush) are unchanged and still bound a burst.
  • Skill references (deco-storefront-performance, deco-v7-to-v8-migration) and the observability conformance fixture are updated.

The spec change is in https://github.com/deco-sites/docs-tanstack/pull/35. Per CLAUDE.md the docs win, so the conformance tests were rewritten to the new claims (tel-24, tel-17, X31, AR-06, AR-60, dd-15) rather than relaxed.

Verification

  • bunx vitest run packages/blocks: 2287 pass, 0 fail.
  • bun run check (typecheck, biome, knip): clean, except one biome warning that was already there.
  • skills:check and skills:readme:check: ok.

šŸ¤– Generated with Claude Code

Summary by cubic

Changes telemetry sampling so content's sample rates win instead of being capped: a rate saved in Studio is used as-is, from 0 to 1, so sites can now raise error sampling and turn on traces from content.

telemetry.limits (which silently capped errorSampleRate: 1 at 10% and kept traces off) is replaced by telemetry.defaults: the rates code gives when content saves none, each falling back to the built-in 0.05 and 0.

  • A config still passing limits throws a TypeError at createCMS naming telemetry.defaults; no known site passes it.
  • cms.settings() fills each unsaved rate from code's defaults; the built-in cms-settings block, which can't see code's config, returns sample rates only as saved.
  • TelemetryPipeline.apply starts on the destination's defaults instead of the built-ins.
  • Per-batch limits (200 logs, 1,000 spans per flush) still bound a burst.