fix(nextjs): Apply the prerender trace guard to withSentry on Cloudflare

ISR pages revalidate inside a request of the Worker, where `withSentry` of
`@sentry/nextjs/cloudflare` registers its own tracer provider and propagator.
The guard only covered the setup of the Node SDK, so a shell prerendered in
the Worker got that request's trace. The Next.js integration now marks
prerenders on the tracer provider `@sentry/cloudflare` registered and its
propagator skips a marked context.

Also moves the changelog entry above the contributor line and fixes a test
comment that pointed to a file of the follow-up PR.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: chargome

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- **feat(nextjs)**: Browser pageloads of apps with `cacheComponents` enabled now connect to the server request again. The SDK stopped emitting `sentry-trace` meta tags for these apps because a cached shell could replay the trace of the request that rendered it to every later visitor. The server SDK now refuses to hand out trace context while Next.js prerenders a document, so cached shells never carry a trace, and a tag that is in the document was always rendered for the current request. The guard is part of the tracer provider and propagator the SDK registers, so it does not cover apps that set up OpenTelemetry themselves. This also covers ISR pages, which no longer need the client-side meta tag removal based on `generateStaticParams`; the `isrRoutes` field of the injected route manifest is gone.
+
 Work in this release was contributed by @Philip-Nwabuwa. Thank you for your contribution!
 
 ## 11.6.0
@@ -87,8 +89,6 @@ Work in this release was contributed by @Philip-Nwabuwa. Thank you for your cont
 
 Work in this release was contributed by @zkasuran. Thank you for your contribution!
 
-- **feat(nextjs)**: Browser pageloads of apps with `cacheComponents` enabled now connect to the server request again. The SDK stopped emitting `sentry-trace` meta tags for these apps because a cached shell could replay the trace of the request that rendered it to every later visitor. The server SDK now refuses to hand out trace context while Next.js prerenders a document, so cached shells never carry a trace, and a tag that is in the document was always rendered for the current request. The guard is part of the tracer provider and propagator the SDK registers, so it does not cover apps that set up OpenTelemetry themselves. This also covers ISR pages, which no longer need the client-side meta tag removal based on `generateStaticParams`; the `isrRoutes` field of the injected route manifest is gone.
-
 ## 11.5.0
 
 ### Important Changes

packages/nextjs/src/cloudflare/index.ts

@@ -5,21 +5,22 @@ import type { CloudflareOptions } from '@sentry/cloudflare';
 import { withSentry as withSentryCloudflare } from '@sentry/cloudflare';
 import type { Integration } from '@sentry/core';
 import { applySdkMetadata, extractTraceparentData, getRootSpan, GLOBAL_OBJ, spanToJSON } from '@sentry/core';
-import {
-  registerPrepareSpanScope,
-  SentryPropagator,
-  setOpenTelemetryContextAsyncContextStrategy,
-} from '@sentry/opentelemetry';
+import { registerPrepareSpanScope, setOpenTelemetryContextAsyncContextStrategy } from '@sentry/opentelemetry';
 import { ATTR_NEXT_SPAN_TYPE } from '../common/nextSpanAttributes';
 import { isTunnelRouteSpan } from '../common/utils/dropMiddlewareTunnelRequests';
 import { dropReactControlFlowErrorsEventProcessor } from '../common/utils/dropReactControlFlowErrors';
 import { markAsyncContextOwnedByNextjsCloudflare } from '../common/utils/responseEnd';
+import {
+  getGlobalTracerProvider,
+  markPrerendersOnTracerProvider,
+  NextSentryPropagator,
+} from '../server/nextSentryPropagator';
 import { addNextjsServerSpanHooks, NEXTJS_SERVER_IGNORE_SPANS } from '../server/serverSpanHooks';
 import { nextjsUseCacheIntegration } from '../server/useCacheInstrumentation';
 
 export * from '@sentry/cloudflare';
 
