Skip to content

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

Draft
chargome wants to merge 2 commits into
developfrom
chargome/feat/nextjs-server-timing-header
Draft

chargome wants to merge 2 commits into
developfrom
chargome/feat/nextjs-server-timing-header

Conversation

@chargome

@chargome chargome commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Why: A sentry-trace meta tag only reaches the browser with the HTML that carries it. Under cacheComponents that is the resumed part, which usually arrives after the SDK started, so the pageload has to wait for it (#25142). A Server-Timing header arrives 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 when writeHead runs rather than when the request comes in.

The header is left off responses a shared cache may store (s-maxage, public, max-age without private/no-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. Next's own caches never replay it, they only store headers the render set. The pages router sends no Cache-Control for a static page, so there the header goes out in production too. It is also left off responses that are not documents, since only the navigation entry exposes it.

With the header, the pageload no longer waits for the tag, so page.server_rendering.type is not known at span start for a runtime shell with a dynamic part. It is settled when the tag arrives or the document finishes parsing, so tracesSampler does not see it in that case. The link to the prerender is still set at start.

The formatting moved from Remix to getTraceServerTimingHeader in core; Nitro keeps its own two append calls for now.

How to review: packages/nextjs/src/server/serverTimingHeader.ts is the feature. traceMetaTags.ts on the client only changes what happens after the pageload started (observeLateTraceMetaTag). The e2e changes show which pages get the header: /pageload-tracing, /runtime-shell and /slow-hole do, /static-shell and the [id] shells do not.

Unsure about: The Cache-Control gate is a heuristic, and a response without any Cache-Control (pages router) gets the header. Vercel is out of scope (JS-3866).

Closes #24945
Refs JS-3864

🤖 Generated with Claude Code

…responses

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@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: 38759ce (PR test merge using develop at f2ee787)

Against: f2ee787 (develop) · base run #65001

✅ Baseline matches: this diff contains only this PR's changes.

Path Size % Change Change
@sentry/browser 30.4 kB - -
@sentry/browser - with treeshaking flags 28.54 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 28.43 kB - -
@sentry/browser (incl. Tracing) 52.72 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 52.72 kB - -
@sentry/browser (incl. Tracing, Profiling) 55.69 kB - -
@sentry/browser (incl. Tracing, Replay) 93.02 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 81.61 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 97.76 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 110.75 kB - -
@sentry/browser (incl. Feedback) 47.98 kB - -
@sentry/browser (incl. sendFeedback) 35.5 kB - -
@sentry/browser (incl. FeedbackAsync) 40.61 kB - -
@sentry/browser (incl. Metrics) 31.44 kB - -
@sentry/browser (incl. Logs) 31.73 kB - -
@sentry/browser (incl. Metrics & Logs) 32.45 kB - -
@sentry/react 32.29 kB - -
@sentry/react (incl. Tracing) 55.09 kB - -
@sentry/vue 38.67 kB - -
@sentry/vue (incl. Tracing) 55.73 kB - -
@sentry/svelte 30.43 kB - -
@sentry/remix (Remix 3 client bundle) 57.8 kB - -
CDN Bundle 32.19 kB - -
CDN Bundle (incl. Tracing) 53.24 kB - -
CDN Bundle (incl. Logs, Metrics) 34.47 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 55.19 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 75.88 kB - -
CDN Bundle (incl. Tracing, Replay) 91.46 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 93.39 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 97.56 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 99.56 kB - -
CDN Bundle - uncompressed 94.67 kB - -
CDN Bundle (incl. Tracing) - uncompressed 157.63 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 101.14 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 163.37 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 232.71 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 279.32 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 285.05 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 293.03 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 298.74 kB - -
@sentry/nextjs (client) 58.1 kB +0.1% +57 B 🔺
@sentry/sveltekit (client) 53.23 kB - -
@sentry/core/server 44.25 kB - -
@sentry/core/browser 13.93 kB - -
@sentry/node 155.71 kB +0.02% +19 B 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 82.26 kB -0.01% -1 B 🔽
@sentry/node - without tracing 96.89 kB +0.02% +15 B 🔺
@sentry/node - without channel injection 136.04 kB +0.02% +21 B 🔺
@sentry/aws-serverless 105.11 kB +0.02% +20 B 🔺
@sentry/cloudflare (withSentry) - minified 200.67 kB - -
@sentry/cloudflare (withSentry) 499.05 kB - -
@sentry/nextjs/cloudflare (withSentry) - minified 221.22 kB - -

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. 2 not successful, 53 successful. See the run.

Check Status
❌ CI: Optional E2E Tests / E2E cloudflare-pi-durable (latest) Test (optional) Failing after 41s Details
❌ CI: Optional E2E Tests / E2E node-flue (latest) Test (optional) Failing after 50s Details
Successful checks
Check Status
✅ CI: Optional E2E Tests / E2E astro-7-static Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E solidstart-2 Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E cloudflare-think (ai v6) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E deno (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E astro-7 Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E debug-id-sourcemaps Test (optional) Successful in 57s Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps Test (optional) Successful in 54s Details
✅ CI: Optional E2E Tests / E2E nestjs-12 (latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E node-pi-durable (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E cloudflare-mastra Test (optional) Successful in 48s Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries (latest) Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E node-fastify-6 Test (optional) Successful in 44s Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries (cloudflare) Test (optional) Successful in 47s Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (deno) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (latest) Test (optional) Successful in 4m Details
✅ CI: Optional E2E Tests / E2E node-fastify-6 (tracer provider) Test (optional) Successful in 47s Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (cloudflare, latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E cloudflare-workers-send-to-sentry Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E node-eve (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5 (tunnel-dev) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-eve (orchestrion) Test (optional) Successful in 9m Details
✅ CI: Optional E2E Tests / E2E cloudflare-pi-durable Test (optional) Successful in 54s Details
✅ CI: Optional E2E Tests / E2E cloudflare-think Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-14 (latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps (static / nuxt generate) Test (optional) Successful in 42s Details
✅ CI: Optional E2E Tests / E2E node-flue Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E node-express-send-to-sentry-static Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E cloudflare-agent Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-orpc Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-express-mcp-v2 Test (optional) Successful in 46s Details
✅ CI: Optional E2E Tests / E2E node-mastra (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-pi-durable Test (optional) Successful in 50s Details
✅ CI: Optional E2E Tests / E2E node-express-mcp-v1 Test (optional) Successful in 53s Details
✅ CI: Optional E2E Tests / E2E node-openai-decisions Test (optional) Successful in 55s Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext, bun) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E cloudflare-flue-send-to-sentry Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E supabase-nextjs Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E node-openai-decisions (latest) Test (optional) Successful in 42s Details
✅ CI: Optional E2E Tests / E2E node-mastra Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-express-send-to-sentry Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-eve Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react (latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react-sourcemaps Test (optional) Successful in 45s Details
✅ CI: Optional E2E Tests / E2E react-router-7-framework-instrumentation Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E vue-3 (no Options API) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react-cloudflare Test (optional) Successful in 52s Details
✅ CI: Optional E2E Tests / E2E react-send-to-sentry Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E nextjs-16-tunnel (cloudflare) Test (optional) Successful in 9m Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (turbo) Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E nuxt-5 Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps (client source maps kept) Test (optional) Successful in 47s 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.

… is sent

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@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.

✅ 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 14ccacd. Configure here.

import { distDirRewriteFramesIntegration } from './distDirRewriteFramesIntegration';
import { registerNextSentryPropagator } from './nextSentryPropagator';
import { addNextjsServerSpanHooks, NEXTJS_SERVER_IGNORE_SPANS } from './serverSpanHooks';
import { addServerTimingTraceHeader } from './serverTimingHeader';

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Server-Timing trace header can ship on CDN-cacheable responses

isSharedCacheable() in serverTimingHeader.ts only inspects Cache-Control, so responses with CDN cache headers (CDN-Cache-Control, Vercel-CDN-Cache-Control, etc.) or max-age=0, stale-while-revalidate still get a per-request sentry-trace/baggage Server-Timing value a shared cache can replay to other users. Align it with the Remix middleware checks.

Evidence
  • addServerTimingTraceHeader() is registered from this import during Next.js server init and sets Server-Timing in the writeHead hook via setServerTimingTraceHeader().
  • Guard is only isSharedCacheable() reading cache-control; private/no-store force false even when a CDN-specific lifetime header allows shared storage.
  • max-age=0 with stale-while-revalidate also fails the positive max-age=(?!0\b) check, so the trace header is still attached.
  • Remix packages/remix/src/v3/server/middleware.ts treats those same CDN headers and stale directives as shared-cacheable and has tests that omit the trace in those cases.

Identified by Warden · security-review · 3S7-667

This branch has not been deployed

No deployments
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

1 participant