feat(browser): Add afterStartPageloadSpan hook to improve spanId assignment on web vital spans (#16893)

Our standalone web vital spans need to include the span id of the
`pageload` span s.t. we can correctly assign the web vital value to the
respective pageload span in the Sentry backend.

In the previous implementation, we'd simply wait for a tick after
tracking the web vitals, get the active root span and take its spanId if
it was a pageload span. However, this relies on the assumption that the
pageload span is indeed started immediately. By default this happens but
users can always deactivate default behaviour and call
`startBrowserTracingPageloadSpan` whenever they want (for example, in a
custom `browserTracingIntegration`).
Furthermore, this "wait for a tick" logic always bugged me and was only
done because `getClient()` would not yet return the already initialized
client.

This change now makes the pageload spanId retrieval more robust by 
- adding and listening to a new SDK lifecycle hook:
`afterStartPageloadSpan`. This callback fires as soon as the pageload
span is actually started and available.
- passing the `client` from the `browserTracingIntegration`'s `setup`
hook into the web vital listening function so that we can remove the
`setTimeout(_, 0)` logic.

Author: Lms24

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

@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */
-import type { Measurements, Span, SpanAttributes, SpanAttributeValue, StartSpanOptions } from '@sentry/core';
+import type { Client, Measurements, Span, SpanAttributes, SpanAttributeValue, StartSpanOptions } from '@sentry/core';
 import {
   browserPerformanceTimeOrigin,
   getActiveSpan,
@@ -83,6 +83,7 @@ let _clsEntry: LayoutShift | undefined;
 interface StartTrackingWebVitalsOptions {
   recordClsStandaloneSpans: boolean;
   recordLcpStandaloneSpans: boolean;
+  client: Client;
 }
 
 /**
@@ -94,6 +95,7 @@ interface StartTrackingWebVitalsOptions {
 export function startTrackingWebVitals({
   recordClsStandaloneSpans,
   recordLcpStandaloneSpans,
+  client,
 }: StartTrackingWebVitalsOptions): () => void {
   const performance = getBrowserPerformanceAPI();
   if (performance && browserPerformanceTimeOrigin()) {
@@ -102,9 +104,9 @@ export function startTrackingWebVitals({
       WINDOW.performance.mark('sentry-tracing-init');
     }
     const fidCleanupCallback = _trackFID();
-    const lcpCleanupCallback = recordLcpStandaloneSpans ? trackLcpAsStandaloneSpan() : _trackLCP();
+    const lcpCleanupCallback = recordLcpStandaloneSpans ? trackLcpAsStandaloneSpan(client) : _trackLCP();
     const ttfbCleanupCallback = _trackTtfb();
-    const clsCleanupCallback = recordClsStandaloneSpans ? trackClsAsStandaloneSpan() : _trackCLS();
+    const clsCleanupCallback = recordClsStandaloneSpans ? trackClsAsStandaloneSpan(client) : _trackCLS();
 
     return (): void => {
       fidCleanupCallback();

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

@@ -1,4 +1,4 @@
-import type { SpanAttributes } from '@sentry/core';
+import type { Client, SpanAttributes } from '@sentry/core';
 import {
   browserPerformanceTimeOrigin,
   getCurrentScope,
@@ -24,7 +24,7 @@ import { listenForWebVitalReportEvents, msToSec, startStandaloneWebVitalSpan, su
  * Once either of these events triggers, the CLS value is sent as a standalone span and we stop
  * measuring CLS.
  */
-export function trackClsAsStandaloneSpan(): void {
+export function trackClsAsStandaloneSpan(client: Client): void {
   let standaloneCLsValue = 0;
   let standaloneClsEntry: LayoutShift | undefined;
 
@@ -41,7 +41,7 @@ export function trackClsAsStandaloneSpan(): void {
     standaloneClsEntry = entry;
   }, true);
 
-  listenForWebVitalReportEvents((reportEvent, pageloadSpanId) => {
+  listenForWebVitalReportEvents(client, (reportEvent, pageloadSpanId) => {
     sendStandaloneClsSpan(standaloneCLsValue, standaloneClsEntry, pageloadSpanId, reportEvent);
     cleanupClsHandler();
   });

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

@@ -1,4 +1,4 @@
-import type { SpanAttributes } from '@sentry/core';
+import type { Client, SpanAttributes } from '@sentry/core';
 import {
   browserPerformanceTimeOrigin,
   getCurrentScope,
@@ -24,7 +24,7 @@ import { listenForWebVitalReportEvents, msToSec, startStandaloneWebVitalSpan, su
  * Once either of these events triggers, the LCP value is sent as a standalone span and we stop
  * measuring LCP for subsequent routes.
  */
-export function trackLcpAsStandaloneSpan(): void {
+export function trackLcpAsStandaloneSpan(client: Client): void {
   let standaloneLcpValue = 0;
   let standaloneLcpEntry: LargestContentfulPaint | undefined;
 
@@ -41,7 +41,7 @@ export function trackLcpAsStandaloneSpan(): void {
     standaloneLcpEntry = entry;
   }, true);
 
-  listenForWebVitalReportEvents((reportEvent, pageloadSpanId) => {
+  listenForWebVitalReportEvents(client, (reportEvent, pageloadSpanId) => {
     _sendStandaloneLcpSpan(standaloneLcpValue, standaloneLcpEntry, pageloadSpanId, reportEvent);
     cleanupLcpHandler();
   });

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

@@ -1,13 +1,13 @@
-import type { Integration, SentrySpan, Span, SpanAttributes, SpanTimeInput, StartSpanOptions } from '@sentry/core';
-import {
-  getActiveSpan,
-  getClient,
-  getCurrentScope,
-  getRootSpan,
-  spanToJSON,
-  startInactiveSpan,
-  withActiveSpan,
+import type {
+  Client,
+  Integration,
+  SentrySpan,
+  Span,
+  SpanAttributes,
+  SpanTimeInput,
+  StartSpanOptions,
 } from '@sentry/core';
+import { getClient, getCurrentScope, spanToJSON, startInactiveSpan, withActiveSpan } from '@sentry/core';
 import { WINDOW } from '../types';
 import { onHidden } from './web-vitals/lib/onHidden';
 
@@ -205,6 +205,7 @@ export function supportsWebVital(entryType: 'layout-shift' | 'largest-contentful
  * - pageloadSpanId: the span id of the pageload span. This is used to link the web vital span to the pageload span.
  */
 export function listenForWebVitalReportEvents(
+  client: Client,
   collectorCallback: (event: WebVitalReportEvent, pageloadSpanId: string) => void,
 ) {
   let pageloadSpanId: string | undefined;
@@ -218,32 +219,20 @@ export function listenForWebVitalReportEvents(
   }
 
   onHidden(() => {
-    if (!collected) {
-      _runCollectorCallbackOnce('pagehide');
-    }
+    _runCollectorCallbackOnce('pagehide');
   });
 
-  setTimeout(() => {
-    const client = getClient();
-    if (!client) {
-      return;
+  const unsubscribeStartNavigation = client.on('beforeStartNavigationSpan', (_, options) => {
+    // we only want to collect LCP if we actually navigate. Redirects should be ignored.
+    if (!options?.isRedirect) {
+      _runCollectorCallbackOnce('navigation');
+      unsubscribeStartNavigation?.();
+      unsubscribeAfterStartPageLoadSpan?.();
     }
+  });
 
-    const unsubscribeStartNavigation = client.on('beforeStartNavigationSpan', (_, options) => {
-      // we only want to collect LCP if we actually navigate. Redirects should be ignored.
-      if (!options?.isRedirect) {
-        _runCollectorCallbackOnce('navigation');
-        unsubscribeStartNavigation?.();
-      }
-    });
-
-    const activeSpan = getActiveSpan();
-    if (activeSpan) {
-      const rootSpan = getRootSpan(activeSpan);
-      const spanJSON = spanToJSON(rootSpan);
-      if (spanJSON.op === 'pageload') {
-        pageloadSpanId = rootSpan.spanContext().spanId;
-      }
-    }
-  }, 0);
+  const unsubscribeAfterStartPageLoadSpan = client.on('afterStartPageLoadSpan', span => {
+    pageloadSpanId = span.spanContext().spanId;
+    unsubscribeAfterStartPageLoadSpan?.();
+  });
 }

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -440,6 +440,7 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
       _collectWebVitals = startTrackingWebVitals({
         recordClsStandaloneSpans: enableStandaloneClsSpans || false,
         recordLcpStandaloneSpans: enableStandaloneLcpSpans || false,
+        client,
       });
 
       if (enableInp) {
@@ -644,7 +645,13 @@ export function startBrowserTracingPageLoadSpan(
   client.emit('startPageLoadSpan', spanOptions, traceOptions);
   getCurrentScope().setTransactionName(spanOptions.name);
 
-  return getActiveIdleSpan(client);
+  const pageloadSpan = getActiveIdleSpan(client);
+
+  if (pageloadSpan) {
+    client.emit('afterStartPageLoadSpan', pageloadSpan);
+  }
+
+  return pageloadSpan;
 }
 
 /**

packages/core/src/client.ts

@@ -603,6 +603,12 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     ) => void,
   ): () => void;
 
+  /**
+   * A hook for the browser tracing integrations to trigger after the pageload span was started.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'afterStartPageLoadSpan', callback: (span: Span) => void): () => void;
+
   /**
    * A hook for triggering right before a navigation span is started.
    * @returns {() => void} A function that, when executed, removes the registered callback.
@@ -791,6 +797,11 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     traceOptions?: { sentryTrace?: string | undefined; baggage?: string | undefined },
   ): void;
 
+  /**
+   * Emit a hook event for browser tracing integrations to trigger aafter the pageload span was started.
+   */
+  public emit(hook: 'afterStartPageLoadSpan', span: Span): void;
+
   /**
    * Emit a hook event for triggering right before a navigation span is started.
    */