-class NextjsCloudflarePropagator extends SentryPropagator {
+class NextjsCloudflarePropagator extends NextSentryPropagator {
   /** @inheritDoc */
   public extract(ctx: Context, carrier: unknown, getter: TextMapGetter): Context {
     // Next.js extracts the request headers again from the root context when it misses its router server context, e.g.
@@ -43,6 +44,9 @@ const nextjsIntegration = (): Integration => ({
   name: 'Nextjs',
   setup: client => {
     if ((client.getOptions() as CloudflareOptions).enableOpenTelemetrySetup) {
+      // ISR pages revalidate inside a request of the Worker, so the prerender guard has to cover the tracer
+      // provider `@sentry/cloudflare` registered as well.
+      markPrerendersOnTracerProvider(getGlobalTracerProvider());
       propagation.setGlobalPropagator(new NextjsCloudflarePropagator());
     }
     client.getOptions().release ??= (GLOBAL_OBJ as { _sentryRelease?: string })._sentryRelease;

packages/nextjs/src/server/index.ts

@@ -184,8 +184,9 @@ export function init(options: NodeOptions): NodeClient | undefined {
   }
 
   // Next.js reads the trace meta tags of a document through the global propagator. Only the setup the
-  // Node SDK owns gets the Next.js-aware one; another OpenTelemetry setup (for example `@vercel/otel`)
-  // keeps its own tracer provider and propagator.
+  // Node SDK owns gets the Next.js-aware one here; `withSentry` of `@sentry/nextjs/cloudflare` applies it
+  // to its own setup, and another OpenTelemetry setup (for example `@vercel/otel`) keeps its own tracer
+  // provider and propagator.
   if (client?.traceProvider) {
     registerNextSentryPropagator(client.traceProvider);
   }

packages/nextjs/src/server/nextSentryPropagator.ts

@@ -82,11 +82,18 @@ export class NextSentryPropagator extends SentryPropagator {
   }
 }
 
+const markedProviders = new WeakSet<TracerProvider>();
+
 /**
- * Makes the tracer provider the Node SDK registered mark prerenders on the OpenTelemetry context, and
- * replaces the propagator it registered with one that hands out nothing on a marked context.
+ * Makes a tracer provider mark prerenders on the OpenTelemetry context, by wrapping the tracers it hands
+ * out. Safe to call repeatedly with the same provider, which the per-request `init` on Cloudflare does.
  */
-export function registerNextSentryPropagator(provider: TracerProvider): void {
+export function markPrerendersOnTracerProvider(provider: TracerProvider): void {
+  if (markedProviders.has(provider)) {
+    return;
+  }
+  markedProviders.add(provider);
+
   const wrappedTracers = new WeakMap<Tracer, Tracer>();
   const getTracer = provider.getTracer.bind(provider);
   provider.getTracer = (...args) => {
@@ -98,6 +105,22 @@ export function registerNextSentryPropagator(provider: TracerProvider): void {
     }
     return wrapped;
   };
+}
+
+/**
+ * The tracer provider behind the global OpenTelemetry API, which is a proxy around the registered one.
+ */
+export function getGlobalTracerProvider(): TracerProvider {
+  const provider = trace.getTracerProvider();
+  return 'getDelegate' in provider ? (provider as { getDelegate(): TracerProvider }).getDelegate() : provider;
+}
+
+/**
+ * Makes the tracer provider the Node SDK registered mark prerenders on the OpenTelemetry context, and
+ * replaces the propagator it registered with one that hands out nothing on a marked context.
+ */
+export function registerNextSentryPropagator(provider: TracerProvider): void {
+  markPrerendersOnTracerProvider(provider);
 
   // The OpenTelemetry API refuses a second global propagator, so the one from the Node SDK setup has
   // to be unregistered first.

packages/nextjs/test/cloudflare/withSentry.test.ts

@@ -16,7 +16,7 @@ import {
 } from '@sentry/core';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { withSentry } from '../../src/cloudflare';
-import { ATTR_NEXT_SPAN_TYPE } from '../../src/common/nextSpanAttributes';
+import { ATTR_NEXT_SPAN_NAME, ATTR_NEXT_SPAN_TYPE } from '../../src/common/nextSpanAttributes';
 import { init as initEdge } from '../../src/edge';
 import { init as initServer } from '../../src/server';
 import { NEXTJS_SERVER_IGNORE_SPANS } from '../../src/server/serverSpanHooks';
@@ -257,6 +257,39 @@ describe('withSentry', () => {
     expect(carrier['sentry-trace']).toBe(`${activeSpan?.spanContext().traceId}-${activeSpan?.spanContext().spanId}-1`);
   });
 
+  it('injects nothing while Next.js prerenders a page in a request', async () => {
+    const carrier: Record<string, string> = {};
+    const requestCarrier: Record<string, string> = {};
+    const handler = withSentry(() => ({ dsn: DSN, tracesSampleRate: 1 }), {
+      fetch: () => {
+        trace.getTracer('next.js').startActiveSpan(
+          'prerender route (app) /isr',
+          {
+            attributes: {
+              [ATTR_NEXT_SPAN_TYPE]: 'AppRender.getBodyResult',
+              [ATTR_NEXT_SPAN_NAME]: 'prerender route (app) /isr',
+            },
+          },
+          span => {
+            propagation.inject(context.active(), carrier);
+            span.end();
+          },
+        );
+        propagation.inject(context.active(), requestCarrier);
+        return new Response('ok');
+      },
+    });
+
+    await handler.fetch?.(new Request('https://example.com/') as never, {}, {
+      waitUntil: vi.fn(),
+      passThroughOnException: vi.fn(),
+      props: {},
+    } as never);
+
+    expect(carrier).toEqual({});
+    expect(requestCarrier['sentry-trace']).toMatch(/^[0-9a-f]{32}-[0-9a-f]{16}-1$/);
+  });
+
   it('does not set the global propagator when the callback turns off the OpenTelemetry setup', async () => {
     const setGlobalPropagator = vi.spyOn(propagation, 'setGlobalPropagator');
     const handler = withSentry(() => ({ dsn: DSN, enableOpenTelemetrySetup: false }), {

packages/nextjs/test/config/maybeSetClientTraceMetadataOption.test.ts

@@ -16,7 +16,7 @@ describe('maybeSetClientTraceMetadataOption', () => {
   });
 
   it('enables trace meta tags when Cache Components is enabled', () => {
-    // The client decides per tag whether it may be continued, see `cacheComponentsTraceMetaTags.ts`.
+    // The server withholds the tags while it prerenders, see `nextSentryPropagator.ts`.
     const config: NextConfigObject = { cacheComponents: true };
     maybeSetClientTraceMetadataOption(config, '16.0.0');
     expect(config.experimental?.clientTraceMetadata).toEqual(['baggage', 'sentry-trace']);