feat(nextjs): Export the prerender guard for custom OpenTelemetry setups

An app that sets up OpenTelemetry itself registers its own propagator, which
writes the trace meta tags of a prerendered shell. It can now register
`NextSentryPropagator` and call `markPrerendersOnTracerProvider` with its
tracer provider to get the same guard as the SDK's own setup.

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

Author: chargome

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 - **feat(nextjs): Never emit trace meta tags from a prerender ([#25141](https://github.com/getsentry/sentry-javascript/pull/25141))**
 
-  Apps with `cacheComponents` enabled get the `sentry-trace` and `baggage` meta tags again, so a pageload joins the trace of the server request that rendered the page. The server SDK no longer writes these tags while Next.js prerenders a page, so a cached shell never carries the trace of another visitor. This also covers ISR pages.
+  Apps with `cacheComponents` enabled get the `sentry-trace` and `baggage` meta tags again, so a pageload joins the trace of the server request that rendered the page. The server SDK no longer writes these tags while Next.js prerenders a page, so a cached shell never carries the trace of another visitor. This also covers ISR pages. Apps that set up OpenTelemetry themselves register `NextSentryPropagator` instead of `SentryPropagator` and call `markPrerendersOnTracerProvider` with their tracer provider to get the same behaviour.
 
 Work in this release was contributed by @Philip-Nwabuwa and @4ktLuffy. Thank you for your contributions!
 

packages/nextjs/src/server/index.ts

@@ -239,3 +239,8 @@ export function init(options: NodeOptions): NodeClient | undefined {
 export * from '../common';
 
 export { wrapApiHandlerWithSentry } from '../common/pages-router-instrumentation/wrapApiHandlerWithSentry';
+
+// For apps that set up OpenTelemetry themselves (`enableOpenTelemetrySetup: false`), which otherwise
+// write the trace meta tags of a prerendered shell with the propagator they registered.
+export { NextSentryPropagator } from './nextSentryPropagator';
+export { markPrerendersOnTracerProvider } from './prerenderContext';

packages/nextjs/src/server/nextSentryPropagator.ts

@@ -7,6 +7,10 @@ import { isPrerenderContext, markPrerendersOnTracerProvider } from './prerenderC
  * A `SentryPropagator` that does not hand out the trace meta tags of a document while Next.js
  * prerenders it. Trace context baked into a prerendered shell would be replayed to every visitor the
  * shell is served to, so the browser could continue a trace that never handled its request.
+ *
+ * The SDK registers it when it sets up OpenTelemetry. An app that sets up OpenTelemetry itself
+ * registers it in place of `SentryPropagator` and calls `markPrerendersOnTracerProvider` with its
+ * tracer provider, which this propagator relies on to recognize a prerender.
  */
 export class NextSentryPropagator extends SentryPropagator {
   /** @inheritDoc */

packages/nextjs/src/server/prerenderContext.ts

@@ -74,8 +74,10 @@ function wrapTracer(tracer: Tracer): Tracer {
 const markedProviders = new WeakSet<TracerProvider>();
 
 /**
- * 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.
+ * Makes a tracer provider mark prerenders of Next.js on the OpenTelemetry context, by wrapping the
+ * tracers it hands out. `NextSentryPropagator` relies on the mark. The SDK calls this for the provider it
+ * registers; an app that sets up OpenTelemetry itself calls it with its own provider. Safe to call
+ * repeatedly with the same provider, which the per-request `init` on Cloudflare does.
  */
 export function markPrerendersOnTracerProvider(provider: TracerProvider): void {
   if (markedProviders.has(provider)) {