ref(browser): Add CLS/LCP report event attribute to standalone spans

Author: Lms24

packages/browser-utils/src/metrics/cls.ts

@@ -16,8 +16,10 @@ import {
 } from '@sentry/core';
 import { DEBUG_BUILD } from '../debug-build';
 import { addClsInstrumentationHandler } from './instrument';
+import type { WebVitalReportEvent } from './utils';
 import { msToSec, startStandaloneWebVitalSpan } from './utils';
 import { onHidden } from './web-vitals/lib/onHidden';
+import { runOnce } from './web-vitals/lib/runOnce';
 
 /**
  * Starts tracking the Cumulative Layout Shift on the current page and collects the value once
@@ -37,16 +39,13 @@ export function trackClsAsStandaloneSpan(): void {
     return;
   }
 
-  let sentSpan = false;
-  function _collectClsOnce() {
-    if (sentSpan) {
-      return;
-    }
-    sentSpan = true;
-    if (pageloadSpanId) {
-      sendStandaloneClsSpan(standaloneCLsValue, standaloneClsEntry, pageloadSpanId);
-    }
-    cleanupClsHandler();
+  function _collectClsOnce(reportEvent: WebVitalReportEvent) {
+    runOnce(() => {
+      if (pageloadSpanId) {
+        sendStandaloneClsSpan(standaloneCLsValue, standaloneClsEntry, pageloadSpanId, reportEvent);
+      }
+      cleanupClsHandler();
+    });
   }
 
   const cleanupClsHandler = addClsInstrumentationHandler(({ metric }) => {
@@ -59,7 +58,7 @@ export function trackClsAsStandaloneSpan(): void {
   }, true);
 
   onHidden(() => {
-    _collectClsOnce();
+    _collectClsOnce('pagehide');
   });
 
   // Since the call chain of this function is synchronous and evaluates before the SDK client is created,
@@ -73,9 +72,9 @@ export function trackClsAsStandaloneSpan(): void {
     }
 
     const unsubscribeStartNavigation = client.on('beforeStartNavigationSpan', (_, options) => {
-      // we only want to collect LCP if we actually navigate. Redirects should be ignored.
+      // we only want to collect CLS if we actually navigate. Redirects should be ignored.
       if (!options?.isRedirect) {
-        _collectClsOnce();
+        _collectClsOnce('navigation');
         unsubscribeStartNavigation?.();
       }
     });
@@ -91,7 +90,12 @@ export function trackClsAsStandaloneSpan(): void {
   }, 0);
 }
 
-function sendStandaloneClsSpan(clsValue: number, entry: LayoutShift | undefined, pageloadSpanId: string) {
+function sendStandaloneClsSpan(
+  clsValue: number,
+  entry: LayoutShift | undefined,
+  pageloadSpanId: string,
+  reportEvent: WebVitalReportEvent,
+) {
   DEBUG_BUILD && logger.log(`Sending CLS span (${clsValue})`);
 
   const startTime = msToSec((browserPerformanceTimeOrigin() || 0) + (entry?.startTime || 0));
@@ -105,6 +109,8 @@ function sendStandaloneClsSpan(clsValue: number, entry: LayoutShift | undefined,
     [SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: entry?.duration || 0,
     // attach the pageload span id to the CLS span so that we can link them in the UI
     'sentry.pageload.span_id': pageloadSpanId,
+    // describes what triggered the web vital to be reported
+    'sentry.report_event': reportEvent,
   };
 
   // Add CLS sources as span attributes to help with debugging layout shifts

packages/browser-utils/src/metrics/lcp.ts

@@ -16,8 +16,10 @@ import {
 } from '@sentry/core';
 import { DEBUG_BUILD } from '../debug-build';
 import { addLcpInstrumentationHandler } from './instrument';
+import type { WebVitalReportEvent } from './utils';
 import { msToSec, startStandaloneWebVitalSpan } from './utils';
 import { onHidden } from './web-vitals/lib/onHidden';
+import { runOnce } from './web-vitals/lib/runOnce';
 
 /**
  * Starts tracking the Largest Contentful Paint on the current page and collects the value once
@@ -37,16 +39,13 @@ export function trackLcpAsStandaloneSpan(): void {
     return;
   }
 
-  let sentSpan = false;
-  function _collectLcpOnce() {
-    if (sentSpan) {
-      return;
-    }
-    sentSpan = true;
-    if (pageloadSpanId) {
-      _sendStandaloneLcpSpan(standaloneLcpValue, standaloneLcpEntry, pageloadSpanId);
-    }
-    cleanupLcpHandler();
+  function _collectLcpOnce(reportEvent: WebVitalReportEvent) {
+    runOnce(() => {
+      if (pageloadSpanId) {
+        _sendStandaloneLcpSpan(standaloneLcpValue, standaloneLcpEntry, pageloadSpanId, reportEvent);
+      }
+      cleanupLcpHandler();
+    });
   }
 
   const cleanupLcpHandler = addLcpInstrumentationHandler(({ metric }) => {
@@ -59,7 +58,7 @@ export function trackLcpAsStandaloneSpan(): void {
   }, true);
 
   onHidden(() => {
-    _collectLcpOnce();
+    _collectLcpOnce('pagehide');
   });
 
   // Since the call chain of this function is synchronous and evaluates before the SDK client is created,
@@ -75,7 +74,7 @@ export function trackLcpAsStandaloneSpan(): void {
     const unsubscribeStartNavigation = client.on('beforeStartNavigationSpan', (_, options) => {
       // we only want to collect LCP if we actually navigate. Redirects should be ignored.
       if (!options?.isRedirect) {
-        _collectLcpOnce();
+        _collectLcpOnce('navigation');
         unsubscribeStartNavigation?.();
       }
     });
@@ -98,6 +97,7 @@ export function _sendStandaloneLcpSpan(
   lcpValue: number,
   entry: LargestContentfulPaint | undefined,
   pageloadSpanId: string,
+  reportEvent: WebVitalReportEvent,
 ) {
   DEBUG_BUILD && logger.log(`Sending LCP span (${lcpValue})`);
 
@@ -112,6 +112,8 @@ export function _sendStandaloneLcpSpan(
     [SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: 0, // LCP is a point-in-time metric
     // attach the pageload span id to the LCP span so that we can link them in the UI
     'sentry.pageload.span_id': pageloadSpanId,
+    // describes what triggered the web vital to be reported
+    'sentry.report_event': reportEvent,
   };
 
   if (entry) {

packages/browser-utils/src/metrics/utils.ts

@@ -2,6 +2,8 @@ import type { Integration, SentrySpan, Span, SpanAttributes, SpanTimeInput, Star
 import { getClient, getCurrentScope, spanToJSON, startInactiveSpan, withActiveSpan } from '@sentry/core';
 import { WINDOW } from '../types';
 
+export type WebVitalReportEvent = 'pagehide' | 'navigation';
+
 /**
  * Checks if a given value is a valid measurement value.
  */
@@ -168,3 +170,6 @@ export function extractNetworkProtocol(nextHopProtocol: string): { name: string;
   }
   return { name, version };
 }
+
+type ReportEvent = 'pagehide' | 'navigation';
+function createReportOnceHandler();