Skip to main content

​
Request-metrics reader gates: four bounded surfaces

One rule governs every read on the request-metrics surface: the invariant check is the one claim that bills. A completed request writes exactly one telemetry row, keyed by request_id and attributed to your tenant; the aggregate counts or excludes that row, it never invents one. Four bounded surfaces decide which rows a given read sees and what the aggregate does with them:
  1. Window chain — which time range the query scans.
  2. Origin-feature gate — whether the advanced-analytics block is enabled for your workspace.
  3. Latency exclusion — which status codes the latency percentiles drop.
  4. Pipeline skip-list — which request paths never meter a row at all.
Treat each as a predicate the read resolves before it returns a number, not a setting you tune. The window inputs and the feature flag are tenant-owned controls; the skip-list and the 429 exclusion are platform-owned constants. None is a new invariant — all four already exist in the request-metrics pipeline and the stats surface.

​
1. Window chain: start, end, trailing bound

Every time-bounded read resolves its window through one precedence order: A value that fails shape validation is dropped silently — you get the default or a wider window, never a 400. Drift direction: drop. A malformed bound widens the range rather than erroring; the read degrades to a broader window, not a failure.

​
2. Origin-feature gate: the advanced-analytics flag

The /stats/analytics block (summary, channels, volume, delivery funnel) sits behind a per-tenant feature flag. With the flag off, the block returns 403 FEATURE_DISABLED; with it on, the window chain runs and returns the full payload. The always-on widgets (summary, channel-health, usage, activity, request-logs, dashboard) are available to every reader with the analytics:read scope regardless of the flag. Treat the 403 as “not enabled”, never as an error to retry. Drift direction: clamp. A disabled workspace gets a fixed 403, not a partial payload — the gate holds the surface closed rather than returning thin data.

​
3. Latency exclusion: 429s leave the percentiles

The head aggregate excludes rate-limit rejections (429) from the p50/p95 and the mean: a 429 is answered at the rate-limit guard in milliseconds, and folding it in would pull the rendered p50 far below your real handler latency. The volume counters still count every metered row — 429s included — so the error-rate and request-count cards stay honest. Drift direction: degrade. A 429 spike lowers the aggregate numerator while the latency percentile stays pinned to the served subset; the band coarsens toward served traffic, which is the intended shape, not a contradiction.

​
4. Pipeline skip-list: which paths never meter

The write side names its self-observation and keepalive paths on an explicit skip list — health probes, the analytics console’s own reads, presence heartbeats, and realtime transports — rather than a blanket “everything authenticated counts” line. A row that matches the skip list never enters the aggregate, so the percentiles measure genuine API traffic instead of the dashboard tab that rendered them. The read side mirrors the same constant to also exclude historical rows metered before the skip shipped, for up to a 30-day window. Drift direction: drop. A skipped path contributes zero rows; the counter reads operator-intent calls only, and a pre-skip row still sitting in a longer window thins over a few days rather than persisting.

​
See also