Skip to content

feat(nextjs): Send the trace in the Server-Timing header of document responses - #26107

Merged
chargome merged 3 commits into
chargome/ref/remix-core-server-timing-utilsfrom
chargome/feat/nextjs-server-timing-header
Nov 16, 2026
Merged

chargome merged 3 commits into
chargome/ref/remix-core-server-timing-utilsfrom
chargome/feat/nextjs-server-timing-header

Conversation

@chargome

@chargome chargome commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Stacked on the core and Remix PRs; this one holds the Next.js change only.

Why: Under cacheComponents the sentry-trace meta tag arrives with the resumed part of the document, usually after the browser SDK started, so the pageload has to wait for it (#25142). A Server-Timing header reaches the browser before any HTML. The browser SDK already reads it, and Remix and Nitro already send it. On a self-hosted server Next.js flushes the headers with the first chunk, inside the request span, so the header is set in writeHead rather than when the request comes in.

Before, with the meta tag only:

sequenceDiagram
    participant B as Browser
    participant S as Next.js server
    B->>S: GET /page
    Note over S: request span starts, shell comes from cache
    S-->>B: headers + shell (no trace context)
    Note over B: SDK starts, pageload has to wait
    Note over S: dynamic part renders
    S-->>B: resumed part with sentry-trace meta tag
    Note over B: pageload starts late, fetches and errors before it are unattached
Loading

After, with the header:

sequenceDiagram
    participant B as Browser
    participant S as Next.js server
    B->>S: GET /page
    Note over S: request span starts, shell comes from cache
    Note over S: writeHead on the first chunk: Server-Timing carries the active trace
    S-->>B: headers + shell (Server-Timing: sentry-trace, baggage)
    Note over B: SDK starts, pageload continues the trace at once
    Note over S: dynamic part renders
    S-->>B: resumed part with sentry-trace meta tag
    Note over B: tag only settles page.server_rendering.type
Loading

The header is left off responses a shared cache may store, which is what Next.js sends for static and ISR app router documents. A CDN in front of the server would otherwise replay one visitor's trace and sampling decision to everyone. The check is the one the Remix 3 middleware already had, now shared as isSharedCacheable in core. Non-document responses get no header either.

Since the pageload no longer waits for the tag, page.server_rendering.type is settled after span start for a runtime shell with a dynamic part, so tracesSampler does not see it in that case. The observer stops when the pageload span ends, so a dynamic part that outlasts the pageload leaves the type unset.

Closes #24945
Refs JS-3864

@chargome chargome self-assigned this Nov 4, 2026
@chargome

chargome commented Nov 4, 2026

Copy link
Copy Markdown
Member Author

bugbot run

@linear-code

linear-code Bot commented Nov 4, 2026

Copy link
Copy Markdown

JS-3864

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

size-limit report 📦

Compared: 49b7f01 (PR test merge using develop at aa092cd)

Against: cb81d76 (develop) · base run #66242

⚠️ Baseline mismatch: 5 develop commit(s) in the PR build are missing from the baseline; 4 develop commit(s) in the baseline are missing from the PR build. Their size changes also affect this comparison. Compare commits. Rebase your PR onto the latest develop to compare against an up-to-date baseline.

Path Size % Change Change
@sentry/browser 30.1 kB - -
@sentry/browser - with treeshaking flags 28.3 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 28.2 kB - -
@sentry/browser (incl. Tracing) 52.28 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 52.29 kB - -
@sentry/browser (incl. Tracing, Profiling) 55.25 kB - -
@sentry/browser (incl. Tracing, Replay) 92.82 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 81.6 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 97.21 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 110.6 kB - -
@sentry/browser (incl. Feedback) 47.73 kB - -
@sentry/browser (incl. sendFeedback) 30.69 kB - -
@sentry/browser (incl. FeedbackAsync) 35.69 kB - -
@sentry/browser (incl. Metrics) 31.43 kB - -
@sentry/browser (incl. Logs) 31.71 kB - -
@sentry/browser (incl. Metrics & Logs) 32.37 kB - -
@sentry/react 32.11 kB - -
@sentry/react (incl. Tracing) 54.95 kB - -
@sentry/vue 38.3 kB - -
@sentry/vue (incl. Tracing) 55.24 kB - -
@sentry/svelte 30.12 kB - -
@sentry/remix (Remix 3 client bundle) 58.06 kB - -
CDN Bundle 31.87 kB - -
CDN Bundle (incl. Tracing) 52.7 kB - -
CDN Bundle (incl. Logs, Metrics) 34.67 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 55.26 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 75.7 kB - -
CDN Bundle (incl. Tracing, Replay) 90.72 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 93.33 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 96.09 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 98.69 kB - -
CDN Bundle - uncompressed 92.98 kB - -
CDN Bundle (incl. Tracing) - uncompressed 155.45 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 101.33 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 163.08 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 231.44 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 275.61 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 283.24 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 287.4 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 295.02 kB - -
@sentry/nextjs (client) 58.45 kB +0.14% +79 B 🔺
@sentry/sveltekit (client) 53.48 kB - -
@sentry/core/server 44.73 kB - -
@sentry/core/browser 14.3 kB - -
@sentry/node 150.67 kB -0.09% -126 B 🔽
@sentry/node/import (ESM hook with diagnostics-channel injection) 83.3 kB -0.01% -6 B 🔽
@sentry/node - without tracing 88.55 kB -0.02% -13 B 🔽
@sentry/node - without channel injection 139.62 kB -0.1% -128 B 🔽
@sentry/aws-serverless 98.46 kB -0.01% -9 B 🔽
@sentry/cloudflare (withSentry) - minified 205.82 kB -0.03% -59 B 🔽
@sentry/cloudflare (withSentry) 477.65 kB -0.05% -223 B 🔽
@sentry/nextjs/cloudflare (withSentry) - minified 231 kB -0.03% -59 B 🔽

View base workflow run

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Optional E2E tests

Some optional checks were not successful. They do not block the merge. 1 not successful, 9 successful. See the run.

Check Status
❌ CI: Optional E2E Tests / E2E nextjs-16-cacheComponents (cloudflare) Test (optional) Failing after 11m Details
Successful checks
Check Status
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext, bun) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-14 (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-16-tunnel (cloudflare) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (turbo) Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (cloudflare, latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-orpc Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E supabase-nextjs Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (latest) Test (optional) Successful in 3m Details

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@chargome

chargome commented Nov 4, 2026

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Comment thread packages/nextjs/src/server/index.ts Resolved
@chargome

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@chargome

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@chargome

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@chargome
chargome force-pushed the chargome/feat/nextjs-server-timing-header branch from 2091a1e to 5ad59f6 Compare November 12, 2026 15:09
@chargome
chargome changed the base branch from develop to chargome/ref/remix-core-server-timing-utils November 12, 2026 15:09
@chargome

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@chargome
chargome force-pushed the chargome/feat/nextjs-server-timing-header branch from 5ad59f6 to ef9e5f1 Compare November 12, 2026 15:30
@chargome
chargome added this pull request to stack #26327 November 12, 2026 16:15
@chargome
chargome marked this pull request as ready for review November 12, 2026 16:25
@chargome
chargome requested a review from a team November 12, 2026 16:25
@chargome
chargome requested a review from a team as a code owner November 12, 2026 16:25
@chargome
chargome removed the request for review from a team November 12, 2026 16:25
const hasCacheOrigin = !!lastMetaContent(document, CACHE_ORIGIN_META_TAG_NAME);
const isConnected = hasServerTimingTraceContext();
const setServerRenderingType = (type: string): void => {
if (hasCacheOrigin && span.isRecording()) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

M: Can we add a test where the pageload ends before the dynamic part arrives? When there are slow dynamic parts, the rendering type cannot be set as it only does this while the span is still recording.

Before, we had the PAGELOAD_TRACE_META_TAG_TIMEOUT_MS (10 seconds) timeout for the pageload (we still have that). But now the code moved into the observe* function which does not have the timeout anymore. Or is this on purpose? 🤔

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped on purpose, the observe does not wait for the pageload but only watches for a tag after the pageload started. Added a new bound so it stops when the pageload span ends.

Added a test 👍

// Only the navigation entry of a document exposes the header to the browser SDK.
function isDocument(response: HttpServerResponse, headers: HeaderObject | undefined): boolean {
const contentType = readHeader(response, headers, 'content-type');
return !contentType || contentType.startsWith('text/html');

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...so responses without a content type don't count as document.

Suggested change
return !contentType || contentType.startsWith('text/html');
return contentType?.toLowerCase().startsWith('text/html')

@chargome

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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 2e5db30. Configure here.

@chargome
chargome requested a review from s1gr1d November 16, 2026 10:24
chargome and others added 2 commits November 16, 2026 14:07
…responses

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…uire a document content type

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chargome
chargome force-pushed the chargome/feat/nextjs-server-timing-header branch from 68d3f3c to 60ae2cb Compare November 16, 2026 13:07
…ader connected the pageload

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chargome
chargome merged commit cc85e7a into develop Nov 16, 2026
114 of 115 checks passed
@chargome
chargome deleted the chargome/feat/nextjs-server-timing-header branch November 16, 2026 14:40
chargome added a commit that referenced this pull request Nov 16, 2026
…26325)

Next.js is about to send the trace in a `Server-Timing` header (#26107).
This pr just prepares the reusable functions for the consuming SDKs
(Next, Remix, Nitro) . `isSharedCacheable` takes a header reader so it
works on a fetch `Response` and on a Node `ServerResponse` alike.

Refs JS-3864

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
s1gr1d added a commit that referenced this pull request Nov 16, 2026
…26397)

## What

Next.js now writes a `sentry-render-start` meta tag (whole UNIX seconds)
next to `sentry-cache-origin`. The browser uses it to set
`page.server_rendering.age` on the pageload span, so the UI can show how
old the cached HTML was. The browser side is in `@sentry/core`, so
SvelteKit and Nuxt only need to write the tag. They follow in stacked
PRs.

## Why

The `cache_origin` link tells you which render produced a cached page,
but not how old that page is. That linked span is often not sampled or
already gone, so the browser needs the start time itself.

The tag holds the start of the linked render span. Without a recording
span, it holds the current time, which is the render start, because
Next.js computes the meta tags at the start of `prerenderToStream`. The
attribute comes from getsentry/sentry-conventions#799, which is not
merged yet, so the name is a local constant with a TODO.

A `Server-Timing` header (#26107) does not replace the tag:
shared-cacheable responses and Vercel do not send it, and it cannot hold
the render time of a cached shell.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Send trace context in the Server-Timing header for self-hosted Next.js

2 participants