feat(nextjs): Add client routing instrumentation for app router (#9446)

Author: Luca Forstner

packages/e2e-tests/test-applications/nextjs-app-dir/tests/client-app-routing-instrumentation.test.ts

@@ -0,0 +1,52 @@
+import { test, expect } from '@playwright/test';
+import { waitForTransaction } from '../event-proxy-server';
+
+test('Creates a pageload transaction for app router routes', async ({ page }) => {
+  const randomRoute = String(Math.random());
+
+  const clientPageloadTransactionPromise = waitForTransaction('nextjs-13-app-dir', transactionEvent => {
+    return (
+      transactionEvent?.transaction === `/server-component/parameter/${randomRoute}` &&
+      transactionEvent.contexts?.trace?.op === 'pageload'
+    );
+  });
+
+  await page.goto(`/server-component/parameter/${randomRoute}`);
+
+  expect(await clientPageloadTransactionPromise).toBeDefined();
+});
+
+test('Creates a navigation transaction for app router routes', async ({ page }) => {
+  const randomRoute = String(Math.random());
+
+  const clientPageloadTransactionPromise = waitForTransaction('nextjs-13-app-dir', transactionEvent => {
+    return (
+      transactionEvent?.transaction === `/server-component/parameter/${randomRoute}` &&
+      transactionEvent.contexts?.trace?.op === 'pageload'
+    );
+  });
+
+  await page.goto(`/server-component/parameter/${randomRoute}`);
+  await clientPageloadTransactionPromise;
+  await page.getByText('Page (/server-component/parameter/[parameter])').isVisible();
+
+  const clientNavigationTransactionPromise = waitForTransaction('nextjs-13-app-dir', transactionEvent => {
+    return (
+      transactionEvent?.transaction === '/server-component/parameter/foo/bar/baz' &&
+      transactionEvent.contexts?.trace?.op === 'navigation'
+    );
+  });
+
+  const servercomponentTransactionPromise = waitForTransaction('nextjs-13-app-dir', async transactionEvent => {
+    return (
+      transactionEvent?.transaction === 'Page Server Component (/server-component/parameter/[...parameters])' &&
+      (await clientNavigationTransactionPromise).contexts?.trace?.trace_id ===
+        transactionEvent.contexts?.trace?.trace_id
+    );
+  });
+
+  await page.getByText('/server-component/parameter/foo/bar/baz').click();
+
+  expect(await clientNavigationTransactionPromise).toBeDefined();
+  expect(await servercomponentTransactionPromise).toBeDefined();
+});

packages/e2e-tests/test-applications/nextjs-app-dir/tests/trace.test.ts

@@ -14,11 +14,11 @@ import { addOrUpdateIntegration } from '@sentry/utils';
 import { devErrorSymbolicationEventProcessor } from '../common/devErrorSymbolicationEventProcessor';
 import { getVercelEnv } from '../common/getVercelEnv';
 import { buildMetadata } from '../common/metadata';
-import { nextRouterInstrumentation } from './performance';
+import { nextRouterInstrumentation } from './routing/nextRoutingInstrumentation';
 import { applyTunnelRouteOption } from './tunnelRoute';
 
 export * from '@sentry/react';
-export { nextRouterInstrumentation } from './performance';
+export { nextRouterInstrumentation } from './routing/nextRoutingInstrumentation';
 export { captureUnderscoreErrorException } from '../common/_error';
 
 export { Integrations };

packages/nextjs/src/client/index.ts

@@ -0,0 +1,113 @@
+import { WINDOW } from '@sentry/react';
+import type { HandlerDataFetch, Primitive, Transaction, TransactionContext } from '@sentry/types';
+import { addInstrumentationHandler, browserPerformanceTimeOrigin } from '@sentry/utils';
+
+type StartTransactionCb = (context: TransactionContext) => Transaction | undefined;
+
+const DEFAULT_TAGS = {
+  'routing.instrumentation': 'next-app-router',
+} as const;
+
+/**
+ * Instruments the Next.js Clientside App Router.
+ */
+export function appRouterInstrumentation(
+  startTransactionCb: StartTransactionCb,
+  startTransactionOnPageLoad: boolean = true,
+  startTransactionOnLocationChange: boolean = true,
+): void {
+  // We keep track of the active transaction so we can finish it when we start a navigation transaction.
+  let activeTransaction: Transaction | undefined = undefined;
+
+  // We keep track of the previous location name so we can set the `from` field on navigation transactions.
+  // This is either a route or a pathname.
+  let prevLocationName = WINDOW.location.pathname;
+
+  if (startTransactionOnPageLoad) {
+    activeTransaction = startTransactionCb({
+      name: prevLocationName,
+      op: 'pageload',
+      origin: 'auto.pageload.nextjs.app_router_instrumentation',
+      tags: DEFAULT_TAGS,
+      // pageload should always start at timeOrigin (and needs to be in s, not ms)
+      startTimestamp: browserPerformanceTimeOrigin ? browserPerformanceTimeOrigin / 1000 : undefined,
+      metadata: { source: 'url' },
+    });
+  }
+
+  if (startTransactionOnLocationChange) {
+    addInstrumentationHandler('fetch', (handlerData: HandlerDataFetch) => {
+      // The instrumentation handler is invoked twice - once for starting a request and once when the req finishes
+      // We can use the existence of the end-timestamp to filter out "finishing"-events.
+      if (handlerData.endTimestamp !== undefined) {
+        return;
+      }
+
+      // Only GET requests can be navigating RSC requests
+      if (handlerData.fetchData.method !== 'GET') {
+        return;
+      }
+
+      const parsedNavigatingRscFetchArgs = parseNavigatingRscFetchArgs(handlerData.args);
+
+      if (parsedNavigatingRscFetchArgs === null) {
+        return;
+      }
+
+      const transactionName = parsedNavigatingRscFetchArgs.targetPathname;
+      const tags: Record<string, Primitive> = {
+        ...DEFAULT_TAGS,
+        from: prevLocationName,
+      };
+
+      prevLocationName = transactionName;
+
+      if (activeTransaction) {
+        activeTransaction.finish();
+      }
+
+      startTransactionCb({
+        name: transactionName,
+        op: 'navigation',
+        origin: 'auto.navigation.nextjs.app_router_instrumentation',
+        tags,
+        metadata: { source: 'url' },
+      });
+    });
+  }
+}
+
+function parseNavigatingRscFetchArgs(fetchArgs: unknown[]): null | {
+  targetPathname: string;
+} {
+  // Make sure the first arg is a URL object
+  if (!fetchArgs[0] || typeof fetchArgs[0] !== 'object' || (fetchArgs[0] as URL).searchParams === undefined) {
+    return null;
+  }
+
+  // Make sure the second argument is some kind of fetch config obj that contains headers
+  if (!fetchArgs[1] || typeof fetchArgs[1] !== 'object' || !('headers' in fetchArgs[1])) {
+    return null;
+  }
+
+  try {
+    const url = fetchArgs[0] as URL;
+    const headers = fetchArgs[1].headers as Record<string, string>;
+
+    // Not an RSC request
+    if (headers['RSC'] !== '1') {
+      return null;
+    }
+
+    // Prefetch requests are not navigating RSC requests
+    if (headers['Next-Router-Prefetch'] === '1') {
+      return null;
+    }
+
+    return {
+      targetPathname: url.pathname,
+    };
+  } catch {
+    return null;
+  }
+}

packages/nextjs/src/client/routing/appRouterRoutingInstrumentation.ts

@@ -0,0 +1,23 @@
+import { WINDOW } from '@sentry/react';
+import type { Transaction, TransactionContext } from '@sentry/types';
+
+import { appRouterInstrumentation } from './appRouterRoutingInstrumentation';
+import { pagesRouterInstrumentation } from './pagesRouterRoutingInstrumentation';
+
+type StartTransactionCb = (context: TransactionContext) => Transaction | undefined;
+
+/**
+ * Instruments the Next.js Clientside Router.
+ */
+export function nextRouterInstrumentation(
+  startTransactionCb: StartTransactionCb,
+  startTransactionOnPageLoad: boolean = true,
+  startTransactionOnLocationChange: boolean = true,
+): void {
+  const isAppRouter = !WINDOW.document.getElementById('__NEXT_DATA__');
+  if (isAppRouter) {
+    appRouterInstrumentation(startTransactionCb, startTransactionOnPageLoad, startTransactionOnLocationChange);
+  } else {
+    pagesRouterInstrumentation(startTransactionCb, startTransactionOnPageLoad, startTransactionOnLocationChange);
+  }
+}

packages/nextjs/src/client/routing/nextRoutingInstrumentation.ts

@@ -1,7 +1,12 @@
 import { getCurrentHub } from '@sentry/core';
 import { WINDOW } from '@sentry/react';
 import type { Primitive, Transaction, TransactionContext, TransactionSource } from '@sentry/types';
-import { logger, stripUrlQueryAndFragment, tracingContextFromHeaders } from '@sentry/utils';
+import {
+  browserPerformanceTimeOrigin,
+  logger,
+  stripUrlQueryAndFragment,
+  tracingContextFromHeaders,
+} from '@sentry/utils';
 import type { NEXT_DATA as NextData } from 'next/dist/next-server/lib/utils';
 import { default as Router } from 'next/router';
 import type { ParsedUrlQuery } from 'querystring';
@@ -86,7 +91,7 @@ function extractNextDataTagInformation(): NextDataTagInfo {
 }
 
 const DEFAULT_TAGS = {
-  'routing.instrumentation': 'next-router',
+  'routing.instrumentation': 'next-pages-router',
 } as const;
 
 // We keep track of the active transaction so we can finish it when we start a navigation transaction.
@@ -99,14 +104,14 @@ let prevLocationName: string | undefined = undefined;
 const client = getCurrentHub().getClient();
 
 /**
- * Creates routing instrumention for Next Router. Only supported for
+ * Instruments the Next.js pages router. Only supported for
  * client side routing. Works for Next >= 10.
  *
  * Leverages the SingletonRouter from the `next/router` to
  * generate pageload/navigation transactions and parameterize
  * transaction names.
  */
-export function nextRouterInstrumentation(
+export function pagesRouterInstrumentation(
   startTransactionCb: StartTransactionCb,
   startTransactionOnPageLoad: boolean = true,
   startTransactionOnLocationChange: boolean = true,
@@ -125,7 +130,10 @@ export function nextRouterInstrumentation(
     activeTransaction = startTransactionCb({
       name: prevLocationName,
       op: 'pageload',
+      origin: 'auto.pageload.nextjs.pages_router_instrumentation',
       tags: DEFAULT_TAGS,
+      // pageload should always start at timeOrigin (and needs to be in s, not ms)
+      startTimestamp: browserPerformanceTimeOrigin ? browserPerformanceTimeOrigin / 1000 : undefined,
       ...(params && client && client.getOptions().sendDefaultPii && { data: params }),
       ...traceparentData,
       metadata: {
@@ -165,6 +173,7 @@ export function nextRouterInstrumentation(
       const navigationTransaction = startTransactionCb({
         name: transactionName,
         op: 'navigation',
+        origin: 'auto.navigation.nextjs.pages_router_instrumentation',
         tags,
         metadata: { source: transactionSource },
       });
@@ -177,8 +186,8 @@ export function nextRouterInstrumentation(
         // hooks). Instead, we'll simply let the navigation transaction finish itself (it's an `IdleTransaction`).
         const nextRouteChangeSpan = navigationTransaction.startChild({
           op: 'ui.nextjs.route-change',
+          origin: 'auto.ui.nextjs.pages_router_instrumentation',
           description: 'Next.js Route Change',
-          origin: 'auto.navigation.nextjs',
         });
 
         const finishRouteChangeSpan = (): void => {