ref(browser): let web vitals own pageload flush

Co-Authored-By: OpenAI GPT-5 <codex@openai.com>

Author: logaretm

packages/browser/src/integrations/webVitals.ts

@@ -1,4 +1,4 @@
-import type { Client, IntegrationFn, Span } from '@sentry/core/browser';
+import type { IntegrationFn, Span } from '@sentry/core/browser';
 import { defineIntegration, hasSpanStreamingEnabled } from '@sentry/core/browser';
 import {
   addWebVitalsToSpan,
@@ -29,16 +29,6 @@ export interface WebVitalsOptions {
   }>;
 }
 
-const collectWebVitalsCallbacks = new WeakMap<Client, (span: Span) => void>();
-
-/**
- * Finalizes the collected web vitals and writes them onto the given (pageload) span.
- * Called by `browserTracingIntegration` when the pageload/navigation span ends.
- */
-export function collectWebVitalsForClient(client: Client, span: Span): void {
-  collectWebVitalsCallbacks.get(client)?.(span);
-}
-
 /**
  * Captures Core Web Vitals (LCP, CLS, INP) and related pageload vitals.
  *
@@ -66,14 +56,16 @@ export const webVitalsIntegration = defineIntegration((options: WebVitalsOptions
         client,
       });
 
-      collectWebVitalsCallbacks.set(client, span => {
-        finalizeWebVitals();
-        addWebVitalsToSpan(span, {
-          // CLS/LCP are recorded as pageload span measurements only when they're neither
-          // tracked as standalone spans nor handled by span streaming (and not ignored).
-          recordClsOnPageloadSpan: recordClsStandaloneSpans === false,
-          recordLcpOnPageloadSpan: recordLcpStandaloneSpans === false,
-          spanStreamingEnabled,
+      client.on('afterStartPageLoadSpan', span => {
+        wrapPageloadSpanEnd(span, () => {
+          finalizeWebVitals();
+          addWebVitalsToSpan(span, {
+            // CLS/LCP are recorded as pageload span measurements only when they're neither
+            // tracked as standalone spans nor handled by span streaming (and not ignored).
+            recordClsOnPageloadSpan: recordClsStandaloneSpans === false,
+            recordLcpOnPageloadSpan: recordLcpStandaloneSpans === false,
+            spanStreamingEnabled,
+          });
         });
       });
 
@@ -98,3 +90,17 @@ export const webVitalsIntegration = defineIntegration((options: WebVitalsOptions
     },
   };
 }) satisfies IntegrationFn;
+
+function wrapPageloadSpanEnd(span: Span, beforeEnd: () => void): void {
+  let hasEnded = false;
+  const originalEnd = span.end.bind(span);
+
+  span.end = (...args: Parameters<Span['end']>): void => {
+    if (!hasEnded) {
+      hasEnded = true;
+      beforeEnd();
+    }
+
+    originalEnd(...args);
+  };
+}

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -47,11 +47,7 @@ import {
 import { DEBUG_BUILD } from '../debug-build';
 import { getHttpRequestData, WINDOW } from '../helpers';
 import { fetchStreamPerformanceIntegration } from '../integrations/fetchStreamPerformance';
-import {
-  collectWebVitalsForClient,
-  WEB_VITALS_INTEGRATION_NAME,
-  webVitalsIntegration,
-} from '../integrations/webVitals';
+import { WEB_VITALS_INTEGRATION_NAME, webVitalsIntegration } from '../integrations/webVitals';
 import { registerBackgroundTabDetection } from './backgroundtab';
 import { linkTraces } from './linkedTraces';
 import { defaultRequestInstrumentationOptions, instrumentOutgoingRequests } from './request';
@@ -456,9 +452,6 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
       // should wait for finish signal if it's a pageload transaction
       disableAutoFinish: isPageloadSpan,
       beforeSpanEnd: span => {
-        // The webVitalsIntegration owns all web vital logic; it finalizes the collected
-        // web vitals and writes them onto the pageload span.
-        collectWebVitalsForClient(client, span);
         addPerformanceEntries(span, {
           ignoreResourceSpans,
           ignorePerformanceApiSpans,

packages/browser/test/integrations/webVitals.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { collectWebVitalsForClient, webVitalsIntegration } from '../../src/integrations/webVitals';
+import { webVitalsIntegration } from '../../src/integrations/webVitals';
 
 const mockAddWebVitalsToSpan = vi.hoisted(() => vi.fn());
 const mockRegisterInpInteractionListener = vi.hoisted(() => vi.fn());
@@ -19,6 +19,29 @@ vi.mock('@sentry-internal/browser-utils', () => ({
   trackLcpAsSpan: mockTrackLcpAsSpan,
 }));
 
+function getMockClient(options: Record<string, unknown> = {}) {
+  const listeners = new Map<string, Array<(...args: unknown[]) => void>>();
+
+  return {
+    getOptions: () => options,
+    on: vi.fn((hook: string, callback: (...args: unknown[]) => void) => {
+      const callbacks = listeners.get(hook) ?? [];
+      callbacks.push(callback);
+      listeners.set(hook, callbacks);
+
+      return () => {
+        const updatedCallbacks = listeners.get(hook)?.filter(cb => cb !== callback) ?? [];
+        listeners.set(hook, updatedCallbacks);
+      };
+    }),
+    emit: (hook: string, ...args: unknown[]) => {
+      listeners.get(hook)?.forEach(callback => {
+        callback(...args);
+      });
+    },
+  };
+}
+
 describe('webVitalsIntegration', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -30,7 +53,7 @@ describe('webVitalsIntegration', () => {
   });
 
   it('tracks web vitals with the existing non-streaming behavior by default', () => {
-    const client = { getOptions: () => ({}) };
+    const client = getMockClient();
     const integration = webVitalsIntegration();
 
     integration.setup?.(client as never);
@@ -49,7 +72,7 @@ describe('webVitalsIntegration', () => {
   });
 
   it('keeps standalone LCP and CLS experiments working', () => {
-    const client = { getOptions: () => ({}) };
+    const client = getMockClient();
     const integration = webVitalsIntegration({
       _experiments: {
         enableStandaloneClsSpans: true,
@@ -67,7 +90,7 @@ describe('webVitalsIntegration', () => {
   });
 
   it('tracks LCP, CLS and INP as streamed spans when span streaming is enabled', () => {
-    const client = { getOptions: () => ({ traceLifecycle: 'stream' }) };
+    const client = getMockClient({ traceLifecycle: 'stream' });
     const integration = webVitalsIntegration();
 
     integration.setup?.(client as never);
@@ -86,7 +109,7 @@ describe('webVitalsIntegration', () => {
   });
 
   it('supports ignoring selected web vitals for browserTracingIntegration compatibility', () => {
-    const client = { getOptions: () => ({}) };
+    const client = getMockClient();
     const integration = webVitalsIntegration({ ignore: ['cls', 'inp', 'lcp'] });
 
     integration.setup?.(client as never);
@@ -102,14 +125,15 @@ describe('webVitalsIntegration', () => {
     expect(mockRegisterInpInteractionListener).not.toHaveBeenCalled();
   });
 
-  it('finalizes web vitals and writes them onto the span when collected for the client', () => {
+  it('finalizes web vitals and writes them onto the pageload span before it ends', () => {
     const finalizeWebVitals = vi.fn();
-    const client = { getOptions: () => ({}) };
-    const span = {};
+    const client = getMockClient();
+    const span = { end: vi.fn() };
     mockStartTrackingWebVitals.mockReturnValue(finalizeWebVitals);
 
     webVitalsIntegration().setup?.(client as never);
-    collectWebVitalsForClient(client as never, span as never);
+    client.emit('afterStartPageLoadSpan', span);
+    span.end();
 
     expect(finalizeWebVitals).toHaveBeenCalledTimes(1);
     expect(mockAddWebVitalsToSpan).toHaveBeenCalledWith(span, {
@@ -120,11 +144,12 @@ describe('webVitalsIntegration', () => {
   });
 
   it('does not record CLS/LCP on the pageload span when span streaming is enabled', () => {
-    const client = { getOptions: () => ({ traceLifecycle: 'stream' }) };
-    const span = {};
+    const client = getMockClient({ traceLifecycle: 'stream' });
+    const span = { end: vi.fn() };
 
     webVitalsIntegration().setup?.(client as never);
-    collectWebVitalsForClient(client as never, span as never);
+    client.emit('afterStartPageLoadSpan', span);
+    span.end();
 
     expect(mockAddWebVitalsToSpan).toHaveBeenCalledWith(span, {
       recordClsOnPageloadSpan: false,
@@ -134,14 +159,15 @@ describe('webVitalsIntegration', () => {
   });
 
   it('does not record CLS/LCP on the pageload span when standalone spans are enabled', () => {
-    const client = { getOptions: () => ({}) };
-    const span = {};
+    const client = getMockClient();
+    const span = { end: vi.fn() };
     const integration = webVitalsIntegration({
       _experiments: { enableStandaloneClsSpans: true, enableStandaloneLcpSpans: true },
     });
 
     integration.setup?.(client as never);
-    collectWebVitalsForClient(client as never, span as never);
+    client.emit('afterStartPageLoadSpan', span);
+    span.end();
 
     expect(mockAddWebVitalsToSpan).toHaveBeenCalledWith(span, {
       recordClsOnPageloadSpan: false,