feat(nextjs): Use spans generated by Next.js for App Router (#12729)

Author: Luca Forstner

CHANGELOG.md

@@ -8,6 +8,27 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+### Important Changes
+
+- **feat(nextjs): Use spans generated by Next.js for App Router (#12729)**
+
+Previously, the `@sentry/nextjs` SDK automatically recorded spans in the form of transactions for each of your top-level
+server components (pages, layouts, ...). This approach had a few drawbacks, the main ones being that traces didn't have
+a root span, and more importantly, if you had data stream to the client, its duration was not captured because the
+server component spans had finished before the data could finish streaming.
+
+With this release, we will capture the duration of App Router requests in their entirety as a single transaction with
+server component spans being descendants of that transaction. This means you will get more data that is also more
+accurate. Note that this does not apply to the Edge runtime. For the Edge runtime, the SDK will emit transactions as it
+has before.
+
+Generally speaking, this change means that you will see less _transactions_ and more _spans_ in Sentry. Your will no
+longer receive server component transactions like `Page Server Component (/path/to/route)` (unless using the Edge
+runtime), and you will instead receive transactions for your App Router SSR requests that look like
+`GET /path/to/route`.
+
+If you are on Sentry SaaS, this may have an effect on your quota consumption: Less transactions, more spans.
+
 ## 8.15.0
 
 - feat(core): allow unregistering callback through `on` (#11710)

dev-packages/e2e-tests/test-applications/create-next-app/package.json

@@ -12,7 +12,6 @@
     "test:assert": "pnpm test:prod && pnpm test:dev"
   },
   "dependencies": {
-    "@next/font": "13.0.7",
     "@sentry/nextjs": "latest || *",
     "@types/node": "18.11.17",
     "@types/react": "18.0.26",

dev-packages/e2e-tests/test-applications/nextjs-14/app/propagation/test-outgoing-fetch-external-disallowed/route.ts

@@ -3,8 +3,8 @@ import { NextResponse } from 'next/server';
 export const dynamic = 'force-dynamic';
 
 export async function GET() {
-  const data = await fetch(`http://localhost:3030/propagation/test-outgoing-fetch-external-disallowed/check`).then(
-    res => res.json(),
-  );
+  const data = await fetch(`http://localhost:3030/propagation/test-outgoing-fetch-external-disallowed/check`, {
+    cache: 'no-store',
+  }).then(res => res.json());
   return NextResponse.json(data);
 }

dev-packages/e2e-tests/test-applications/nextjs-14/app/propagation/test-outgoing-fetch/route.ts

@@ -3,6 +3,8 @@ import { NextResponse } from 'next/server';
 export const dynamic = 'force-dynamic';
 
 export async function GET() {
-  const data = await fetch(`http://localhost:3030/propagation/test-outgoing-fetch/check`).then(res => res.json());
+  const data = await fetch(`http://localhost:3030/propagation/test-outgoing-fetch/check`, { cache: 'no-store' }).then(
+    res => res.json(),
+  );
   return NextResponse.json(data);
 }

dev-packages/e2e-tests/test-applications/nextjs-14/playwright.config.ts

@@ -5,9 +5,15 @@ if (!testEnv) {
   throw new Error('No test env defined');
 }
 
-const config = getPlaywrightConfig({
-  startCommand: testEnv === 'development' ? 'pnpm next dev -p 3030' : 'pnpm next start -p 3030',
-  port: 3030,
-});
+const config = getPlaywrightConfig(
+  {
+    startCommand: testEnv === 'development' ? 'pnpm next dev -p 3030' : 'pnpm next start -p 3030',
+    port: 3030,
+  },
+  {
+    // This comes with the risk of tests leaking into each other but the tests run quite slow so we should parallelize
+    workers: '100%',
+  },
+);
 
 export default config;

dev-packages/e2e-tests/test-applications/nextjs-14/tests/generation-functions.test.ts

@@ -1,19 +1,29 @@
 import { expect, test } from '@playwright/test';
 import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
-test('Should send a transaction event for a generateMetadata() function invokation', async ({ page }) => {
-  const testTitle = 'foobarasdf';
+test('Should emit a span for a generateMetadata() function invokation', async ({ page }) => {
+  const testTitle = 'should-emit-span';
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent?.transaction === 'Page.generateMetadata (/generation-functions)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.metadataTitle === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] === `/generation-functions?metadataTitle=${testTitle}`
     );
   });
 
   await page.goto(`/generation-functions?metadataTitle=${testTitle}`);
 
-  expect(await transactionPromise).toBeDefined();
+  const transaction = await transactionPromise;
+
+  expect(transaction.spans).toContainEqual(
+    expect.objectContaining({
+      description: 'generateMetadata /generation-functions/page',
+      origin: 'manual',
+      parent_span_id: expect.any(String),
+      span_id: expect.any(String),
+      status: 'ok',
+      trace_id: expect.any(String),
+    }),
+  );
 
   const pageTitle = await page.title();
   expect(pageTitle).toBe(testTitle);
@@ -22,12 +32,12 @@ test('Should send a transaction event for a generateMetadata() function invokati
 test('Should send a transaction and an error event for a faulty generateMetadata() function invokation', async ({
   page,
 }) => {
-  const testTitle = 'foobarbaz';
+  const testTitle = 'should-emit-error';
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent.transaction === 'Page.generateMetadata (/generation-functions)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.metadataTitle === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] ===
+      `/generation-functions?metadataTitle=${testTitle}&shouldThrowInGenerateMetadata=1`
     );
   });
 
@@ -54,14 +64,23 @@ test('Should send a transaction event for a generateViewport() function invokati
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent?.transaction === 'Page.generateViewport (/generation-functions)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.viewportThemeColor === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] ===
+      `/generation-functions?viewportThemeColor=${testTitle}`
     );
   });
 
   await page.goto(`/generation-functions?viewportThemeColor=${testTitle}`);
 
-  expect(await transactionPromise).toBeDefined();
+  expect((await transactionPromise).spans).toContainEqual(
+    expect.objectContaining({
+      description: 'generateViewport /generation-functions/page',
+      origin: 'manual',
+      parent_span_id: expect.any(String),
+      span_id: expect.any(String),
+      status: 'ok',
+      trace_id: expect.any(String),
+    }),
+  );
 });
 
 test('Should send a transaction and an error event for a faulty generateViewport() function invokation', async ({
@@ -71,8 +90,8 @@ test('Should send a transaction and an error event for a faulty generateViewport
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent?.transaction === 'Page.generateViewport (/generation-functions)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.viewportThemeColor === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] ===
+      `/generation-functions?viewportThemeColor=${testTitle}&shouldThrowInGenerateViewport=1`
     );
   });
 
@@ -97,8 +116,8 @@ test('Should send a transaction event with correct status for a generateMetadata
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent?.transaction === 'Page.generateMetadata (/generation-functions/with-redirect)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.metadataTitle === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] ===
+      `/generation-functions/with-redirect?metadataTitle=${testTitle}`
     );
   });
 
