# Web vitals and setup health

DX-07 and DX-09. Which page got slower, as an issue with its numbers, and why replay, vitals or heatmap data is
missing, as cells that each say pass, warn, fail or unknown with one named fix.

Neither needs a new SDK call. The vitals ride the `pageload` span the browser SDK already sends when a page is first
hidden (`web_vital.lcp`, `.inp`, `.cls`, `.fcp`, `.ttfb`, and `browser.page`, the route template), and the setup answer
is read from what Bucker already stores: the outcome ledger, replay segments, the SDK inventory and the vitals series.

## The series

`vitals_route_hours` holds, for each project, route template, hour and vital, the **p75**, the sample count `n` and the
`basis` the figure was computed on. About 24 rows a route a day per vital, kept 13 months.

| Property | What it means |
| --- | --- |
| Exact p75 | Computed in the database with `percentile_cont` over the hour's values, not from a sketch. A CLS of 0.05 reads 0.05. |
| `basis: field_sampled` | The source is a pageload span the SDK sampled with `tracesSampleRate`. Head sampling is invisible to Bucker, so a figure is the p75 of **sampled page views**, never a share of traffic. `field_unsampled` is reserved for the 100 percent source DX-04 adds. |
| Off until an operator says | The rollup scans every tenant's pageload spans, so it sits behind the `web_vitals` pillar (`pillar.web_vitals.enabled`, off by default): with it off the rollups pass discovers no project and writes no row. |
| Trailing recompute | The rollups pass re-derives the last six hours on every run, so a span that arrives late (the SDK sends it when the page is hidden) moves the hour it belongs to. A window is replaced, never incremented. |
| Bounded input | A value counts only if it is a plain decimal within its bound (ten minutes for the millisecond vitals, 100 for CLS). A route is cut to 200 characters with control characters removed. At most 500 routes a window are kept per project; the rest fold into `__overflow__` with the totals exact. |
| No release or environment | The table has neither column. A regression names the route and the vital; the suspect change is joined from the issue's own timeline. |

## The regression detector

`vitals_regression`, version 1. It starts in **shadow**: it records findings and opens nothing until the labels pass has
judged it (precision 0.7 over 50 labels), like every new detector. For one route and vital:

1. The last `sustained_hours` (default 2) complete hours must each hold at least `min_samples` (default 200) page views
   and each sit **at or above** `median + mad_multiplier x scale` (default 3) of the **baseline**: the hourly p75s of the seven
   days that ended 24 hours ago. The day's gap keeps a regression that has just started out of its own baseline.
2. `scale` is the median absolute deviation, floored at 2 percent of the median and at a per-vital absolute floor, so a
   flat series does not fire on a one-bucket wobble.
3. The shift must **cross a rating boundary** (good to needs-improvement or worse; the web.dev bounds: LCP 2.5 s and
   4 s, INP 200 ms and 500 ms, CLS 0.1 and 0.25, FCP 1.8 s and 3 s, TTFB 0.8 s and 1.8 s) or, on a route whose baseline
   is already poor, rise by `poor_rise_percent` (default 25), so a poor page that gets worse still fires.
4. Fewer than 24 qualifying baseline hours, or a sustained hour under `min_samples`, is **not enough data**, never a
   guess.

One issue per shift: exception type `VitalsRegressionLCP` (and `INP`, `CLS`, `FCP`, `TTFB`), fingerprint on the route
template and the vital. A pass that runs every hour of one shift adds nothing; an open issue is not a decision again. The
detector **resolves** the issue when the series has stayed back under its limit for the sustained hours. An issue a
person resolved stays resolved until a new shift begins after its last event, and an **archived** issue is never
resolved, reopened or shown as open: the detector only manages `NEW`, `ONGOING` and `REGRESSED` issues.

### Thresholds

The four numbers are per project. They are one revisioned document (`vitals-config:<projectId>`, the same
compare-and-swap shape the friction detectors use), changed only through `dx_detectors_update`:

| Key | Default | Bounds | Fires more when |
| --- | --- | --- | --- |
| `sustained_hours` | 2 | 1 to 6 | lower |
| `mad_multiplier` | 3 | 2 to 10 | lower |
| `min_samples` | 200 | 20 to 5,000 | lower |
| `poor_rise_percent` | 25 | 10 to 100 | lower |

