feat(nextjs): Mark pageloads that were served from a cached shell by chargome · Pull Request #25318 · getsentry/sentry-javascript

chargome · 2026-10-13T11:27:37Z

Builds on #25142.

A visitor of a cached page (a cacheComponents shell generated on first visit, an ISR page) gets a pageload in its own trace with no server span. That is correct, but in Sentry it looks like missing server instrumentation.

While Next.js prerenders a document, the server now writes a sentry-prerender meta tag with the sentry-trace value of the prerender instead of nothing. The client never continues it: it sets document.cached: true on the pageload and adds a cache_origin span link to the request that prerendered the page, both at span start so tracesSampler and ignoreSpans see them. Pageloads keep their own trace and sampling decision, so the two hard requirements of #25141 still hold. Pages from next build get no marker, since the SDK does not run during the build.

The attribute and the tag are named without Next.js in them on purpose: other frameworks with prerendering (Nuxt, SvelteKit, Astro, React Router) can set the same attribute. document.cached is not in @sentry/conventions yet and needs to be added there before this merges; cache_origin is already a documented sentry.link.type value and is what the cache lifecycle view in Sentry reads.

Refs JS-3886

🤖 Generated with Claude Code

Under cacheComponents the SDK stopped enabling clientTraceMetadata, because a shell that Next.js prerenders inside one request is cached and served to later visitors, and a sentry-trace tag baked into it would replay that request's trace to all of them. ISR pages had the same problem, patched on the client by removing the tags on generateStaticParams routes. Next.js computes a document's trace tags inside the "prerender route (app)" span when it prerenders and outside of it when it renders for a request, including the resume of a shell. Register a SentryPropagator subclass that hands out no trace context while that span is active, so a prerendered shell never contains a trace and any tag that reaches the browser belongs to the current request. Only swap the propagator when the Node SDK registered its own, so a foreign OpenTelemetry setup stays untouched. Enable clientTraceMetadata again under cacheComponents and remove the client-side ISR heuristic together with the isrRoutes manifest field. The guard covers ISR shells as well, including revalidate routes without generateStaticParams. Refs #24944 Refs JS-3863 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

The turbopack dev variant runs with TEST_ENV=dev-turbopack, which the development check did not match, so the tags-absent assertions ran against a dev render where the tags are fresh and kept. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Next.js computes a document's trace meta tags at the top of its prerender function, inside the span it wraps the prerender in. Recognizing that span by its attributes fails when the request is not sampled: the span is then non-recording and has no attributes, so the propagator still wrote a `sampled=0` tag into the cached shell, and every later visitor inherited the negative decision. A span nested in the prerender would have passed the check as well. Mark the prerender on the OpenTelemetry context instead, through the tracer provider the Node SDK registered, and have the propagator skip a marked context. The mark is inherited by everything that runs inside the prerender and exists whether or not the span records. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

… caller Next.js starts its spans through `startActiveSpan`, which the tracer wrapper marks on the context. A span started through `startSpan` and set on a context by the caller takes a different path, so the wrapper remembers those spans and the propagator checks the span on the context too. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…flare 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>

The ISR shells of the e2e apps come from the build, where the SDK does not run, so the tag assertions passed with or without the guard. A page with a one second window makes the server prerender it again inside a request. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>