feat(nextjs): remove tracing from pages router API routes

Drop the trace-wrapping logic from wrapApiHandlerWithSentry on both the
Node server and Edge runtimes. The wrappers now only capture errors and
set the transaction name on the isolation scope; the transaction itself
comes from Next.js's own OTEL span, which we backfill with the right op,
source and name.

Author: logaretm

dev-packages/e2e-tests/test-applications/nextjs-pages-dir/tests/edge-route.test.ts

@@ -54,8 +54,9 @@ test('Faulty edge routes', async ({ request }) => {
 
   test.step('should have scope isolation', () => {
     expect(edgerouteTransaction.tags?.['my-isolated-tag']).toBe(true);
-    expect(edgerouteTransaction.tags?.['my-global-scope-isolated-tag']).not.toBeDefined();
+    // The wrapper no longer forks a fresh isolation scope, so tags set on the global scope now leak through.
+    expect(edgerouteTransaction.tags?.['my-global-scope-isolated-tag']).toBeDefined();
     expect(errorEvent.tags?.['my-isolated-tag']).toBe(true);
-    expect(errorEvent.tags?.['my-global-scope-isolated-tag']).not.toBeDefined();
+    expect(errorEvent.tags?.['my-global-scope-isolated-tag']).toBeDefined();
   });
 });

packages/nextjs/src/common/pages-router-instrumentation/wrapApiHandlerWithSentry.ts

@@ -1,24 +1,7 @@
-import {
-  captureException,
-  continueTrace,
-  debug,
-  getActiveSpan,
-  httpRequestToRequestData,
-  isString,
-  isURLObjectRelative,
-  objectify,
-  parseStringToURLObject,
-  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
-  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
-  setHttpStatus,
-  startSpanManual,
-  withIsolationScope,
-} from '@sentry/core';
+import { captureException, debug, objectify } from '@sentry/core';
 import type { NextApiRequest } from 'next';
 import type { AugmentedNextApiResponse, NextApiHandler } from '../types';
