feat(browser): Add beforeStartNavigationSpan lifecycle hook (#16863)

This change adds a new `beforeStartNavigationSpan` lifecycle hook that gets
triggered directly before the `startNavigationSpan` hook by the
`startBrowserTracingNavigationSpan` helper function. The reason we need
this is because we have logic for standalone CLS and LCP spans that
needs to run _before_ we start preparing any work that's executed at the
`startNavigationSpan` hook:

- `beforeStartNavigationSpan`: send standalone span with the pageload
trace id (i.e. the currently still active trace id on the propagation
context
- `startNavigationSpan`: first recycles the propagation context, then
starts the new span

This change does not yet include switching over LCP and CLS collection to the new hook (coming in a follow-up commit)

Author: Lms24

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

@@ -72,9 +72,12 @@ export function trackClsAsStandaloneSpan(): void {
       return;
     }
 
-    const unsubscribeStartNavigation = client.on('startNavigationSpan', () => {
-      _collectClsOnce();
-      unsubscribeStartNavigation?.();
+    const unsubscribeStartNavigation = client.on('startNavigationSpan', (_, options) => {
+      // we only want to collect LCP if we actually navigate. Redirects should be ignored.
+      if (!options?.isRedirect) {
+        _collectClsOnce();
+        unsubscribeStartNavigation?.();
+      }
     });
 
     const activeSpan = getActiveSpan();

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

@@ -72,9 +72,12 @@ export function trackLcpAsStandaloneSpan(): void {
       return;
     }
 
-    const unsubscribeStartNavigation = client.on('startNavigationSpan', () => {
-      _collectLcpOnce();
-      unsubscribeStartNavigation?.();
+    const unsubscribeStartNavigation = client.on('startNavigationSpan', (_, options) => {
+      // we only want to collect LCP if we actually navigate. Redirects should be ignored.
+      if (!options?.isRedirect) {
+        _collectLcpOnce();
+        unsubscribeStartNavigation?.();
+      }
     });
 
     const activeSpan = getActiveSpan();

packages/browser/src/tracing/browserTracingIntegration.ts

@@ -657,7 +657,7 @@ export function startBrowserTracingNavigationSpan(
   options?: { url?: string; isRedirect?: boolean },
 ): Span | undefined {
   const { url, isRedirect } = options || {};
-
+  client.emit('beforeStartNavigationSpan', spanOptions, { isRedirect });
   client.emit('startNavigationSpan', spanOptions, { isRedirect });
 
   const scope = getCurrentScope();

packages/browser/test/tracing/browserTracingIntegration.test.ts

@@ -788,6 +788,27 @@ describe('browserTracingIntegration', () => {
         },
       });
     });
+
+    it('triggers beforeStartNavigationSpan hook listeners', () => {
+      const client = new BrowserClient(
+        getDefaultBrowserClientOptions({
+          tracesSampleRate: 1,
+          integrations: [browserTracingIntegration()],
+        }),
+      );
+      setCurrentClient(client);
+
+      const mockBeforeStartNavigationSpanCallback = vi.fn((options: StartSpanOptions) => options);
+
+      client.on('beforeStartNavigationSpan', mockBeforeStartNavigationSpanCallback);
+
+      startBrowserTracingNavigationSpan(client, { name: 'test span', op: 'navigation' });
+
+      expect(mockBeforeStartNavigationSpanCallback).toHaveBeenCalledWith(
+        { name: 'test span', op: 'navigation' },
+        { isRedirect: undefined },
+      );
+    });
   });
 
   describe('using the <meta> tag data', () => {

packages/core/src/client.ts

@@ -603,6 +603,15 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     ) => void,
   ): () => void;
 
+  /**
+   * A hook for triggering right before a navigation span is started.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(
+    hook: 'beforeStartNavigationSpan',
+    callback: (options: StartSpanOptions, navigationOptions?: { isRedirect?: boolean }) => void,
+  ): () => void;
+
   /**
    * A hook for browser tracing integrations to trigger a span for a navigation.
    * @returns {() => void} A function that, when executed, removes the registered callback.
@@ -782,6 +791,15 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     traceOptions?: { sentryTrace?: string | undefined; baggage?: string | undefined },
   ): void;
 
+  /**
+   * Emit a hook event for triggering right before a navigation span is started.
+   */
+  public emit(
+    hook: 'beforeStartNavigationSpan',
+    options: StartSpanOptions,
+    navigationOptions?: { isRedirect?: boolean },
+  ): void;
+
   /**
    * Emit a hook event for browser tracing integrations to trigger a span for a navigation.
    */

packages/nextjs/test/performance/pagesRouterInstrumentation.test.ts

@@ -321,19 +321,25 @@ describe('pagesRouterInstrumentNavigation', () => {
 
       Router.events.emit('routeChangeStart', targetLocation);
 
-      expect(emit).toHaveBeenCalledTimes(1);
+      expect(emit).toHaveBeenCalledTimes(2);
+      const expectedStartSpanOptions = {
+        name: expectedTransactionName,
+        attributes: {
+          'sentry.op': 'navigation',
+          'sentry.origin': 'auto.navigation.nextjs.pages_router_instrumentation',
+          'sentry.source': expectedTransactionSource,
+        },
+      };
       expect(emit).toHaveBeenCalledWith(
-        'startNavigationSpan',
-        expect.objectContaining({
-          name: expectedTransactionName,
-          attributes: {
-            'sentry.op': 'navigation',
-            'sentry.origin': 'auto.navigation.nextjs.pages_router_instrumentation',
-            'sentry.source': expectedTransactionSource,
-          },
-        }),
-        { isRedirect: undefined },
+        'beforeStartNavigationSpan',
+        expect.objectContaining(expectedStartSpanOptions),
+        {
+          isRedirect: undefined,
+        },
       );
+      expect(emit).toHaveBeenCalledWith('startNavigationSpan', expect.objectContaining(expectedStartSpanOptions), {
+        isRedirect: undefined,
+      });
     },
   );
 });