feat(browser): Add beforeStartNavigationSpan lifecycle hook

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);
   client.emit('startNavigationSpan', spanOptions, { isRedirect });
 
   const scope = getCurrentScope();

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

@@ -788,6 +788,24 @@ 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' });
+    });
   });
 
   describe('using the <meta> tag data', () => {

packages/core/src/client.ts

@@ -603,6 +603,12 @@ 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) => 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 +788,11 @@ 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): 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,
+      });
     },
   );
 });