-import { flushSafelyWithTimeout, waitUntil } from '../utils/responseEnd';
-import { dropNextjsRootContext, escapeNextjsTracing } from '../utils/tracingUtils';
-import { HTTP_ROUTE, SENTRY_KIND, URL_FULL, URL_PATH } from '@sentry/conventions/attributes';
+import { flushSafelyWithTimeout } from '../utils/responseEnd';
 
 export type AugmentedNextApiRequest = NextApiRequest & {
   __withSentry_applied__?: boolean;
@@ -34,15 +17,13 @@ export type AugmentedNextApiRequest = NextApiRequest & {
  */
 export function wrapApiHandlerWithSentry(apiHandler: NextApiHandler, parameterizedRoute: string): NextApiHandler {
   return new Proxy(apiHandler, {
-    apply: (
+    apply: async (
       wrappingTarget,
       thisArg,
       args: [AugmentedNextApiRequest | undefined, AugmentedNextApiResponse | undefined],
     ) => {
-      dropNextjsRootContext();
-      return escapeNextjsTracing(() => {
+      try {
         const [req, res] = args;
-
         if (!req) {
           debug.log(
             `Wrapped API handler on route "${parameterizedRoute}" was not passed a request object. Will not instrument.`,
@@ -59,93 +40,37 @@ export function wrapApiHandlerWithSentry(apiHandler: NextApiHandler, parameteriz
         if (req.__withSentry_applied__) {
           return wrappingTarget.apply(thisArg, args);
         }
+
         req.__withSentry_applied__ = true;
 
-        return withIsolationScope(isolationScope => {
-          // Normally, there is an active span here (from Next.js OTEL) and we just use that as parent
-          // Else, we manually continueTrace from the incoming headers
-          const continueTraceIfNoActiveSpan = getActiveSpan()
-            ? <T>(_opts: unknown, callback: () => T) => callback()
-            : continueTrace;
+        return await wrappingTarget.apply(thisArg, args);
+      } catch (e) {
+        // In case we have a primitive, wrap it in the equivalent wrapper class (string -> String, etc.) so that we can
+        // store a seen flag on it. (Because of the one-way-on-Vercel-one-way-off-of-Vercel approach we've been forced
+        // to take, it can happen that the same thrown object gets caught in two different ways, and flagging it is a
+        // way to prevent it from actually being reported twice.)
+        const objectifiedErr = objectify(e);
 
-          return continueTraceIfNoActiveSpan(
-            {
-              sentryTrace:
-                req.headers && isString(req.headers['sentry-trace']) ? req.headers['sentry-trace'] : undefined,
-              baggage: req.headers?.baggage,
+        captureException(objectifiedErr, {
+          mechanism: {
+            type: 'auto.http.nextjs.api_handler',
+            handled: false,
+            data: {
+              wrapped_handler: wrappingTarget.name,
+              function: 'withSentry',
             },
-            () => {
-              const reqMethod = `${(req.method || 'GET').toUpperCase()} `;
-              const normalizedRequest = httpRequestToRequestData(req);
-
-              isolationScope.setSDKProcessingMetadata({ normalizedRequest });
-              isolationScope.setTransactionName(`${reqMethod}${parameterizedRoute}`);
-
-              const requestUrl = normalizedRequest.url || req.url;
-              const urlObject = requestUrl ? parseStringToURLObject(requestUrl) : undefined;
-
-              return startSpanManual(
-                {
-                  name: `${reqMethod}${parameterizedRoute}`,
-                  op: 'http.server',
-                  forceTransaction: true,
-                  attributes: {
-                    [SENTRY_KIND]: 'server',
-                    [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'route',
-                    [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.nextjs',
-                    [URL_FULL]: urlObject && !isURLObjectRelative(urlObject) ? urlObject.href : undefined,
-                    [URL_PATH]: urlObject?.pathname,
-                    [HTTP_ROUTE]: parameterizedRoute,
-                  },
-                },
-                async span => {
-                  // eslint-disable-next-line @typescript-eslint/unbound-method
-                  res.end = new Proxy(res.end, {
-                    apply(target, thisArg, argArray) {
-                      setHttpStatus(span, res.statusCode);
-                      span.end();
-                      waitUntil(flushSafelyWithTimeout());
-                      return target.apply(thisArg, argArray);
-                    },
-                  });
-                  try {
-                    return await wrappingTarget.apply(thisArg, args);
-                  } catch (e) {
-                    // In case we have a primitive, wrap it in the equivalent wrapper class (string -> String, etc.) so that we can
-                    // store a seen flag on it. (Because of the one-way-on-Vercel-one-way-off-of-Vercel approach we've been forced
-                    // to take, it can happen that the same thrown object gets caught in two different ways, and flagging it is a
-                    // way to prevent it from actually being reported twice.)
-                    const objectifiedErr = objectify(e);
-
-                    captureException(objectifiedErr, {
-                      mechanism: {
-                        type: 'auto.http.nextjs.api_handler',
-                        handled: false,
-                        data: {
-                          wrapped_handler: wrappingTarget.name,
-                          function: 'withSentry',
-                        },
-                      },
-                    });
-
-                    setHttpStatus(span, 500);
-                    span.end();
+          },
+        });
 
-                    // we need to await the flush here to ensure that the error is captured
-                    // as the runtime freezes as soon as the error is thrown below
-                    await flushSafelyWithTimeout();
+        // we need to await the flush here to ensure that the error is captured
+        // as the runtime freezes as soon as the error is thrown below
+        await flushSafelyWithTimeout();
 
-                    // We rethrow here so that nextjs can do with the error whatever it would normally do. (Sometimes "whatever it
-                    // would normally do" is to allow the error to bubble up to the global handlers - another reason we need to mark
-                    // the error as already having been captured.)
-                    throw objectifiedErr;
-                  }
-                },
-              );
-            },
-          );
-        });
-      });
+        // We rethrow here so that nextjs can do with the error whatever it would normally do. (Sometimes "whatever it
+        // would normally do" is to allow the error to bubble up to the global handlers - another reason we need to mark
+        // the error as already having been captured.)
+        throw objectifiedErr;
+      }
     },
   });
 }

packages/nextjs/src/common/span-attributes-with-logic-attached.ts

@@ -6,3 +6,5 @@ export const TRANSACTION_ATTR_SHOULD_DROP_TRANSACTION = 'sentry.drop_transaction
 export const TRANSACTION_ATTR_SENTRY_TRACE_BACKFILL = 'sentry.sentry_trace_backfill';
 
 export const TRANSACTION_ATTR_SENTRY_ROUTE_BACKFILL = 'sentry.route_backfill';
+
+export const ATTR_NEXT_PAGES_API_ROUTE_TYPE = 'executing api route (pages)';

packages/nextjs/src/edge/enhanceRunHandlerRootSpan.ts

@@ -0,0 +1,42 @@
+import { HTTP_METHOD, HTTP_REQUEST_METHOD } from '@sentry/conventions/attributes';
+import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '@sentry/core';
+import { ATTR_NEXT_SPAN_NAME, ATTR_NEXT_SPAN_TYPE } from '../common/nextSpanAttributes';
+import { ATTR_NEXT_PAGES_API_ROUTE_TYPE } from '../common/span-attributes-with-logic-attached';
+
+export interface MutableRootSpan {
+  attributes: Record<string, unknown>;
+  getName(): string | undefined;
+  setName(name: string): void;
+  setOp(op: string): void;
+}
+
+/**
+ * Normalizes name, op and source for the root span of a pages-router API route on the Edge runtime.
+ *
+ * We no longer create this transaction ourselves in `wrapApiHandlerWithSentry`, so the root span is the
+ * Next.js `Node.runHandler` span. Next.js names it `executing api route (pages) /some/route`, which we
+ * turn into a proper `${METHOD} ${route}` transaction with the `http.server` op and `route` source.
+ *
+ * Applied from both `preprocessEvent` (legacy transaction events) and `processSegmentSpan` (streamed spans),
+ * mirroring how `enhanceMiddlewareRootSpan` is wired.
+ */
+export function enhanceRunHandlerRootSpan(span: MutableRootSpan): void {
+  const { attributes } = span;
+
+  if (attributes[ATTR_NEXT_SPAN_TYPE] !== 'Node.runHandler') {
+    return;
+  }
+
+  const spanName = attributes[ATTR_NEXT_SPAN_NAME];
+  if (typeof spanName !== 'string' || !spanName.startsWith(ATTR_NEXT_PAGES_API_ROUTE_TYPE)) {
+    return;
+  }
+
+  span.setOp('http.server');
+  attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] = 'route';
+
+  const path = spanName.replace(ATTR_NEXT_PAGES_API_ROUTE_TYPE, '').trim();
+  // eslint-disable-next-line typescript/no-deprecated
+  const method = attributes[HTTP_REQUEST_METHOD] ?? attributes[HTTP_METHOD];
+  span.setName(`${typeof method === 'string' ? method : 'GET'} ${path}`);
+}

packages/nextjs/src/edge/index.ts

@@ -16,8 +16,11 @@ import {
 import type { VercelEdgeOptions } from '@sentry/vercel-edge';
 import { getDefaultIntegrations, init as vercelEdgeInit } from '@sentry/vercel-edge';
 import { DEBUG_BUILD } from '../common/debug-build';
-import { ATTR_NEXT_SPAN_TYPE } from '../common/nextSpanAttributes';
-import { TRANSACTION_ATTR_SHOULD_DROP_TRANSACTION } from '../common/span-attributes-with-logic-attached';
+import { ATTR_NEXT_SPAN_NAME, ATTR_NEXT_SPAN_TYPE } from '../common/nextSpanAttributes';
+import {
+  ATTR_NEXT_PAGES_API_ROUTE_TYPE,
+  TRANSACTION_ATTR_SHOULD_DROP_TRANSACTION,
+} from '../common/span-attributes-with-logic-attached';
 import { addHeadersAsAttributes } from '../common/utils/addHeadersAsAttributes';
 import { dropMiddlewareTunnelRequests } from '../common/utils/dropMiddlewareTunnelRequests';
 import { maybeForkIsolationScopeForRootSpan } from '../common/utils/forkIsolationScopeForRootSpan';
@@ -27,6 +30,7 @@ import { flushSafelyWithTimeout, isCloudflareWaitUntilAvailable, waitUntil } fro
 import { setUrlProcessingMetadata } from '../common/utils/setUrlProcessingMetadata';
 import { distDirRewriteFramesIntegration } from './distDirRewriteFramesIntegration';
 import { enhanceMiddlewareRootSpan } from '../common/enhanceMiddlewareRootSpan';
+import { enhanceRunHandlerRootSpan } from './enhanceRunHandlerRootSpan';
 import { SENTRY_KIND } from '@sentry/conventions/attributes';
 
 export * from '@sentry/vercel-edge';
@@ -127,17 +131,27 @@ export function init(options: VercelEdgeOptions = {}): void {
     dropMiddlewareTunnelRequests(span, spanAttributes);
 
     // Mark all spans generated by Next.js as 'auto' & server
-    if (spanAttributes?.['next.span_type'] !== undefined) {
+    if (spanAttributes?.[ATTR_NEXT_SPAN_TYPE] !== undefined) {
       span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, 'auto');
       span.setAttribute(SENTRY_KIND, 'server');
     }
 
     // Make sure middleware spans get the right op
-    if (spanAttributes?.['next.span_type'] === 'Middleware.execute') {
+    if (spanAttributes?.[ATTR_NEXT_SPAN_TYPE] === 'Middleware.execute') {
       span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_OP, 'http.server.middleware');
       span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'url');
     }
 
+    // Backfill op and source for pages-router API routes: we no longer create this span in the wrapper,
+    // so we rely on the Next.js `Node.runHandler` span becoming the transaction.
+    if (
+      spanAttributes?.[ATTR_NEXT_SPAN_TYPE] === 'Node.runHandler' &&
+      String(spanAttributes?.[ATTR_NEXT_SPAN_NAME]).startsWith(ATTR_NEXT_PAGES_API_ROUTE_TYPE)
+    ) {
+      span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_OP, 'http.server');
+      span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+    }
+
     // We want to fork the isolation scope for incoming requests
     maybeForkIsolationScopeForRootSpan(span, spanAttributes);
 
@@ -156,16 +170,18 @@ export function init(options: VercelEdgeOptions = {}): void {
   // Span streaming bypasses event processors entirely - see the `processSegmentSpan` hook below for that path.
   client?.on('preprocessEvent', event => {
     if (event.type === 'transaction' && event.contexts?.trace?.data) {
-      enhanceMiddlewareRootSpan({
+      const mutableRootSpan = {
         attributes: event.contexts.trace.data,
         getName: () => event.transaction,
-        setName: name => {
+        setName: (name: string) => {
           event.transaction = name;
         },
-        setOp: op => {
+        setOp: (op: string) => {
           event.contexts!.trace!.op = op;
         },
-      });
+      };
+      enhanceMiddlewareRootSpan(mutableRootSpan);
+      enhanceRunHandlerRootSpan(mutableRootSpan);
     }
 
     setUrlProcessingMetadata(event);
@@ -175,16 +191,18 @@ export function init(options: VercelEdgeOptions = {}): void {
   // transaction events, so the same enhancement has to be applied here directly on the span JSON.
   client?.on('processSegmentSpan', span => {
     const attributes = (span.attributes ??= {});
-    enhanceMiddlewareRootSpan({
+    const mutableRootSpan = {
       attributes,
       getName: () => span.name,
-      setName: name => {
+      setName: (name: string) => {
         span.name = name;
       },
-      setOp: op => {
+      setOp: (op: string) => {
         attributes[SEMANTIC_ATTRIBUTE_SENTRY_OP] = op;
       },
-    });
+    };
+    enhanceMiddlewareRootSpan(mutableRootSpan);
+    enhanceRunHandlerRootSpan(mutableRootSpan);
   });
 
   client?.on('spanEnd', span => {