Repository navigation
feat(nextjs): Never emit trace meta tags from a prerender - #25141
Merged
Merged
Conversation
Member
Author
|
bugbot run |
1 similar comment
Member
Author
|
bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Member
Author
|
bugbot run |
chargome
force-pushed
the
chargome/feat/nextjs-prerender-trace-guard
branch
from
October 8, 2026 07:58
33c6ae1 to
feab86e
Compare
Member
Author
|
bugbot run |
Member
Author
|
bugbot run |
Contributor
size-limit report 📦
|
chargome
force-pushed
the
chargome/feat/nextjs-prerender-trace-guard
branch
from
October 9, 2026 14:24
cf27bae to
576a529
Compare
Member
Author
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 576a529. Configure here.
chargome
marked this pull request as ready for review
October 12, 2026 09:40
chargome
requested review from
nicohrubec and
s1gr1d
and removed request for
a team and
nicohrubec
October 12, 2026 09:40
chargome
force-pushed
the
chargome/feat/nextjs-prerender-trace-guard
branch
from
October 12, 2026 12:01
40f56e9 to
c63eae2
Compare
s1gr1d
reviewed
Oct 12, 2026
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>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…r file Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
vinext renders ISR pages for every request, so the trace tags are fresh there and kept, like on the dev server. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
chargome
force-pushed
the
chargome/feat/nextjs-prerender-trace-guard
branch
from
October 13, 2026 08:49
0921a7d to
6651191
Compare
s1gr1d
approved these changes
Oct 13, 2026
Comment on lines
+245
to
+246
| export { NextSentryPropagator } from './nextSentryPropagator'; | ||
| export { markPrerendersOnTracerProvider } from './prerenderContext'; |
Member
There was a problem hiding this comment.
Maybe you could mention those two new public exports in the changelog.
Member
Author
There was a problem hiding this comment.
I left them out on purpose as it is a very niche case, but I will move that to docs for sure
…js-prerender-trace-guard # Conflicts: # CHANGELOG.md
…tups in the changelog
s1gr1d
added a commit
that referenced
this pull request
Oct 20, 2026
… the pageload (#25142) Builds on #25141. When a document resumes a prerendered shell, its `sentry-trace` tag sits at the start of the resumed part, which arrives after the SDK has started. In a local demo six of seven visits found no tag at init, so the pageload could only link the server trace instead of joining it. The app router pageload now continues whatever tag is in the document, last one wins. In apps with `cacheComponents` enabled, if there is no tag, no `Server-Timing` trace and the document is still streaming, it waits for the tag before creating the pageload span. Other apps keep the immediate start: without `cacheComponents` a tag is either in `<head>` from the start or never comes, so waiting only held the pageload back. The wait ends at `DOMContentLoaded` or after 10 seconds. The span still starts at the time origin and gets its children from the performance timeline, so it looks the same as before, only inside the server's trace. No tag by the end of parsing means a fresh trace, which is the fully static case. A client-side navigation during the wait starts the pageload with a fresh trace first, so the navigation ends it like any pageload it interrupts, as today. Started later, the pageload would end the navigation span instead. The pageload keeps the URL the document was loaded with, even if the navigation already changed it. Waiting was chosen over moving a started span to another trace. That needs core changes and does not work with span streaming once children are flushed. The cost: fetches, errors and clicks between SDK start and the resumed part are not attached to the pageload. The `Server-Timing` follow-ups (JS-3864, JS-3866) remove that window where the header can be set. <img width="2240" height="1904" alt="figure-ppr" src="https://github.com/user-attachments/assets/c6049dff-1ceb-4a09-9467-b2436648cf6c" /> Fixes #24944 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: s1gr1d <32902192+s1gr1d@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Under
cacheComponentsthe SDK did not enableexperimental.clientTraceMetadata(#21141). A shell that Next.js prerenders during one request is cached and served to later visitors, and asentry-tracetag inside it would attach all of them to that one request. ISR pages had the same problem, worked around on the client by removing the tags on routes withgenerateStaticParams(#18192).Next.js computes the trace tags of a document inside the
prerender route (app)span when it prerenders, and outside of it when it renders for a request, including when it resumes a shell. The server SDK now marks that span on the OpenTelemetry context, and its propagator hands out nothing on a marked context. A prerendered shell never contains a trace, so any tag that reaches the browser belongs to the current request. The mark sits on the context rather than the span because an unsampled request makes the span non-recording, with no attributes to recognize it by, and asampled=0tag in the shell would drop every later pageload. Checked in Next.js 15.0 through 16.4.With that,
clientTraceMetadatais enabled again undercacheComponents, and the client-side ISR workaround and theisrRoutesmanifest field are removed. The guard covers ISR shells too, includingrevalidateroutes the file scan never found.The guard is applied to the tracer provider and propagator the Node SDK registers, and
withSentryof@sentry/nextjs/cloudflareapplies it to its own setup, since ISR pages revalidate inside a request of the Worker. A custom OpenTelemetry setup does not get it automatically. If it registersSentryPropagator, it can register the exportedNextSentryPropagatorinstead and pass its tracer provider tomarkPrerendersOnTracerProvider. Setups with only the OpenTelemetry W3C propagators, which includes@vercel/otelby default, write nosentry-tracetag, so nothing changes for them. The docs follow in sentry-docs.An ISR page with
revalidate = 1makes the e2e suite exercise the guard at runtime; the other ISR shells come from the build, where the SDK does not run.On its own this PR keeps the current client behaviour: tags in
<head>are continued and are now always fresh. The tag of a resumed shell arrives with the resumed part, which the client only reads in #25142.Refs #24944, see #24298