Skip to main content

Web Vitals

Web Vitals​

The Embrace SDK automatically reports Web Vital metrics from your application providing visibility into user perceived performance issues.

How Web Vital Instrumentation Works​

The SDK leverages the web-vitals package to record Web Vital scores. This includes all metrics from the package, such as the Core Web Vitals: Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and Interaction to Next Paint (INP).

The SDK also uses the @opentelemetry/instrumentation-document-load package to record Spans related to the page's initial load. When possible this information is combined in User Timelines with LCP reports to provide more context in the Embrace Dashboard.

This automatic instrumentation gives you immediate visibility into performance issues encountered by your users without requiring manual code changes.

Data Captured​

For each Web Vital, the SDK captures:

  • The score and rating from the Web Vital report
  • The timestamp most attributed to the score
  • The element most attributed to the score
  • The URL of the page being reported on
  • The navigation the score belongs to, including soft navigations in single-page applications

Single-page applications​

In single-page applications (SPAs), the SDK reports Web Vitals for each soft navigation in addition to the initial page load. Each route change resets the metrics, and scores are attributed to the URL of the view they were measured on. See SPA Navigation for details on how the SDK handles route changes.

A few things to note:

  • Time to First Byte (TTFB) is only reported for full page loads, since no new document is fetched during a soft navigation
  • Soft navigation reporting relies on the Soft Navigations API, currently available in Chromium-based browsers from version 151. In browsers without support, Web Vitals are only measured for the initial page load. See Report metrics for soft navigations in the web-vitals package documentation for more detail on how soft navigations are measured

Soft navigation reporting is enabled by default. If you would rather only report Web Vitals for full page loads, you can turn it off when initializing the SDK:

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  defaultInstrumentationConfig: {
    'web-vital': {
      reportSoftNavs: false,
    },
  },
});

Integration with Other Features​

Web Vitals integrates with other Embrace features:

  • Web Vital reports are associated with the current session and, if possible, correlated with page load information and user interactions
  • Performance dashboards monitor Web Vitals and surface issues on particular pages
  • Alerts can be set on Web Vital scores exceeding specific thresholds

Browser Support​

Due to browser limitations not all Web Vitals are available from user interactions on all browsers. See Browser Support in the web-vitals package documentation for a detailed breakdown.

Reporting Web Vitals for soft navigations also requires the browser to support the Soft Navigations API, as described in Single-page applications above.