Browser performance diagnostics

Use Metrics → Web vitals → Diagnostics to connect a slow page view with its navigation phases, slow resources and reported request trace. Overview keeps the lightweight tracker's historical measurements; the sources are separate.

Install

1. Open Collection settings in the correct environment.
2. Add a static page label such as checkout | Checkout and enable collection.
3. Install the browser package and connect your existing consent controls.

import { createClient } from "@saaspro/browser";
import { startBrowserDiagnostics } from "@saaspro/browser/rum";

const spm = createClient().init({
  key: "YOUR_PUBLIC_INGEST_KEY",
  host: "https://saaspro.dev",
  consent: "pending",
  vitals: false,
});
const diagnostics = startBrowserDiagnostics(spm, {
  page: "checkout",
  consent: "pending",
});

// Only after the visitor grants the corresponding consent:
spm.consent("granted");
diagnostics.setConsent("granted");

// Apply changed consent immediately:
// diagnostics.setConsent("revoked");

Use the environment's public ingest key and configure its allowed application origin. Disable lightweight vitals when adopting diagnostics to avoid maintaining two separate sources. The optional entry bundles Google's web-vitals 6.2.1; it does not add that library to the default tracker.

Label resources and connect traces

Add static resource labels in Collection settings, then map known resources:

const diagnostics = startBrowserDiagnostics(spm, {
  page: "checkout",
  consent: "granted", // Supply the visitor's actual consent state.
  resourceLabel: entry => {
    const path = new URL(entry.name).pathname;
    return path.endsWith("/checkout.js") ? "checkout_bundle" : null;
  },
  traceContext: () => currentPageSpan?.spanContext(),
  onDelivery: receipt => console.log(receipt.accepted, receipt.outcome),
});

The callback's URL stays local. Only approved label keys, resource kinds and numeric timings are sent. Do not use customer identifiers as labels or releases. Releases accept letters, digits, dots, underscores, colons, plus signs and hyphens. Trace context must be the actual page-related span; diagnostics never invents a trace or changes request headers. A link appears only if the reported span is retained in the same application and environment.

Read the measurements

• Each hard navigation and back/forward-cache restoration gets a view UUID. Metric IDs and sequences update that view; repeated reports do not multiply p75 samples. INP/CLS can change as a visitor continues using the page.
• Reports cover observed views. Missing delivery, sampling, browser support and incomplete interactions affect coverage. Missing INP does not mean zero INP.
• The waterfall retains the 25 slowest of at most 200 observed resources. Times start at navigation or restoration; overlapping durations are not additive.
• Cross-origin details require browser timing permission. Unavailable phases and byte counts are null; a zero byte count alone does not prove a cache hit.
• Navigation phase durations differ from DOM/load milestones, which are offsets from navigation start. A BFcache restoration has no new navigation phases.
• Soft/SPA navigation measurements are not enabled. A static page key describes the entire document lifecycle, not each client-side route.

The SDK uses standard web-vitals callbacks without exporting attribution entries, DOM nodes, selectors, titles, raw URLs, IPs or visitor IDs. Starting after consent may include buffered numeric timings from the current document. Consent, identity or session changes abort pending exports and suspend diagnostics until the next hard navigation/BFcache restoration, so old measurements cannot be reattributed. stop() is final for that client in the current document. The shared measurement observers register at most once per loaded SDK module; stopped clients receive no callbacks. flush() makes a best-effort acknowledged export; a network failure can be retried explicitly. Page-hide delivery is best effort, not guaranteed.

Limits and administration

Collection defaults off. Configure 1–100% stable view sampling, 100–50,000 new views per UTC day and 1–30 retained days, capped by application retention. Each environment retains at most 50,000 views and 128 MiB of payload, excluding database overhead. A view can update 1,000 times within a 24-hour arrival window. Requests are bounded to 24 KiB and five seconds. The receipt panel shows accepted updates, duplicates, sampling and budget refusals; these are attempts, not unique views.

Console changes require Metrics write, a recent passkey and an audit reason. Deletion removes a view and rejects its replay for 30 days. Retention hides older views immediately; the worker performs bounded physical cleanup every five minutes. Read-only Management API:

GET /api/v1/apps/ORG/APP/metrics/rum?env=production&days=7&vital=LCP
Authorization: Bearer YOUR_PERSONAL_MANAGEMENT_TOKEN

Optional filters: page, release, view (UUID), offset (multiples of 25). The token needs Metrics read in the selected application. Raw ingest keys cannot read reports.

References: web-vitals, Resource Timing.