feat(browser): Attribute web vitals to the navigation they were measured on

Adds `browser.navigation.type` to every emitted LCP, CLS and INP span, so
a vital can be read against the kind of navigation that produced it. A
soft navigation and a cold page load are not comparable measurements, and
without this there is no way to separate them after the fact.

web-vitals reports a wider set of navigation types than the attribute
defines, so only the states Navigation Timing cannot express keep their
own value. Every ordinary document navigation folds into `navigate`,
including a back/forward that missed the bfcache (per the spec) and a
`document.wasDiscarded` restore, which the spec does not name at all.

The `back-forward-cache` -> `bfcache` mapping is included but unreachable
today: `withoutBfcache` drops those metrics before they reach a span.
It's here so that enabling bfcache vitals later doesn't silently report
them as `navigate`.

Spec: getsentry/sentry-conventions#600

Author: logaretm

packages/browser-utils/src/instrumentation/performanceObserver.ts

@@ -58,6 +58,19 @@ export interface PerformanceLongAnimationFrameTiming extends PerformanceEntry {
 // entrypoint carries a `declare global` block that references DOM globals not present in every
 // TypeScript lib version (e.g. `NavigationType`), which leaks into and breaks consumers on older
 // TS. Keeping this local keeps web-vitals' global augmentations out of our published types.
+/**
+ * The navigation types web-vitals reports a metric for. Wider than the set the
+ * `browser.navigation.type` attribute uses - see `toBrowserNavigationType`.
+ */
+export type MetricNavigationType =
+  | 'navigate'
+  | 'reload'
+  | 'back-forward'
+  | 'back-forward-cache'
+  | 'prerender'
+  | 'restore'
+  | 'soft-navigation';
+
 interface Metric {
   /**
    * The name of the metric (in acronym form).
@@ -106,14 +119,7 @@ interface Metric {
    * support that API). For pages that are restored from the bfcache, this
    * value will be 'back-forward-cache'.
    */
-  navigationType:
-    | 'navigate'
-    | 'reload'
-    | 'back-forward'
-    | 'back-forward-cache'
-    | 'prerender'
-    | 'restore'
-    | 'soft-navigation';
+  navigationType: MetricNavigationType;
 
   /**
    * The id of the navigation the metric belongs to. For soft navigations this is the

packages/browser-utils/src/web-vitals/emitSpan.ts

@@ -11,9 +11,28 @@ import {
 import { startInactiveSpan } from '@sentry/core/browser';
 import { SENTRY_SEGMENT_NAME, SENTRY_TRANSACTION } from '@sentry/conventions/attributes';
 import { WINDOW } from '../types';
+import type { MetricNavigationType } from '../instrumentation/performanceObserver';
 import type { WebVitalReportEvent } from './reportEvents';
 import { SOFT_NAVIGATION_ID_ATTRIBUTE } from './softNavs';
 
+// TODO(conventions): replace with `BROWSER_NAVIGATION_TYPE` from `@sentry/conventions/attributes`
+// once https://github.com/getsentry/sentry-conventions/pull/600 is released.
+const BROWSER_NAVIGATION_TYPE_ATTRIBUTE = 'browser.navigation.type';
+
+// web-vitals reports a wider set of navigation types than the attribute defines. Only the states
+// Navigation Timing cannot express keep their own value; every ordinary document navigation folds
+// into `navigate`, including a back/forward that missed the bfcache and a discarded-tab restore.
+const BROWSER_NAVIGATION_TYPES: Partial<Record<MetricNavigationType, string>> = {
+  reload: 'reload',
+  prerender: 'prerender',
+  'back-forward-cache': 'bfcache',
+  'soft-navigation': 'soft-navigation',
+};
+
+function toBrowserNavigationType(navigationType: MetricNavigationType): string {
+  return BROWSER_NAVIGATION_TYPES[navigationType] ?? 'navigate';
+}
+
 // Locally-defined interfaces to avoid leaking bare global type references into the
 // generated .d.ts. The `declare global` augmentations in web-vitals/types.ts make these
 // available during this package's compilation but are NOT carried to consumers.
@@ -46,6 +65,8 @@ interface WebVitalSpanOptions {
   endTime?: number;
   /** Set when the vital was reported for a soft navigation rather than the initial page load. */
   softNavigationId?: number;
+  /** The navigation the vital was measured on, as reported by web-vitals. */
+  navigationType?: MetricNavigationType;
   /**
    * When `true`, the span is sent on its own as a v2 streamed span instead of being folded into a
    * transaction. Used for INP when span streaming is disabled (it reports late, so it can't ride
@@ -74,6 +95,7 @@ export function _emitWebVitalSpan(options: WebVitalSpanOptions): void {
     endTime,
     standalone,
     softNavigationId,
+    navigationType,
   } = options;
 
   // Taken off the segment span itself, so it can't diverge from it: a routing instrumentation may
@@ -109,6 +131,10 @@ export function _emitWebVitalSpan(options: WebVitalSpanOptions): void {
     attributes[SOFT_NAVIGATION_ID_ATTRIBUTE] = softNavigationId;
   }
 
+  if (navigationType) {
+    attributes[BROWSER_NAVIGATION_TYPE_ATTRIBUTE] = toBrowserNavigationType(navigationType);
+  }
+
   // A standalone span is sent as a plain v2 span without running the `processSpan` hooks (see
   // `captureStandaloneSpanWithStaticCallback`), so Replay can't attach the replay id itself. Set it
   // here, mirroring Replay's `processSpan`, so INP keeps its replay association like it did on v1.

packages/browser-utils/src/web-vitals/spans.ts

@@ -12,7 +12,7 @@ import { DEBUG_BUILD } from '../debug-build';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import type { InteractionType } from './inp';
 import { getCachedInteractionContext, INP_ENTRY_MAP, MAX_PLAUSIBLE_INP_DURATION } from './inp';
-import type { InstrumentationHandlerCallback } from '../instrumentation/performanceObserver';
+import type { InstrumentationHandlerCallback, MetricNavigationType } from '../instrumentation/performanceObserver';
 import {
   addClsInstrumentationHandler,
   addInpInstrumentationHandler,
@@ -92,15 +92,20 @@ export function trackLcpAsSpan(client: Client, reportSoftNavs = false): void {
   if (reportSoftNavs) {
     trackWebVitalPerNavigation(client, addLcpInstrumentationHandler, (metric, parentSpan, softNavigationId) => {
       const entry = metric.entries[metric.entries.length - 1] as LargestContentfulPaint | undefined;
-      _sendLcpSpan(metric.value, entry, parentSpan, undefined, softNavigationId);
+      _sendLcpSpan(metric.value, entry, parentSpan, undefined, softNavigationId, metric.navigationType);
     });
     return;
   }
 
   let lcpValue = 0;
   let lcpEntry: LargestContentfulPaint | undefined;
+  let lcpNavigationType: MetricNavigationType | undefined;
 
   const cleanupLcpHandler = addLcpInstrumentationHandler(({ metric }) => {
+    // The navigation type describes the page, not the entry, so it is worth keeping even for a
+    // report we otherwise discard.
+    lcpNavigationType = metric.navigationType;
+
     const entry = metric.entries[metric.entries.length - 1] as LargestContentfulPaint | undefined;
     if (!entry || !isValidLcpMetric(metric.value)) {
       return;
@@ -110,7 +115,7 @@ export function trackLcpAsSpan(client: Client, reportSoftNavs = false): void {
   }, true);
 
   listenForWebVitalReportEvents(client, (reportEvent, _, pageloadSpan) => {
-    _sendLcpSpan(lcpValue, lcpEntry, pageloadSpan, reportEvent);
+    _sendLcpSpan(lcpValue, lcpEntry, pageloadSpan, reportEvent, undefined, lcpNavigationType);
     cleanupLcpHandler();
   });
 }
@@ -124,6 +129,7 @@ export function _sendLcpSpan(
   pageloadSpan?: Span,
   reportEvent?: WebVitalReportEvent,
   softNavigationId?: number,
+  navigationType?: MetricNavigationType,
 ): void {
   if (!isValidLcpMetric(lcpValue)) {
     return;
@@ -157,6 +163,7 @@ export function _sendLcpSpan(
     startTime: timeOrigin,
     endTime,
     softNavigationId,
+    navigationType,
   });
 }
 
@@ -171,15 +178,20 @@ export function trackClsAsSpan(client: Client, reportSoftNavs = false): void {
   if (reportSoftNavs) {
     trackWebVitalPerNavigation(client, addClsInstrumentationHandler, (metric, parentSpan, softNavigationId) => {
       const entry = metric.entries[metric.entries.length - 1] as LayoutShift | undefined;
-      _sendClsSpan(metric.value, entry, parentSpan, undefined, softNavigationId);
+      _sendClsSpan(metric.value, entry, parentSpan, undefined, softNavigationId, metric.navigationType);
     });
     return;
   }
 
   let clsValue = 0;
   let clsEntry: LayoutShift | undefined;
+  let clsNavigationType: MetricNavigationType | undefined;
 
   const cleanupClsHandler = addClsInstrumentationHandler(({ metric }) => {
+    // A CLS of 0 is reported with no entries and still emits a span, so the navigation type has to
+    // be captured before the entry check rather than alongside the value.
+    clsNavigationType = metric.navigationType;
+
     const entry = metric.entries[metric.entries.length - 1] as LayoutShift | undefined;
     if (!entry) {
       return;
@@ -189,7 +201,7 @@ export function trackClsAsSpan(client: Client, reportSoftNavs = false): void {
   }, true);
 
   listenForWebVitalReportEvents(client, (reportEvent, _, pageloadSpan) => {
-    _sendClsSpan(clsValue, clsEntry, pageloadSpan, reportEvent);
+    _sendClsSpan(clsValue, clsEntry, pageloadSpan, reportEvent, undefined, clsNavigationType);
     cleanupClsHandler();
   });
 }
@@ -203,6 +215,7 @@ export function _sendClsSpan(
   pageloadSpan?: Span,
   reportEvent?: WebVitalReportEvent,
   softNavigationId?: number,
+  navigationType?: MetricNavigationType,
 ): void {
   DEBUG_BUILD && debug.log(`Sending CLS span (${clsValue})`);
 
@@ -228,6 +241,7 @@ export function _sendClsSpan(
     reportEvent,
     startTime,
     softNavigationId,
+    navigationType,
   });
 }
 
@@ -332,6 +346,7 @@ export function _sendInpSpan(
     },
     startTime,
     endTime: startTime + duration,
+    navigationType: metric?.navigationType,
     parentSpan: spanToUse,
     standalone,
     softNavigationId,

packages/browser-utils/test/web-vitals/spans.test.ts

@@ -331,6 +331,50 @@ describe('_emitWebVitalSpan', () => {
       });
     }).not.toThrow();
   });
+
+  it.each([
+    ['navigate', 'navigate'],
+    ['reload', 'reload'],
+    ['prerender', 'prerender'],
+    ['soft-navigation', 'soft-navigation'],
+    ['back-forward-cache', 'bfcache'],
+    // Ordinary document navigations the attribute has no separate value for.
+    ['back-forward', 'navigate'],
+    ['restore', 'navigate'],
+  ] as const)('reports navigationType %s as browser.navigation.type %s', (navigationType, expected) => {
+    _emitWebVitalSpan({
+      name: 'Test',
+      op: 'ui.webvital.lcp',
+      origin: 'auto.http.browser.lcp',
+      metricName: 'lcp',
+      value: 50,
+      startTime: 1.0,
+      navigationType,
+    });
+
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({ 'browser.navigation.type': expected }),
+      }),
+    );
+  });
+
+  it('omits browser.navigation.type when the navigation type is unknown', () => {
+    _emitWebVitalSpan({
+      name: 'Test',
+      op: 'ui.webvital.lcp',
+      origin: 'auto.http.browser.lcp',
+      metricName: 'lcp',
+      value: 50,
+      startTime: 1.0,
+    });
+
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({ 'browser.navigation.type': expect.anything() }),
+      }),
+    );
+  });
 });
 
 describe('_sendLcpSpan', () => {
@@ -765,9 +809,11 @@ describe('soft navigation web vitals', () => {
     expect(calls).toHaveLength(2);
     expect(calls[0]![0].attributes?.['browser.web_vital.lcp.value']).toBe(800);
     expect(calls[0]![0].attributes?.['browser.soft_navigation.id']).toBeUndefined();
+    expect(calls[0]![0].attributes?.['browser.navigation.type']).toBe('navigate');
     expect(calls[0]![0].parentSpan).toBe(pageloadSpan);
     expect(calls[1]![0].attributes?.['browser.web_vital.lcp.value']).toBe(300);
     expect(calls[1]![0].attributes?.['browser.soft_navigation.id']).toBe(2);
+    expect(calls[1]![0].attributes?.['browser.navigation.type']).toBe('soft-navigation');
     expect(calls[1]![0].parentSpan).toBe(navigationSpan);
   });