Client Performance Monitoring

Frontend performance only matters in production. Lab tools like Lighthouse measure performance under one synthetic device and one synthetic network; users hit your app from a mid-tier Android on a flaky 4G with a third-party tag manager loaded into the same main thread. Real User Monitoring (RUM) closes that gap by capturing per-session performance signals from the browsers of actual users, then aggregating them into the percentile-based metrics that engineering and SEO actually pay attention to. This article is a working reference for building or evaluating that pipeline: which metrics, captured how, transmitted with what guarantees, and attributed in a way that makes them actionable.

Mental model

Three layers, four hard problems.

Layers

1. Browser Performance APIs — PerformanceObserver, Navigation Timing, Resource Timing, Event Timing, Element Timing, Long Animation Frames, and User Timing — expose timing data with sub-millisecond resolution. The web-vitals library wraps these and patches the well-known edge cases.
2. Transport — navigator.sendBeacon() and fetch with keepalive survive page unload, so terminal-state metrics like CLS and INP actually reach the server. The right hook is visibilitychange, with pagehide as the bfcache-safe fallback.
3. Backend rollup — sampled per-session events stream through ingest, get aggregated per route at p75 / p98, and feed dashboards and alerts.

Hard problems

• Sampling — RUM is high-cardinality. Capturing 100% is rarely worth the bill; sample stable per-session so you can still slice by route or release.
• Attribution — LCP = 3.2s is unactionable. Capture the element selector, resource URL, and the long animation frames around it.
• Lifecycle — INP and CLS only finalize when the page is hidden or torn down. Anything that prevents bfcache (unload, beforeunload) silently drops both your data and the user’s back-button latency.
• Lab vs field divergence — synthetic and field always disagree, and field is the source of truth for Core Web Vitals scoring.

Core Web Vitals

Core Web Vitals are Google’s three load / interactivity / stability metrics. All three are evaluated at the 75th percentile of page visits — a page is “Good” only when at least 75% of visits clear the Good threshold¹.

LCP (Largest Contentful Paint)

LCP measures perceived load speed by tracking when the largest visible content element renders. Per the LCP spec, qualifying elements are:

• <img> and <image> inside <svg> (first frame for animated images)
• <video> (poster image, or first painted frame)
• elements with a CSS background-image set via url()
• block-level elements containing text nodes

Sizing rules:

• Only the visible portion within the viewport counts.
• For resized images, the smaller of intrinsic and rendered size wins (so blowing up a small image doesn’t game LCP).
• Margins, padding, and borders are excluded.
• Low-entropy placeholders and fully transparent elements are filtered out.

When LCP stops reporting. The browser stops dispatching new LCP candidates as soon as the user interacts (tap, scroll, keypress), because user interaction usually changes what’s onscreen. LCP therefore captures the initial loading experience only; ongoing rendering is INP’s job².

