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

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-inp-late/test.ts

@@ -77,6 +77,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         'sentry.transaction': { value: 'test-url', type: 'string' },
         'sentry.segment.name': { value: 'test-url', type: 'string' },
         'user_agent.original': { value: expect.stringContaining('Chrome'), type: 'string' },

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-inp-navigate/test.ts

@@ -77,6 +77,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         'sentry.transaction': { value: 'test-url', type: 'string' },
         'sentry.segment.name': { value: 'test-url', type: 'string' },
         'user_agent.original': { value: expect.stringContaining('Chrome'), type: 'string' },
@@ -162,6 +163,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         'sentry.transaction': { value: 'test-url', type: 'string' },
         'sentry.segment.name': { value: 'test-url', type: 'string' },
         'user_agent.original': { value: expect.stringContaining('Chrome'), type: 'string' },

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-inp-parametrized-late/test.ts

@@ -78,6 +78,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         // the parametrized route name flows onto the INP span
         'sentry.transaction': { value: 'test-route', type: 'string' },
         'sentry.segment.name': { value: 'test-route', type: 'string' },

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-inp-parametrized/test.ts

@@ -78,6 +78,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         // the parametrized route name flows onto the INP span
         'sentry.transaction': { value: 'test-route', type: 'string' },
         'sentry.segment.name': { value: 'test-route', type: 'string' },

dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-inp/test.ts

@@ -81,6 +81,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         'sentry.transaction': { value: 'test-url', type: 'string' },
         'sentry.segment.name': { value: 'test-url', type: 'string' },
         'user_agent.original': { value: expect.stringContaining('Chrome'), type: 'string' },