@@ -114,8 +133,8 @@ test('Should send a transaction event with correct status for a generateMetadata
 
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
     return (
-      transactionEvent?.transaction === 'Page.generateMetadata (/generation-functions/with-notfound)' &&
-      (transactionEvent.extra?.route_data as any)?.searchParams?.metadataTitle === testTitle
+      transactionEvent.contexts?.trace?.data?.['http.target'] ===
+      `/generation-functions/with-notfound?metadataTitle=${testTitle}`
     );
   });
 

dev-packages/e2e-tests/test-applications/nextjs-14/tests/request-instrumentation.test.ts

@@ -3,7 +3,7 @@ import { waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Should send a transaction with a fetch span', async ({ page }) => {
   const transactionPromise = waitForTransaction('nextjs-14', async transactionEvent => {
-    return transactionEvent?.transaction === 'Page Server Component (/request-instrumentation)';
+    return transactionEvent?.transaction === 'GET /request-instrumentation';
   });
 
   await page.goto(`/request-instrumentation`);

dev-packages/e2e-tests/test-applications/nextjs-15/app/pageload-tracing/page.tsx

@@ -6,7 +6,7 @@ export default async function Page() {
 }
 
 export async function generateMetadata() {
-  (await fetch('http://example.com/')).text();
+  (await fetch('http://example.com/', { cache: 'no-store' })).text();
 
   return {
     title: 'my title',

dev-packages/e2e-tests/test-applications/nextjs-15/playwright.config.mjs

@@ -5,9 +5,15 @@ if (!testEnv) {
   throw new Error('No test env defined');
 }
 
-const config = getPlaywrightConfig({
-  startCommand: testEnv === 'development' ? 'pnpm next dev -p 3030' : 'pnpm next start -p 3030',
-  port: 3030,
-});
+const config = getPlaywrightConfig(
+  {
+    startCommand: testEnv === 'development' ? 'pnpm next dev -p 3030' : 'pnpm next start -p 3030',
+    port: 3030,
+  },
+  {
+    // This comes with the risk of tests leaking into each other but the tests run quite slow so we should parallelize
+    workers: '100%',
+  },
+);
 
 export default config;

dev-packages/e2e-tests/test-applications/nextjs-15/tests/pageload-tracing.test.ts

@@ -1,17 +1,9 @@
 import { expect, test } from '@playwright/test';
 import { waitForTransaction } from '@sentry-internal/test-utils';
 
-test('all server component transactions should be attached to the pageload request span', async ({ page }) => {
-  const pageServerComponentTransactionPromise = waitForTransaction('nextjs-15', async transactionEvent => {
-    return transactionEvent?.transaction === 'Page Server Component (/pageload-tracing)';
-  });
-
-  const layoutServerComponentTransactionPromise = waitForTransaction('nextjs-15', async transactionEvent => {
-    return transactionEvent?.transaction === 'Layout Server Component (/pageload-tracing)';
-  });
-
-  const metadataTransactionPromise = waitForTransaction('nextjs-15', async transactionEvent => {
-    return transactionEvent?.transaction === 'Page.generateMetadata (/pageload-tracing)';
+test('App router transactions should be attached to the pageload request span', async ({ page }) => {
+  const serverTransactionPromise = waitForTransaction('nextjs-15', async transactionEvent => {
+    return transactionEvent?.transaction === 'GET /pageload-tracing';
   });
 
   const pageloadTransactionPromise = waitForTransaction('nextjs-15', async transactionEvent => {
@@ -20,18 +12,13 @@ test('all server component transactions should be attached to the pageload reque
 
   await page.goto(`/pageload-tracing`);
 
-  const [pageServerComponentTransaction, layoutServerComponentTransaction, metadataTransaction, pageloadTransaction] =
-    await Promise.all([
-      pageServerComponentTransactionPromise,
-      layoutServerComponentTransactionPromise,
-      metadataTransactionPromise,
-      pageloadTransactionPromise,
-    ]);
+  const [serverTransaction, pageloadTransaction] = await Promise.all([
+    serverTransactionPromise,
+    pageloadTransactionPromise,
+  ]);
 
   const pageloadTraceId = pageloadTransaction.contexts?.trace?.trace_id;
 
   expect(pageloadTraceId).toBeTruthy();
-  expect(pageServerComponentTransaction.contexts?.trace?.trace_id).toBe(pageloadTraceId);
-  expect(layoutServerComponentTransaction.contexts?.trace?.trace_id).toBe(pageloadTraceId);
-  expect(metadataTransaction.contexts?.trace?.trace_id).toBe(pageloadTraceId);
+  expect(serverTransaction.contexts?.trace?.trace_id).toBe(pageloadTraceId);
 });