1new PerformanceObserver((entryList) => {2  const entries = entryList.getEntries()3  const lastEntry = entries[entries.length - 1] as LargestContentfulPaint45  console.log("LCP:", lastEntry.startTime)6  console.log("Element:", lastEntry.element)7  console.log("Size:", lastEntry.size)8  console.log("URL:", lastEntry.url) // populated for image LCPs9}).observe({ type: "largest-contentful-paint", buffered: true })

Thresholds³:

INP (Interaction to Next Paint)

INP replaced FID as the responsiveness Core Web Vital on March 12, 2024⁴. FID measured only the input delay of the first interaction; INP measures the worst end-to-end interaction latency across the whole page lifecycle. Chrome usage data shows roughly 90% of a user’s time on a page is spent after it loads, so first-input-only metrics miss most of the responsiveness story⁵.

Three phases of an interaction:

1. Input Delay — time from the input event until your event handlers actually start (main thread blocked by something else).
2. Processing Time — total time spent in your handlers for that interaction.
3. Presentation Delay — time from the last handler returning until the next frame is painted (recalc style, layout, paint, compositor).

Tracked interactions: mouse clicks, touchscreen taps, and keyboard presses (physical and on-screen keyboards both). Scroll, hover, and zoom are excluded — they don’t run synchronous handlers in the same way⁶.

Final value calculation. INP reports a single number per page lifecycle:

• Pages with fewer than 50 interactions report the worst single interaction latency.
• Pages with ≥ 50 interactions ignore the highest interaction for every additional 50 interactions, which is effectively the 98th percentile of interaction latencies⁷. This stops a single anomalous interaction from skewing the metric on a long-lived SPA.

1import { onINP } from "web-vitals/attribution"23onINP((metric) => {4  console.log("INP:", metric.value)5  console.log("Rating:", metric.rating)67  const { interactionTarget, interactionType, loadState } = metric.attribution8  console.log("Target selector:", interactionTarget) // CSS-selector string, "" if element was removed9  console.log("Interaction type:", interactionType) // 'pointer' | 'keyboard'10  console.log("Load state:", loadState) // 'loading' | 'dom-interactive' | 'dom-content-loaded' | 'complete'11})

Thresholds⁹:

CLS (Cumulative Layout Shift)

CLS measures visual stability — how much visible content unexpectedly shifts during the page lifecycle. Unexpected shifts misalign tap targets, lose reading position, and corrupt clicks.

Layout shift score per shift:

• Impact fraction — combined visible area of shifted elements (union of before and after positions) as a fraction of viewport area.
• Distance fraction — greatest distance any single element moved, divided by the viewport’s larger dimension.

Session windowing. CLS does not sum every shift across the page lifetime. Shifts are bucketed into session windows with a maximum 1-second gap between consecutive shifts and a hard 5-second cap on window duration. The reported CLS value is the maximum of all session-window scores, not their sum¹⁰. This is the change introduced in 2021 to stop long-lived SPAs from accumulating artificially large CLS values¹¹.

Expected vs unexpected. Shifts that occur within 500ms of user interaction (click, tap, keypress) carry the hadRecentInput flag and are excluded from CLS. Animations done with transform: translate() or transform: scale() don’t count either, because transforms don’t change element box geometry¹⁰.

1let clsValue = 02const clsEntries: LayoutShift[] = []34new PerformanceObserver((entryList) => {5  for (const entry of entryList.getEntries() as LayoutShift[]) {6    if (!entry.hadRecentInput) {7      clsValue += entry.value8      clsEntries.push(entry)9    }10  }11}).observe({ type: "layout-shift", buffered: true })

Common causes:

• Images or <video> without width / height attributes (or aspect-ratio CSS).
• Ads, embeds, or iframes that resize after load.
• Dynamically injected content above existing content.
• Web fonts causing FOIT / FOUT (use font-display: optional or size-adjust).

Thresholds¹²:

The 75th-percentile standard

All three metrics are evaluated at the 75th percentile of page loads in the field. A page passes if at least 75% of visits clear the Good threshold. Google chose p75 deliberately — the median is too lenient (half the users still get a poor experience), p95 is too sensitive to genuine outliers (one extreme device shifts the score), and p75 is a defensible balance across devices, networks, and locales¹.

Performance APIs

The metrics above are only the framing. To capture them — and to measure things web-vitals doesn’t measure for you — go straight to the underlying APIs.

PerformanceObserver

PerformanceObserver is the supported way to read the Performance Timeline. Unlike performance.getEntries(), it delivers entries asynchronously as they’re recorded.

1interface PerformanceMetricCallback {2  (entries: PerformanceEntryList): void3}45function observePerformance(6  entryType: string,7  callback: PerformanceMetricCallback,8  options: { buffered?: boolean } = {},9): () => void {10  if (!PerformanceObserver.supportedEntryTypes.includes(entryType)) {11    console.warn(`Entry type "${entryType}" not supported`)12    return () => {}13  }1415  const observer = new PerformanceObserver((list) => {16    callback(list.getEntries())17  })1819  observer.observe({20    type: entryType,21    buffered: options.buffered ?? true,22  })2324  return () => observer.disconnect()25}2627const disconnect = observePerformance("largest-contentful-paint", (entries) => {28  const lcp = entries[entries.length - 1]29  console.log("LCP:", lcp.startTime)30})

The buffered flag. With buffered: true, the observer receives entries that were recorded before observe() was called — essential for metrics like LCP, FCP, and TTFB that often fire before your monitoring code is parsed and executed¹³. Each entry type has its own buffer cap; once exceeded, new entries fall off the buffer.

Supported entry types (2026):

Navigation Timing

Navigation Timing Level 2 exposes the document-load pipeline as a single PerformanceNavigationTiming entry.

1function getNavigationMetrics(): Record<string, number> {2  const [nav] = performance.getEntriesByType("navigation") as PerformanceNavigationTiming[]3  if (!nav) return {}45  return {6    dnsLookup: nav.domainLookupEnd - nav.domainLookupStart,7    tcpConnect: nav.connectEnd - nav.connectStart,8    tlsHandshake: nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0,9    ttfb: nav.responseStart - nav.requestStart,10    downloadTime: nav.responseEnd - nav.responseStart,11    domInteractive: nav.domInteractive - nav.responseEnd,12    domComplete: nav.domComplete - nav.responseEnd,13    pageLoad: nav.loadEventEnd - nav.startTime,14    transferSize: nav.transferSize,15    encodedBodySize: nav.encodedBodySize,16    decodedBodySize: nav.decodedBodySize,17  }18}

Key timing points:

1startTime (= 0)2    → redirectStart / redirectEnd3    → fetchStart4    → domainLookupStart / domainLookupEnd     (DNS)5    → connectStart / connectEnd               (TCP)6    → secureConnectionStart                   (TLS)7    → requestStart8    → responseStart                           (TTFB)9    → responseEnd10    → domInteractive11    → domContentLoadedEventStart / End12    → domComplete13    → loadEventStart / loadEventEnd

Resource Timing

Resource Timing Level 2 exposes per-resource network timing for everything the document fetches (scripts, stylesheets, images, fonts, XHR/fetch requests).

1interface ResourceMetrics {2  name: string3  initiatorType: string4  duration: number5  transferSize: number6  cached: boolean7}89function getSlowResources(threshold = 1000): ResourceMetrics[] {10  const resources = performance.getEntriesByType("resource") as PerformanceResourceTiming[]1112  return resources13    .filter((r) => r.duration > threshold)14    .map((r) => ({15      name: r.name,16      initiatorType: r.initiatorType,17      duration: r.duration,18      transferSize: r.transferSize,19      cached: r.transferSize === 0 && r.decodedBodySize > 0,20    }))21    .sort((a, b) => b.duration - a.duration)22}2324new PerformanceObserver((list) => {25  for (const entry of list.getEntries() as PerformanceResourceTiming[]) {26    if (entry.duration > 2000) {27      console.warn("Slow resource:", entry.name, entry.duration)28    }29  }30}).observe({ type: "resource", buffered: true })

Cross-origin timing. By default, cross-origin resources expose only startTime, duration, and responseEnd; everything else is zeroed for privacy reasons. The origin serving the resource opts in by sending the Timing-Allow-Origin response header:

1Timing-Allow-Origin: *2Timing-Allow-Origin: https://example.com

This single header is the most common reason third-party metrics show up as a featureless black box in your dashboards.

Long Animation Frames (LoAF)

Long Animation Frames (Chromium 123+) reports any animation frame whose total work — script, style, layout, paint — exceeds 50ms, the threshold that breaks smooth ~60fps rendering¹⁵. Same threshold as Long Tasks, but with full per-script attribution and frame-level lifecycle data.

1new PerformanceObserver((list) => {2  for (const entry of list.getEntries() as PerformanceLongAnimationFrameTiming[]) {3    console.log("Long frame:", entry.duration, "ms")45    for (const script of entry.scripts) {6      console.log("  Script:", script.sourceURL)7      console.log("  Function:", script.sourceFunctionName)8      console.log("  Duration:", script.duration, "ms")9      console.log("  Invoker:", script.invoker) // 'user-callback' | 'event-listener' | …10    }11  }12}).observe({ type: "long-animation-frame", buffered: true })

Why pair LoAF with INP. Long Tasks tells you a 200ms task happened — it doesn’t tell you which script or which event. LoAF gives you scripts[] with source URL, function name, duration, and invoker, so you can correlate a poor INP attribution against the actual code that ran in the same frame¹⁴.

User Timing (custom metrics)

User Timing Level 3 lets you mark and measure application-specific points and intervals.

1performance.mark("feature-start")23// ... feature code executes ...45performance.mark("feature-end")6performance.measure("feature-duration", "feature-start", "feature-end")78performance.measure("time-to-feature", {9  start: 0,10  end: "feature-start",11})1213const measures = performance.getEntriesByType("measure")14for (const measure of measures) {15  console.log(`${measure.name}: ${measure.duration}ms`)16}1718performance.mark("api-call-complete", {19  detail: {20    endpoint: "/api/users",21    status: 200,22    cached: false,23  },24})

The detail payload (User Timing Level 3) is the cleanest way to enrich a custom mark without smuggling data through the name string.

Real-world custom metrics:

Data collection architecture

Capturing metrics is the easy half. The hard half is getting them off the page reliably and aggregating them without going broke.

Beacon transmission

navigator.sendBeacon() was designed for exactly this — analytics payloads that need to survive page unload. The browser queues the request and sends it even if the page navigates or closes, without blocking the next page load.

1interface PerformancePayload {2  url: string3  sessionId: string4  timestamp: number5  metrics: Record<string, number>6  attribution?: Record<string, unknown>7}89class MetricsCollector {10  private buffer: PerformancePayload[] = []11  private endpoint: string12  private maxBufferSize = 101314  constructor(endpoint: string) {15    this.endpoint = endpoint16    this.setupUnloadHandler()17  }1819  record(metrics: Record<string, number>, attribution?: Record<string, unknown>): void {20    this.buffer.push({21      url: location.href,22      sessionId: this.getSessionId(),23      timestamp: Date.now(),24      metrics,25      attribution,26    })2728    if (this.buffer.length >= this.maxBufferSize) {29      this.flush()30    }31  }3233  private flush(): void {34    if (this.buffer.length === 0) return3536    const payload = JSON.stringify(this.buffer)37    this.buffer = []3839    const sent = navigator.sendBeacon(this.endpoint, payload)4041    if (!sent) {42      fetch(this.endpoint, {43        method: "POST",44        body: payload,Show 16 hidden lines61  }6263  private getSessionId(): string {64    let id = sessionStorage.getItem("perf_session_id")65    if (!id) {66      id = crypto.randomUUID()67      sessionStorage.setItem("perf_session_id", id)68    }69    return id70  }71}

Why visibilitychange over unload.

• unload doesn’t fire reliably on mobile when the OS background-kills the tab.
• unload and beforeunload disqualify the page from bfcache in every modern engine, costing instant back-navigation and dropping your back-button UX¹⁶. Chromium is actively deprecating unload¹⁷.
• visibilitychange fires consistently when the tab is hidden, backgrounded, or navigated away — that is the actual moment the user “left”.

The full lifecycle (and the analytics hook for each transition) looks like this:

Payload size limits. The Beacon API spec deliberately doesn’t pin a number, but the underlying Fetch spec caps the sum of all in-flight keepalive request bodies for an origin at 64 KiB. Chromium and WebKit enforce this strictly; Firefox historically did not but is converging. Once the budget is exhausted, sendBeacon() returns false and a fetch({ keepalive: true }) request resolves to a network error¹⁹²⁰. Always check the return value and have a fallback.

Sampling strategies

RUM produces one event stream per session, plus per-resource and per-interaction streams on top. Capturing 100% of that on a high-traffic site is rarely worth the storage and ingestion cost. Sample stably so each session is either fully captured or fully dropped — random per-event sampling shreds your ability to do session-level joins later.

1type SamplingDecision = "always" | "sampled" | "never"23interface SamplingConfig {4  performanceRate: number // 0-1, e.g., 0.1 = 10%5  errorRate: number // Usually 1.0 (100%)6  sessionBased: boolean // Decide once per session7}89class Sampler {10  private config: SamplingConfig11  private sessionDecision: boolean | null = null1213  constructor(config: SamplingConfig) {14    this.config = config15    if (config.sessionBased) {16      this.sessionDecision = this.makeDecision(config.performanceRate)17    }18  }1920  shouldSample(type: "performance" | "error"): boolean {21    if (type === "error") {22      return this.makeDecision(this.config.errorRate)23    }2425    if (this.config.sessionBased && this.sessionDecision !== null) {26      return this.sessionDecision27    }2829    return this.makeDecision(this.config.performanceRate)30  }3132  private makeDecision(rate: number): boolean {33    return Math.random() < rate34  }35}3637const sampler = new Sampler({38  performanceRate: 0.1, // 10% of sessions39  errorRate: 1.0, // 100% of errorsShow 6 hidden lines

Sampling considerations:

Typical rates:

• Errors — 100% (always capture)
• Performance metrics — 1–10% session-sampled, depending on traffic
• Session replay — 0.1–1% (heaviest payloads)

Attribution for debugging

LCP = 3.2s is an alert, not a fix. Attribution data identifies the element, resource, and timing breakdown that produced the value, so the dashboard line you’re staring at is actionable.

1import { onLCP, onINP, onCLS } from "web-vitals/attribution"23function collectWithAttribution(): void {4  onLCP((metric) => {5    const { target, url, timeToFirstByte, resourceLoadDelay, resourceLoadDuration, elementRenderDelay } =6      metric.attribution78    sendMetric({9      name: "LCP",10      value: metric.value,11      attribution: {12        target, // CSS selector string for the LCP element13        url, // resource URL when the LCP is an image, undefined for text LCPs14        ttfb: timeToFirstByte,15        resourceLoadDelay,16        resourceLoadDuration,17        elementRenderDelay,18      },19    })20  })2122  onINP((metric) => {23    const { interactionTarget, interactionType, loadState, longAnimationFrameEntries } = metric.attribution2425    sendMetric({26      name: "INP",27      value: metric.value,28      attribution: {29        interactionTarget,30        interactionType,31        loadState,32        longFrames: longAnimationFrameEntries.length,33      },34    })35  })3637  onCLS((metric) => {38    const { largestShiftTarget, largestShiftTime, largestShiftValue, loadState } = metric.attribution3940    sendMetric({41      name: "CLS",42      value: metric.value,43      attribution: {44        shiftTarget: largestShiftTarget, // selector string for the first shifted element45        shiftTime: largestShiftTime,46        shiftValue: largestShiftValue,47        loadState,48      },49    })50  })51}

Bundle size. The standard web-vitals build is ~2 KB brotli; the attribution build adds ~1.5 KB on top. The 1.5 KB pays for itself the first time you have to chase down a regression — without attribution, you’re guessing²¹.

Error tracking

Capturing JavaScript errors

Comprehensive error tracking needs three handlers — synchronous errors, unhandled rejections, and resource-load failures — because no single event covers all of them.

1interface ErrorReport {2  type: "runtime" | "resource" | "promise" | "network"3  message: string4  stack?: string5  source?: string6  line?: number7  column?: number8  timestamp: number9  url: string10  userAgent: string11}1213class ErrorTracker {14  private endpoint: string15  private buffer: ErrorReport[] = []1617  constructor(endpoint: string) {18    this.endpoint = endpoint19    this.setupHandlers()20  }2122  private setupHandlers(): void {23    window.onerror = (message, source, line, column, error) => {24      this.report({25        type: "runtime",26        message: String(message),27        stack: error?.stack,28        source,29        line: line ?? undefined,30        column: column ?? undefined,31      })32      return false // don't suppress default handling33    }3435    window.addEventListener("unhandledrejection", (event) => {36      this.report({37        type: "promise",38        message: event.reason?.message || String(event.reason),39        stack: event.reason?.stack,40      })41    })4243    window.addEventListener(44      "error",45      (event) => {46        if (event.target !== window && event.target instanceof HTMLElement) {47          const target = event.target as HTMLImageElement | HTMLScriptElement | HTMLLinkElement48          this.report({49            type: "resource",50            message: `Failed to load ${target.tagName.toLowerCase()}`,51            source: (target as HTMLImageElement).src || (target as HTMLLinkElement).href,52          })53        }54      },55      true, // capture phase — resource errors don't bubble56    )57  }5859  private report(error: Omit<ErrorReport, "timestamp" | "url" | "userAgent">): void {60    const fullError: ErrorReport = {61      ...error,62      timestamp: Date.now(),63      url: location.href,64      userAgent: navigator.userAgent,65    }6667    this.buffer.push(fullError)68    this.flush()69  }Show 10 hidden lines

Stack-trace parsing

Production JavaScript is minified, so raw stack traces are useless on their own. Source maps restore original file/line information server-side.

1interface ParsedFrame {2  function: string3  file: string4  line: number5  column: number6}78function parseStackTrace(stack: string): ParsedFrame[] {9  if (!stack) return []1011  const lines = stack.split("\n")12  const frames: ParsedFrame[] = []1314  const chromeRegex = /at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/15  const firefoxRegex = /(.*)@(.+?):(\d+):(\d+)/1617  for (const line of lines) {18    const match = chromeRegex.exec(line) || firefoxRegex.exec(line)1920    if (match) {21      frames.push({22        function: match[1] || "<anonymous>",23        file: match[2],24        line: parseInt(match[3], 10),25        column: parseInt(match[4], 10),26      })27    }28  }2930  return frames31}

Server-side, use the source-map library (or any vendor SDK — Sentry, Datadog, Bugsnag all do this for you) to resolve bundle.min.js:1:32417 to src/feature/x.tsx:42:12.

Error grouping

Without grouping, every error instance creates a separate alert. Fingerprinting consolidates identical errors into a single issue.

1function generateErrorFingerprint(error: ErrorReport): string {2  const parts = [error.type, normalizeMessage(error.message), error.stack ? getTopFrame(error.stack) : "no-stack"]34  return hashString(parts.join("|"))5}67function normalizeMessage(message: string): string {8  return message9    .replace(/\d+/g, "<N>") // numbers10    .replace(/'[^']+'/g, "'<S>'") // single-quoted strings11    .replace(/"[^"]+"/g, '"<S>"') // double-quoted strings12    .replace(/\b[a-f0-9]{8,}\b/gi, "<ID>") // hex IDs13}1415function getTopFrame(stack: string): string {16  const frames = parseStackTrace(stack)17  if (frames.length === 0) return "unknown"1819  const top = frames[0]20  return `${top.file}:${top.line}` // exclude column — varies with minification21}2223function hashString(str: string): string {24  let hash = 025  for (let i = 0; i < str.length; i++) {26    hash = (hash << 5) - hash + str.charCodeAt(i)27    hash |= 028  }29  return hash.toString(16)30}

Lab vs field data

Fundamental differences

When to use each

Lab data (Lighthouse, WebPageTest, DebugBear):

• Pre-deployment validation.
• Regression testing in CI (assert on specific Lighthouse scores or budget files).
• Debugging specific issues against a stable baseline.
• Comparing configurations (CDN settings, image formats, hydration strategies).

Field data (your RUM, plus CrUX for industry context):

• Understanding real user experience.
• Identifying issues lab doesn’t catch (third-party scripts, real device variability, browser engine quirks).
• Monitoring production performance per-route, per-release.
• Correlating performance with business metrics (conversion, bounce, retention).

The gap

Lab and field measurements regularly disagree by significant margins because:

1. Device diversity — lab uses one consistent device profile; users span a 10× CPU range.
2. Network conditions — lab throttles to a stable profile; real networks burst, drop, and reconnect.
3. User behavior — lab follows a scripted path; users interact unpredictably and trigger latent code paths.
4. Third-party content — ads, widgets, and embeds load and behave differently in production traffic patterns.
5. Cache state — lab usually tests cold; users often arrive warm.

As web.dev puts it: “lab measurement is not a substitute for field measurement.” Both tools answer different questions; ship both into your workflow.

The web-vitals library

Google’s web-vitals library is the de-facto reference implementation for Core Web Vitals in the browser. It wraps the raw APIs and patches the long tail of edge cases that homegrown collectors typically get wrong.

Why use it over raw APIs

The library handles:

• Background-tab detection — metrics shouldn’t include time the page was hidden.
• bfcache restoration — resets per-page metric state on pageshow with persisted: true.
• Iframe and prerender considerations.
• Mobile-specific timing quirks — particularly around input timing.
• Final-value semantics — INP and CLS only finalize on the right lifecycle event.

Basic usage

1import { onCLS, onINP, onLCP, onFCP, onTTFB } from "web-vitals"23function sendToAnalytics(metric: { name: string; value: number; delta: number; id: string; rating: string }): void {4  const body = JSON.stringify({5    name: metric.name,6    value: metric.value,7    delta: metric.delta,8    id: metric.id,9    rating: metric.rating,10    page: location.pathname,11  })1213  navigator.sendBeacon("/api/analytics", body)14}1516onCLS(sendToAnalytics)17onINP(sendToAnalytics)18onLCP(sendToAnalytics)19onFCP(sendToAnalytics)20onTTFB(sendToAnalytics)

Attribution build

1import { onLCP, onINP, onCLS } from "web-vitals/attribution"23onLCP((metric) => {4  console.log("LCP value:", metric.value)5  console.log("LCP target selector:", metric.attribution.target)6  console.log("Resource URL:", metric.attribution.url)7  console.log("TTFB:", metric.attribution.timeToFirstByte)8  console.log("Resource load delay:", metric.attribution.resourceLoadDelay)9  console.log("Element render delay:", metric.attribution.elementRenderDelay)10})1112onINP((metric) => {13  console.log("INP value:", metric.value)14  console.log("Interaction type:", metric.attribution.interactionType) // 'pointer' | 'keyboard'15  console.log("Interaction target:", metric.attribution.interactionTarget) // selector string16  console.log("Load state:", metric.attribution.loadState)17  console.log("Long frames:", metric.attribution.longAnimationFrameEntries)18})1920onCLS((metric) => {21  console.log("CLS value:", metric.value)22  console.log("Largest shift target:", metric.attribution.largestShiftTarget)23  console.log("Largest shift value:", metric.attribution.largestShiftValue)24  console.log("Largest shift time:", metric.attribution.largestShiftTime)25})

Key API details

The delta property. Metrics like CLS update multiple times as new shifts are observed. delta is the change since the last report; for analytics platforms that don’t support metric updates, sum the deltas client-side or server-side.

The id property. Stable identifier for this metric instance — use it to deduplicate or aggregate multiple reports for the same page view (CLS in particular).

Single call per page. Call each metric function exactly once per page load. Multiple calls create multiple PerformanceObserver instances and produce duplicate, conflicting reports.

Real-world implementations

Sentry Performance

• JavaScript SDK instruments fetch, XHR, framework components.
• Distributed tracing connects browser spans to backend spans via traceparent.
• Web Vitals captured automatically via the web-vitals library.
• Release tracking flags performance regressions across deploys.
• Heavy on per-error attribution (source maps, breadcrumbs).

Datadog RUM

• Lightweight SDK loaded asynchronously.
• Session-based collection with configurable sampling.
• Automatic Core Web Vitals, resource timing, long tasks.
• Session Replay overlay for debugging individual sessions.
• Joins to Datadog APM traces by trace_id.

Vercel Speed Insights

• Minimal script injection in Next.js builds.
• Sends to Vercel’s analytics backend.
• Core Web Vitals with Next.js-specific route attribution.
• Per-route breakdown and per-deploy comparison.

Self-hosted (SpeedCurve, Calibre, Grafana Faro, OSS stack)

• Time-series storage for high-cardinality metrics (ClickHouse, TimescaleDB, M3, Druid).
• Aggregation pipelines for percentile rollups (Flink, Materialize, in-DB rollups).
• Visualization via Grafana, Superset, or vendor-specific dashboards.
• The honest reason teams build this themselves is data-residency, billing predictability, or wanting unfettered access to raw events.

Operational takeaways

1. Use the web-vitals library for the three Core Web Vitals. The raw APIs are for understanding and for custom metrics; for CWVs, the edge-case surface is too large to reimplement.
2. Beacon on visibilitychange, fall back to pagehide. Never use unload or beforeunload — they break bfcache and drop your data.
3. Sample stably per session. Random per-event sampling shreds your ability to do session-level joins; hash the session ID.
4. Always capture attribution. A 1.5 KB bundle delta pays for itself the first time you have to debug a regression.
5. Treat lab and field as different tools. Lab gates regressions in CI; field tells you what users experience. Both are necessary.

Appendix

Prerequisites

• Browser Performance APIs (PerformanceObserver, timing interfaces).
• HTTP basics (request/response timing, headers).
• JavaScript event handling and the page lifecycle.

Terminology

Quick reference

References and footnotes