`dx_detectors_update` with `detector: "vitals_regression"` and `thresholds` derives `vitals_threshold.update` from what
would change: **SENSITIVE and asks a person**. A change that makes the detector fire less is a silence (30-day TTL,
after which the prior value returns unless a human keeps it); a change that fires more is a tighten and may be derived
below the registry's class; a mixed change is judged as a silence. It takes thresholds only: a suppression is a friction
act. Try the numbers first with `vitals_get` `include: ["backtest"]`.

## Reading it

| Door | What it serves |
| --- | --- |
| `vitals_get` (MCP, `event:read`, `dx` toolset) | Per route the p75 of each vital in the newest complete hour against the baseline, the sample count and `basis`, the rating, the state (`regressed`, `ok`, `not_enough_data`) and the open issue; at most five routes and three vitals a route, in at most **500 tokens** (what does not fit is counted in `routesOmitted`). `include: ["backtest"]` with `thresholds` adds what the last 14 days would have done under them (issues no longer opened or newly opened), up to 500 tokens more. |
| `GET /orgs/{org}/projects/{project}/replay/vitals` | The same read in full, for the dashboard. `backtest=true` with `mad_multiplier=4` and the other keys as query parameters adds the backtest. |

Route templates are text from your page: the MCP tool treats them as untrusted and lists the path in
`trust.untrustedFields`.

## Setup health

`dx_setup_health_get` (MCP, `project:read`, `dx` toolset, at most 600 tokens, 900 with `include: ["preview"]`) and
`GET /orgs/{org}/projects/{project}/replay/setup-health` answer "why is there no data" over the last seven days. Each
cell is `pass`, `warn`, `fail` or `unknown`; **unknown is an answer** (Bucker cannot tell from what it stores) and never
reads as a pass.

| Cell | Judged from | A fail names |
| --- | --- | --- |
| `consent_missing` | The consent mix the replay ingest writes when it refuses a segment (`basis = refused`), read through the product-analytics gate. With the gate closed the count was never recorded: `unknown`, reason `analytics_gate_closed`. | `send_replay_consent_state` |
| `replay_refused` | Segments the worker filed as `invalid` (they broke masking enforcement or failed validation; the worker uses one generic reason, so this cell does not tell the two apart). | `review_replay_masking` |
| `replay_silent` | A browser SDK that is sending, against stored segments and every refusal above. Names the cause: consent, refusals, sample rates of zero (`replay_config.widen`, a human act), or nothing at all (`enable_replay_in_sdk`). | as named |
| `replay_client_reports` | What the SDK reported dropping (`client_discard` outcomes). Labelled `client_reported`: the SDK's word, not Bucker's observation. | `review_client_report_reasons` |
| `replay_segments` | The stored segments' own fields: unmasked, evicted events, the SDK's stop reason. | `enforce_replay_masking` |
| `vitals_missing` | `pageload` spans with and without web vitals (counted over at most 50,000 spans; `scanCapped: 1` in the counts says the cap was hit), and the series' rows. | `enable_browser_tracing`, `update_browser_sdk` |
| `heatmaps_not_built` | `unknown` until DX-14 owns its checks. | none |

The answer also carries the replay configuration in force and its **version** (the settings row's last change, or
`default`), the stored segments' counts and the SDKs sending. A cell never names a person or a session. SDK names,
versions and the reasons an SDK reported are text a public key chose: the MCP tool sanitizes them and lists their paths
as untrusted.

Fixes are a person's act by name, or an existing tool. Where a fix is a governed act whose tool is not built yet
(`replay_config_narrow`, DX-02) it is a named human act until it is. `include: ["preview"]` for a candidate replay
configuration answers `not_available` (owner DX-02).

The same three questions are registered in the instrumentation check set (`replay_silent`, `vitals_missing`,
`heatmaps_not_built`). They answer `unknown` there, because the snapshot `instrumentation_health_get` reads (the SDK
inventory and the last hour of the outcome ledger) holds none of the data they need; the per-project answer is the cell of
the same name here.

## In the dashboard

The project's setup page shows the cells beside the DSN and the first-event diagnosis, and a vitals panel under them: one
row per route and vital with p75, baseline, change, rating, samples and the issue, a badge (not only a colour) on a
regression, `not enough data` with its reason, and a line saying the figures are sampled page views and naming the
detector's state.