@@ -147,6 +148,7 @@ sentryTest(
         'sentry.op': { value: 'ui.interaction.click', type: 'string' },
         'sentry.exclusive_time': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
         'browser.web_vital.inp.value': { value: inpValue, type: expect.stringMatching(/^(integer)|(double)$/) },
+        'browser.navigation.type': { value: 'navigate', type: 'string' },
         'sentry.transaction': { value: 'test-url', type: 'string' },
         'sentry.segment.name': { value: 'test-url', type: 'string' },
         'user_agent.original': { value: expect.stringContaining('Chrome'), type: 'string' },

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
@@ -157,6 +163,8 @@ let _previousTtfb: Metric | undefined;
 let _previousInp: Metric | undefined;
 let _previousFcp: Metric | undefined;
 
+const stopListeners: Partial<Record<InstrumentHandlerType, StopListening>> = {};
+
 let _reportSoftNavs = false;
 
 /**
@@ -373,18 +381,24 @@ function addMetricObserver(
 ): CleanupHandlerCallback {
   addHandler(type, callback);
 
-  let stopListening: StopListening | undefined;
-
   if (!instrumented[type]) {
-    stopListening = instrumentFn();
     instrumented[type] = true;
+    // Deferred by a microtask rather than started here, because web-vitals reads its options once,
+    // when the observer is created. Registering a handler would otherwise pin those options for
+    // every other consumer of this observer, so whichever integration happened to run first would
+    // decide whether soft navigations and bfcache restores are reported. Client setup is
+    // synchronous, so every `enable*Reporting()` call has landed by the time this runs, and the
+    // observers are buffered so no entries are missed in the meantime.
+    void Promise.resolve().then(() => {
+      stopListeners[type] = instrumentFn();
+    });
   }
 
   if (previousValue) {
     callback({ metric: previousValue });
   }
 
-  return getCleanupCallback(type, callback, stopOnCallback ? stopListening : undefined);
+  return getCleanupCallback(type, callback, stopOnCallback);
 }
 
 function instrumentPerformanceObserver(type: InstrumentHandlerTypePerformanceObserver): void {
@@ -421,11 +435,13 @@ function addHandler(type: InstrumentHandlerType, handler: InstrumentHandlerCallb
 function getCleanupCallback(
   type: InstrumentHandlerType,
   callback: InstrumentHandlerCallback,
-  stopListening: StopListening,
+  stopOnCleanup = false,
 ): CleanupHandlerCallback {
   return () => {
-    if (stopListening) {
-      stopListening();
+    // Looked up rather than captured: the observer is started in a microtask, so its stop function
+    // does not exist yet when this callback is built.
+    if (stopOnCleanup) {
+      stopListeners[type]?.();
     }
 
     const typeHandlers = handlers[type];

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

@@ -9,11 +9,35 @@ import {
   spanToJSON,
 } from '@sentry/core';
 import { startInactiveSpan } from '@sentry/core/browser';
-import { SENTRY_SEGMENT_NAME, SENTRY_TRANSACTION } from '@sentry/conventions/attributes';
+import {
+  SENTRY_REPLAY_ID,
+  SENTRY_SEGMENT_NAME,
+  SENTRY_TRANSACTION,
+  USER_AGENT_ORIGINAL,
+} 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 +70,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 +100,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
@@ -92,7 +119,7 @@ export function _emitWebVitalSpan(options: WebVitalSpanOptions): void {
     [SENTRY_TRANSACTION]: segmentName,
     [SENTRY_SEGMENT_NAME]: segmentName,
     // Web vital score calculation relies on the user agent
-    'user_agent.original': WINDOW.navigator?.userAgent,
+    [USER_AGENT_ORIGINAL]: WINDOW.navigator?.userAgent,
     ...passedAttributes,
   };
 
@@ -109,6 +136,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.
@@ -147,7 +178,9 @@ function getReplayAttributes(): SpanAttributes {
   }
 
   return {
-    'sentry.replay_id': replayId,
+    [SENTRY_REPLAY_ID]: replayId,
+    // Not the `SENTRY_REPLAY_IS_BUFFERING` convention: that one has no `sentry._internal.` prefix, and
+    // the rest of the SDK sets the prefixed key (see `logs/internal.ts`, `metrics/internal.ts`).
     'sentry._internal.replay_is_buffering': replay!.getRecordingMode() === 'buffer' ? true : undefined,
   };
 }

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,28 @@ 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,
+        metric.navigationStartTime,
+      );
     });
     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 +123,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 +137,8 @@ export function _sendLcpSpan(
   pageloadSpan?: Span,
   reportEvent?: WebVitalReportEvent,
   softNavigationId?: number,
+  navigationType?: MetricNavigationType,
+  navigationStartTime?: number,
 ): void {
   if (!isValidLcpMetric(lcpValue)) {
     return;
@@ -132,8 +147,13 @@ export function _sendLcpSpan(
   DEBUG_BUILD && debug.log(`Sending LCP span (${lcpValue})`);
 
   const performanceTimeOrigin = browserPerformanceTimeOrigin() || 0;
-  const timeOrigin = msToSec(performanceTimeOrigin);
-  const endTime = msToSec(performanceTimeOrigin + (entry?.startTime || 0));
+  // A soft navigation's LCP is measured from the triggering interaction, not the document time
+  // origin. Starting the span there too keeps it inside the navigation span it is parented to and
+  // keeps its duration equal to the value it reports.
+  const startTime = msToSec(performanceTimeOrigin + (navigationStartTime || 0));
+  // Without an entry there is no render time to end at, so the span lasts the value it reports,
+  // like an entry-less INP does. Ending at the time origin instead would invert the span.
+  const endTime = entry ? msToSec(performanceTimeOrigin + entry.startTime) : startTime + msToSec(lcpValue);
   const name = entry ? htmlTreeAsString(entry.element) : 'Largest contentful paint';
 
   const attributes: SpanAttributes = {};
@@ -154,9 +174,10 @@ export function _sendLcpSpan(
     attributes,
     parentSpan: pageloadSpan,
     reportEvent,
-    startTime: timeOrigin,
+    startTime,
     endTime,
     softNavigationId,
+    navigationType,
   });
 }
 
@@ -171,15 +192,28 @@ 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,
+        metric.navigationStartTime,
+      );
     });
     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 +223,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,10 +237,17 @@ export function _sendClsSpan(
   pageloadSpan?: Span,
   reportEvent?: WebVitalReportEvent,
   softNavigationId?: number,
+  navigationType?: MetricNavigationType,
+  navigationStartTime?: number,
 ): void {
   DEBUG_BUILD && debug.log(`Sending CLS span (${clsValue})`);
 
-  const startTime = entry ? msToSec((browserPerformanceTimeOrigin() || 0) + entry.startTime) : timestampInSeconds();
+  const performanceTimeOrigin = browserPerformanceTimeOrigin();
+  // A CLS of 0 has no shift to place the span at. It is reported when the navigation it was
+  // measured on is already over - the next soft navigation, or pagehide - so the current time would
+  // land it outside that navigation, on the route that follows it.
+  const offset = entry?.startTime ?? navigationStartTime ?? 0;
+  const startTime = performanceTimeOrigin ? msToSec(performanceTimeOrigin + offset) : timestampInSeconds();
   const name = entry ? htmlTreeAsString(entry.sources[0]?.node) : 'Layout shift';
 
   const attributes: SpanAttributes = {};
@@ -228,6 +269,7 @@ export function _sendClsSpan(
     reportEvent,
     startTime,
     softNavigationId,
+    navigationType,
   });
 }
 
@@ -332,6 +374,7 @@ export function _sendInpSpan(
     },
     startTime,
     endTime: startTime + duration,
+    navigationType: metric?.navigationType,
     parentSpan: spanToUse,
     standalone,
     softNavigationId,