@@ -8,6 +8,10 @@
 
   Pageloads of apps with `cacheComponents` enabled are connected to their server request again. Pages that Next.js prerenders no longer carry trace information, so a cached page can no longer connect visitors to a request that was not theirs. This also applies to ISR pages. The pageload waits for the trace information when it arrives with the part of the page that streams in after a cached shell.
 
+- **feat(nextjs): Mark pageloads that were served from a cached shell**
+
+  A pageload whose document is a shell that Next.js prerendered at runtime, for example an ISR page or a `cacheComponents` page generated on first visit, now carries the `sentry.nextjs.cached_shell` attribute and a `cache_origin` span link to the request that generated the shell. That tells apart "nothing ran on the server for this visit" from missing server instrumentation. The link is never continued as a parent, so pageloads keep their own traces and sampling decisions.
+
 ## 11.7.0
 
 ### Important Changes
 
@@ -7,7 +7,8 @@ const APP = 'nextjs-16-cacheComponents';
 // The server only writes `sentry-trace` meta tags for a render that happened for the current request,
 // never while it prerenders a shell. So a tag in the document can always be continued; the only
 // question is when it arrives. The resumed part of a prerendered shell arrives after the SDK started,
-// which the pageload instrumentation waits for.
+// which the pageload instrumentation waits for. A shell prerendered at runtime carries a `sentry-shell`
+// marker instead, which marks the pageload as served from a cached shell and links the prerender.
 
 test('connects the pageload trace to the runtime server request', async ({ page }) => {
   // The shell is prerendered, but the page's dynamic part (`DynamicContent` awaits `headers()`)
@@ -30,7 +31,6 @@ test('connects the pageload trace to the runtime server request', async ({ page
 
   expect(serverTx.contexts?.trace?.trace_id).toBeTruthy();
   expect(pageloadTx.contexts?.trace?.trace_id).toBe(serverTx.contexts?.trace?.trace_id);
-  expect(pageloadTx.contexts?.trace?.links).toBeUndefined();
 });
 
 test('connects the pageload trace to a blocking render', async ({ page }) => {
@@ -58,10 +58,11 @@ test('does not share a trace between visitors of a shell generated at request ti
   test.skip(process.env.TEST_ENV !== 'production', 'Shells are only cached in production builds');
 
   // `[id]` only lists `test` in `generateStaticParams`, so the first visit prerenders and caches the
-  // shell for this id. The prerender writes no trace tag, so every visitor starts a fresh trace.
+  // shell for this id. The prerender writes no trace tag, only a `sentry-shell` marker with its own
+  // trace, so every visitor starts a fresh trace that links the prerender and is marked as a cached shell.
   const id = `shell-${Date.now()}`;
 
-  const visit = async (): Promise<{ traceId: string | undefined; links: unknown }> => {
+  const visit = async (): Promise<{ traceId: string | undefined; links: unknown; cachedShell: unknown }> => {
     const context = await browser.newContext();
     const page: Page = await context.newPage();
 
@@ -75,11 +76,16 @@ test('does not share a trace between visitors of a shell generated at request ti
     await page.goto(`/${id}`);
     await expect(page.locator('#result')).toHaveText(`Hello, ${id}!`);
     expect(await page.locator('meta[name="sentry-trace"]').count()).toBe(0);
+    expect(await page.locator('meta[name="sentry-shell"]').count()).toBe(1);
 
     const pageloadTx = await pageloadTxPromise;
     await context.close();
 
-    return { traceId: pageloadTx.contexts?.trace?.trace_id, links: pageloadTx.contexts?.trace?.links };
+    return {
+      traceId: pageloadTx.contexts?.trace?.trace_id,
+      links: pageloadTx.contexts?.trace?.links,
+      cachedShell: pageloadTx.contexts?.trace?.data?.['sentry.nextjs.cached_shell'],
+    };
   };
 
   const first = await visit();
@@ -88,8 +94,17 @@ test('does not share a trace between visitors of a shell generated at request ti
   expect(first.traceId).toBeTruthy();
   expect(second.traceId).toBeTruthy();
   expect(second.traceId).not.toBe(first.traceId);
-  expect(first.links).toBeUndefined();
-  expect(second.links).toBeUndefined();
+  expect(first.cachedShell).toBe(true);
+  expect(second.cachedShell).toBe(true);
+
+  // Both link the one request that prerendered the shell, which is neither visitor's own trace.
+  const linkOf = (links: unknown): { trace_id: string; attributes?: Record<string, unknown> } => {
+    const link = (links as Array<{ trace_id: string; attributes?: Record<string, unknown> }>)[0];
+    expect(link?.attributes?.['sentry.link.type']).toBe('cache_origin');
+    return link!;
+  };
+  expect(linkOf(first.links).trace_id).toBe(linkOf(second.links).trace_id);
+  expect(linkOf(second.links).trace_id).not.toBe(second.traceId);
 });
 
 test('starts a fresh trace on a fully static page', async ({ page }) => {
@@ -105,8 +120,10 @@ test('starts a fresh trace on a fully static page', async ({ page }) => {
 
   const pageloadTx = await pageloadTxPromise;
 
-  // A build-time shell carries no trace context at all.
+  // A build-time shell carries no trace context and no marker, the SDK does not run during the build.
   expect(await page.locator('meta[name="sentry-trace"]').count()).toBe(0);
+  expect(await page.locator('meta[name="sentry-shell"]').count()).toBe(0);
   expect(pageloadTx.contexts?.trace?.trace_id).toBeTruthy();
   expect(pageloadTx.contexts?.trace?.links).toBeUndefined();
+  expect(pageloadTx.contexts?.trace?.data?.['sentry.nextjs.cached_shell']).toBeUndefined();
 });
@@ -7,7 +7,8 @@ const APP = 'nextjs-16-streaming-cacheComponents';
 // The server only writes `sentry-trace` meta tags for a render that happened for the current request,
 // never while it prerenders a shell. So a tag in the document can always be continued; the only
 // question is when it arrives. The resumed part of a prerendered shell arrives after the SDK started,
-// which the pageload instrumentation waits for.
+// which the pageload instrumentation waits for. A shell prerendered at runtime carries a `sentry-shell`
+// marker instead, which marks the pageload as served from a cached shell and links the prerender.
 
 test('connects the pageload trace to the runtime server request', async ({ page }) => {
   // The shell is prerendered, but the page's dynamic part (`DynamicContent` awaits `headers()`)
@@ -28,7 +29,6 @@ test('connects the pageload trace to the runtime server request', async ({ page
 
   expect(serverSpan.trace_id).toBeTruthy();
   expect(pageloadSpan.trace_id).toBe(serverSpan.trace_id);
-  expect(pageloadSpan.links).toBeUndefined();
 });
 
 test('connects the pageload trace to a blocking render', async ({ page }) => {
@@ -56,10 +56,11 @@ test('does not share a trace between visitors of a shell generated at request ti
   test.skip(process.env.TEST_ENV !== 'production', 'Shells are only cached in production builds');
 
   // `[id]` only lists `test` in `generateStaticParams`, so the first visit prerenders and caches the
-  // shell for this id. The prerender writes no trace tag, so every visitor starts a fresh trace.
+  // shell for this id. The prerender writes no trace tag, only a `sentry-shell` marker with its own
+  // trace, so every visitor starts a fresh trace that links the prerender and is marked as a cached shell.
   const id = `shell-${Date.now()}`;
 
-  const visit = async (): Promise<{ traceId: string | undefined; links: unknown }> => {
+  const visit = async (): Promise<{ traceId: string | undefined; links: unknown; cachedShell: unknown }> => {
     const context = await browser.newContext();
     const page: Page = await context.newPage();
 
@@ -70,11 +71,16 @@ test('does not share a trace between visitors of a shell generated at request ti
     await page.goto(`/${id}`);
     await expect(page.locator('#result')).toHaveText(`Hello, ${id}!`);
     expect(await page.locator('meta[name="sentry-trace"]').count()).toBe(0);
+    expect(await page.locator('meta[name="sentry-shell"]').count()).toBe(1);
 
     const pageloadSpan = await pageloadSpanPromise;
     await context.close();
 
-    return { traceId: pageloadSpan.trace_id, links: pageloadSpan.links };
+    return {
+      traceId: pageloadSpan.trace_id,
+      links: pageloadSpan.links,
+      cachedShell: pageloadSpan.attributes['sentry.nextjs.cached_shell']?.value,
+    };
   };
 
   const first = await visit();
@@ -83,8 +89,17 @@ test('does not share a trace between visitors of a shell generated at request ti
   expect(first.traceId).toBeTruthy();
   expect(second.traceId).toBeTruthy();
   expect(second.traceId).not.toBe(first.traceId);
-  expect(first.links).toBeUndefined();
-  expect(second.links).toBeUndefined();
+  expect(first.cachedShell).toBe(true);
+  expect(second.cachedShell).toBe(true);
+
+  // Both link the one request that prerendered the shell, which is neither visitor's own trace.
+  const linkOf = (links: unknown): { trace_id: string; attributes?: Record<string, { value: unknown }> } => {
+    const link = (links as Array<{ trace_id: string; attributes?: Record<string, { value: unknown }> }>)[0];
+    expect(link?.attributes?.['sentry.link.type']?.value).toBe('cache_origin');
+    return link!;
+  };
+  expect(linkOf(first.links).trace_id).toBe(linkOf(second.links).trace_id);
+  expect(linkOf(second.links).trace_id).not.toBe(second.traceId);
 });
 
 test('starts a fresh trace on a fully static page', async ({ page }) => {
@@ -100,8 +115,10 @@ test('starts a fresh trace on a fully static page', async ({ page }) => {
 
   const pageloadSpan = await pageloadSpanPromise;
 
-  // A build-time shell carries no trace context at all.
+  // A build-time shell carries no trace context and no marker, the SDK does not run during the build.
   expect(await page.locator('meta[name="sentry-trace"]').count()).toBe(0);
+  expect(await page.locator('meta[name="sentry-shell"]').count()).toBe(0);
   expect(pageloadSpan.trace_id).toBeTruthy();
   expect(pageloadSpan.links).toBeUndefined();
+  expect(pageloadSpan.attributes['sentry.nextjs.cached_shell']).toBeUndefined();
 });
@@ -1,6 +1,7 @@
+import { SENTRY_LINK_TYPE } from '@sentry/conventions/attributes';
 import type { Span } from '@sentry/core';
-import { extractTraceparentData } from '@sentry/core';
-import { GLOBAL_OBJ } from '@sentry/core';
+import { extractTraceparentData, GLOBAL_OBJ } from '@sentry/core';
+import { SHELL_META_TAG_NAME } from '../../common/traceMetaTags';
 import { WINDOW } from '@sentry/react';
 
 // `@opentelemetry/api` `TraceFlags`, inlined because core does not export its copies.
@@ -12,6 +13,9 @@ export interface TraceMetaTagValues {
   baggage: string | undefined;
 }
 
+/** Set on a pageload whose document is a shell that Next.js prerendered and served from its cache. */
+export const CACHED_SHELL_ATTRIBUTE = 'sentry.nextjs.cached_shell';
+
 function getDocument(): Document | undefined {
   return WINDOW.document;
 }
@@ -132,7 +136,7 @@ export function waitForTraceMetaTag(
  * Adds a span link to the span described by a `sentry-trace` value. Used when the tag arrives after
  * the pageload span exists, which can only link the server request, not continue it.
  */
-export function addTraceMetaTagLink(span: Span, { sentryTrace }: TraceMetaTagValues): void {
+export function addTraceMetaTagLink(span: Span, { sentryTrace }: TraceMetaTagValues, linkType?: string): void {
   const traceparent = extractTraceparentData(sentryTrace);
   if (!traceparent?.traceId || !traceparent.parentSpanId) {
     return;
@@ -144,5 +148,22 @@ export function addTraceMetaTagLink(span: Span, { sentryTrace }: TraceMetaTagVal
       spanId: traceparent.parentSpanId,
       traceFlags: traceparent.parentSampled ? TRACE_FLAG_SAMPLED : TRACE_FLAG_NONE,
     },
+    ...(linkType && { attributes: { [SENTRY_LINK_TYPE]: linkType } }),
   });
 }
+
+/** Reads the marker the server writes into a shell while it prerenders it, see `nextSentryPropagator.ts`. */
+export function readShellMarker(): string | undefined {
+  const document = getDocument();
+  return document && lastMetaContent(document, SHELL_META_TAG_NAME);
+}
+
+/**
+ * Marks a pageload whose document is a cached shell and links the request that prerendered the shell.
+ * The marker is never continued: the shell is served to every later visitor, and the request behind it
+ * handled none of their visits.
+ */
+export function markCachedShell(span: Span, marker: string): void {
+  span.setAttribute(CACHED_SHELL_ATTRIBUTE, true);
+  addTraceMetaTagLink(span, { sentryTrace: marker, baggage: undefined }, 'cache_origin');
+}
@@ -1,3 +1,4 @@
+import { SHELL_META_TAG_NAME } from '../../common/traceMetaTags';
 import { debug, isMatchingPattern, parseSemver } from '@sentry/core';
 import { getSentryRelease } from '@sentry/node';
 import * as fs from 'fs';
@@ -148,6 +149,7 @@ export function maybeSetClientTraceMetadataOption(
       incomingUserNextConfigObject.experimental.clientTraceMetadata = [
         'baggage',
         'sentry-trace',
+        SHELL_META_TAG_NAME,
         ...(incomingUserNextConfigObject.experimental?.clientTraceMetadata || []),
       ];
     }
 
@@ -1,12 +1,14 @@
 import type { Context, TextMapSetter, TracerProvider } from '@opentelemetry/api';
 import { propagation } from '@opentelemetry/api';
 import { SentryPropagator } from '@sentry/opentelemetry';
+import { SHELL_META_TAG_NAME } from '../common/traceMetaTags';
 import { isPrerenderContext, markPrerendersOnTracerProvider } from './prerenderContext';
 
 /**
  * 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.
+ * shell is served to, so the browser could continue a trace that never handled its request. The shell
+ * gets a `sentry-shell` marker tag with the prerender's trace instead, which the client only ever links.
  *
  * 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
@@ -17,10 +19,17 @@ export class NextSentryPropagator extends SentryPropagator {
   public inject(ctx: Context, carrier: unknown, setter: TextMapSetter): void {
     // Next.js collects the meta tag values into an array; every other caller, such as the outgoing
     // request instrumentations, passes a headers object and keeps propagating during a prerender.
-    if (Array.isArray(carrier) && isPrerenderContext(ctx)) {
+    if (!Array.isArray(carrier) || !isPrerenderContext(ctx)) {
+      super.inject(ctx, carrier, setter);
       return;
     }
-    super.inject(ctx, carrier, setter);
+
+    const values: Record<string, string> = {};
+    super.inject(ctx, values, { set: (c, key, value) => ((c as Record<string, string>)[key] = value) });
+    const sentryTrace = values['sentry-trace'];
+    if (sentryTrace) {
+      setter.set(carrier, SHELL_META_TAG_NAME, sentryTrace);
+    }
   }
 }
 
 
@@ -12,13 +12,16 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import '@sentry/core';
 import '@sentry/react';
 import '../../src/client/routing/appRouterRoutingInstrumentation';
+import '../../src/client/routing/appRouterPageloadInstrumentation';
 import type * as AppRouterInstrumentation from '../../src/client/routing/appRouterRoutingInstrumentation';
+import type * as AppRouterPageload from '../../src/client/routing/appRouterPageloadInstrumentation';
 import type * as RouteProvider from '../../src/client/routing/routeProvider';
 import type { RouteManifest } from '../../src/config/manifest/types';
 
 type Core = typeof SentryCore;
 type React = typeof SentryReact;
 type Instrumentation = typeof AppRouterInstrumentation;
+type PageloadInstrumentation = typeof AppRouterPageload;
 type RouteProviderModule = typeof RouteProvider;
 
 interface NextRouter {
@@ -67,11 +70,13 @@ async function setup(traceLifecycle: 'stream' | 'static'): Promise<{
   router: NextRouter;
   client: Client;
   instrumentation: Instrumentation;
+  pageload: PageloadInstrumentation;
 }> {
   vi.resetModules();
   const core: Core = await import('@sentry/core');
   const react: React = await import('@sentry/react');
   const instrumentation: Instrumentation = await import('../../src/client/routing/appRouterRoutingInstrumentation');
+  const pageload: PageloadInstrumentation = await import('../../src/client/routing/appRouterPageloadInstrumentation');
   const routeProvider: RouteProviderModule = await import('../../src/client/routing/routeProvider');
 
   const client = new react.BrowserClient({
@@ -93,7 +98,7 @@ async function setup(traceLifecycle: 'stream' | 'static'): Promise<{
   instrumentation.appRouterInstrumentNavigation(client);
   await vi.waitFor(() => expect(router.back).not.toBe(originalBack));
 
-  return { core, router, client, instrumentation };
+  return { core, router, client, instrumentation, pageload };
 }
 
 describe('appRouterInstrumentNavigation (router-patch mode)', () => {
@@ -291,13 +296,13 @@ describe('appRouterInstrumentPageLoad', () => {
   });
 
   it('records the URL of the document when the pageload starts after a navigation changed it', async () => {
-    const { core, instrumentation } = await setup('static');
+    const { core, pageload } = await setup('static');
 
-    instrumentation.appRouterInstrumentPageLoad(core.getClient()!);
+    pageload.appRouterInstrumentPageLoad(core.getClient()!);
     const spanBeforeSettling = core.getActiveSpan();
 
     window.history.replaceState({}, '', '/navigation/42/router-back');
-    instrumentation.settlePendingPageloadWait();
+    pageload.settlePendingPageloadWait();
 
     const span = core.getActiveSpan();
     expect(span).toBeDefined();
@@ -315,4 +320,30 @@ describe('appRouterInstrumentPageLoad', () => {
       'http://localhost:3000/navigation?from=document',
     );
   });
+
+  it('marks a pageload whose document is a cached shell and links the prerender', async () => {
+    const { core, pageload } = await setup('static');
+    Object.defineProperty(document, 'readyState', { value: 'complete', configurable: true });
+    const meta = document.createElement('meta');
+    meta.name = 'sentry-shell';
+    meta.content = '11111111111111111111111111111111-1111111111111111-1';
+    document.head.appendChild(meta);
+
+    pageload.appRouterInstrumentPageLoad(core.getClient()!);
+
+    const span = core.getActiveSpan();
+    expect(span).toBeDefined();
+    const spanJson = core.spanToJSON(span!);
+    expect(spanJson.attributes?.[SENTRY_OP]).toBe(PAGELOAD);
+    expect(spanJson.attributes?.['sentry.nextjs.cached_shell']).toBe(true);
+    expect(spanJson.trace_id).not.toBe('11111111111111111111111111111111');
+    expect(spanJson.links).toEqual([
+      expect.objectContaining({
+        trace_id: '11111111111111111111111111111111',
+        span_id: '1111111111111111',
+        attributes: expect.objectContaining({ 'sentry.link.type': 'cache_origin' }),
+      }),
+    ]);
+    meta.remove();
+  });
 });