Real-user web vitals

Web vitals tell you how fast your pages feel to the people using them: measured in their browsers, on their devices and networks, not in a lab. Belvador's browser SDK collects them from version 0.7.0; they are kept on your own node like everything else and shown under Metrics → Web vitals.

They are off by default. Nothing about web vitals is loaded or sent until you turn them on.

Turn them on#

import { init } from "@belvador/browser"; // or @belvador/react, @belvador/tanstack-start/clientinit({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  // Real-user LCP, INP, CLS, FCP and TTFB from 10 % of page loads.  webVitals: { sampleRate: 0.1 },});

Works the same with @belvador/react and @belvador/tanstack-start/client. Your workspace node needs agent 0.1.40 or newer (nodes update themselves); until then the Web vitals tab says the node has to update first.

With a consent banner#

import { init } from "@belvador/browser";init({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  webVitals: {    sampleRate: 0.1,    // Asked before every send: nothing leaves until your consent banner says yes.    consent: () => window.localStorage.getItem("analytics-consent") === "granted",  },});

consent is asked again before every send, so a visitor who says yes halfway through a visit is measured from then on, and one who withdraws is not measured again.

What is measured#

The SDK uses Google's web-vitals library (attribution build). Each vital is shown at the 75th percentile (p75) of its samples and rated with the web.dev thresholds:

LCP, CLS and INP are the Core Web Vitals. CLS and INP are final only when the page is hidden or closed, so they arrive then; LCP, FCP and TTFB arrive as soon as they are known. Not every browser reports every vital (see the library's browser support) — page loads in such browsers simply add fewer samples.

What leaves the page#

Each measurement is one Sentry log item with body = "browser.web_vital" on your project's browser DSN, with these attributes only:

/posts/123?token=abc#x is sent as /posts/:id; token=abc never leaves the page. The log then goes through the same privacy rules as every other log on your node (see Privacy), before anything is stored. LCP, FCP and TTFB use the route the page was loaded on; INP and CLS the route shown when the page was hidden, so single-page apps attribute them to the screen the visitor was on.

Words in a path are kept as written: without a route template, /w/acme/settings stays /w/acme/settings, so customer, team or project names in your paths would be stored with every measurement. Send the route instead:

• TanStack Start / TanStack Router — with createRouter(withBelvadorRouter({ routeTree, … })) the SDK names the route from your route tree from version 0.9.2: /w/acme/settings is sent as /w/:slug/settings. Nothing else to set.

• Any other app — pass webVitals: { route: (path) => … } and return the template, for example from your router's matched route.

When a route function answers nothing (no route matches) or throws, the measurement is sent with the path /:unmatched — never the visited path.

Measurements of one page load are sent together — a second after the first one, or as soon as five are waiting — and, when the page is hidden or closed, at once with keepalive. They are never kept for later: web vitals do not use the offline queue, because an old measurement is worth less than a fresh one.

Size and speed#

Turning web vitals off adds no web-vitals code: the release gate checks that the main bundle does not contain the library. When they are on, the library and the SDK's web-vitals code arrive as their own file of about 6 KB gzip, downloaded after init only on the page loads that are sampled. Measuring does not block the page: the browser reports each value through its performance observers, and the SDK sends a small batch a second later, or at once when the page is hidden.

On your node#

Each measurement is kept as a log, and your node also adds it to a histogram metric — browser.web_vital.lcp, .inp, .cls, .fcp, .ttfb — keyed by url.path and rating. A project keeps at most 200 routes as their own series (counted over 24 hours); measurements on further routes are counted under the route other, while their logs keep the real path. Each measurement counts toward the project's log volume.

Metrics → Web vitals shows, for one project, environment and window (up to 7 days):

• the p75 of LCP, INP and CLS with their rating, FCP and TTFB beside them, and the share of good samples;

• the distribution of one vital, bucket by bucket, coloured by rating;

• the elements behind samples that were not good, most frequent first;

• the busiest routes with their p75 — select a route to see only its numbers.

Below 100 samples a p75 is labelled estimate: with few samples one slow visit moves it a lot.

Alerts#

The metrics are ordinary metrics, so a metric monitor can watch them — for example browser.web_vital.lcp, aggregation p75, filter url.path = /checkout, above 2500 for 15 minutes. Create monitor on the Web vitals tab fills in the vital and route for you.

API and AI agents#

The same summary is available over the REST API with a metrics:read token:

curl -s "https://api.belvador.dev/v1/projects/<project-id>/web-vitals?environment=production&path=/posts/:id"   -H "Authorization: Bearer $BELVADOR_TOKEN"

AI agents can read the histograms with the MCP tool query_metrics (aggregation p75). Coverage can expect web vitals from a browser surface; the cell turns verified when your node has stored a measurement in that environment.

Turn them off#

Remove webVitals (or set sampleRate: 0) and deploy. Measurements already stored stay until the project's log and metric retention removes them.