ref(nextjs): Name the cached document attribute and marker tag framework neutral

`document.cached` and `sentry-prerender` instead of a Next.js specific
attribute and `sentry-shell`, so other frameworks with prerendering can set
the same attribute.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: chargome

CHANGELOG.md

@@ -10,7 +10,7 @@
 
 - **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.
+  A pageload whose document was served from a cache, for example an ISR page or a `cacheComponents` page generated on first visit, now carries the `document.cached` attribute and a `cache_origin` span link to the request that prerendered the page. 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
 

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/tests/cacheOrigin-pageloadConnection.spec.ts

@@ -7,7 +7,7 @@ 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. A shell prerendered at runtime carries a `sentry-shell`
+// which the pageload instrumentation waits for. A shell prerendered at runtime carries a `sentry-prerender`
 // 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 }) => {
@@ -58,11 +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, only a `sentry-shell` marker with its own
+  // shell for this id. The prerender writes no trace tag, only a `sentry-prerender` 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; cachedShell: unknown }> => {
+  const visit = async (): Promise<{ traceId: string | undefined; links: unknown; documentCached: unknown }> => {
     const context = await browser.newContext();
     const page: Page = await context.newPage();
 
@@ -76,15 +76,15 @@ 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);
+    expect(await page.locator('meta[name="sentry-prerender"]').count()).toBe(1);
 
     const pageloadTx = await pageloadTxPromise;
     await context.close();
 
     return {
       traceId: pageloadTx.contexts?.trace?.trace_id,
       links: pageloadTx.contexts?.trace?.links,
-      cachedShell: pageloadTx.contexts?.trace?.data?.['sentry.nextjs.cached_shell'],
+      documentCached: pageloadTx.contexts?.trace?.data?.['document.cached'],
     };
   };
 
@@ -94,8 +94,8 @@ 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.cachedShell).toBe(true);
-  expect(second.cachedShell).toBe(true);
+  expect(first.documentCached).toBe(true);
+  expect(second.documentCached).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> } => {
@@ -122,8 +122,8 @@ test('starts a fresh trace on a fully static page', async ({ page }) => {
 
   // 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(await page.locator('meta[name="sentry-prerender"]').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();
+  expect(pageloadTx.contexts?.trace?.data?.['document.cached']).toBeUndefined();
 });

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/tests/cacheOrigin-pageloadConnection.spec.ts

@@ -7,7 +7,7 @@ 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. A shell prerendered at runtime carries a `sentry-shell`
+// which the pageload instrumentation waits for. A shell prerendered at runtime carries a `sentry-prerender`
 // 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 }) => {
@@ -56,11 +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, only a `sentry-shell` marker with its own
+  // shell for this id. The prerender writes no trace tag, only a `sentry-prerender` 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; cachedShell: unknown }> => {
+  const visit = async (): Promise<{ traceId: string | undefined; links: unknown; documentCached: unknown }> => {
     const context = await browser.newContext();
     const page: Page = await context.newPage();
 
@@ -71,15 +71,15 @@ 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);
+    expect(await page.locator('meta[name="sentry-prerender"]').count()).toBe(1);
 
     const pageloadSpan = await pageloadSpanPromise;
     await context.close();
 
     return {
       traceId: pageloadSpan.trace_id,
       links: pageloadSpan.links,
-      cachedShell: pageloadSpan.attributes['sentry.nextjs.cached_shell']?.value,
+      documentCached: pageloadSpan.attributes['document.cached']?.value,
     };
   };
 
@@ -89,8 +89,8 @@ 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.cachedShell).toBe(true);
-  expect(second.cachedShell).toBe(true);
+  expect(first.documentCached).toBe(true);
+  expect(second.documentCached).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 }> } => {
@@ -117,8 +117,8 @@ test('starts a fresh trace on a fully static page', async ({ page }) => {
 
   // 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(await page.locator('meta[name="sentry-prerender"]').count()).toBe(0);
   expect(pageloadSpan.trace_id).toBeTruthy();
   expect(pageloadSpan.links).toBeUndefined();
-  expect(pageloadSpan.attributes['sentry.nextjs.cached_shell']).toBeUndefined();
+  expect(pageloadSpan.attributes['document.cached']).toBeUndefined();
 });

packages/nextjs/src/client/routing/appRouterPageloadInstrumentation.ts

@@ -19,9 +19,9 @@ import { stripTrailingSlash } from './parameterization';
 import type { TraceMetaTagValues, TraceMetaTagWait } from './traceMetaTags';
 import {
   addTraceMetaTagLink,
-  cachedShellSpanOptions,
+  cachedDocumentSpanOptions,
   canWaitForTraceMetaTag,
-  readShellMarker,
+  readPrerenderMarker,
   readTraceMetaTags,
   waitForTraceMetaTag,
 } from './traceMetaTags';
@@ -53,15 +53,15 @@ function startPageloadSpan(
   documentUrl: string,
   traceMetaTags?: TraceMetaTagValues,
 ): Span | undefined {
-  const shellMarker = readShellMarker();
-  const shellOptions = shellMarker ? cachedShellSpanOptions(shellMarker) : undefined;
+  const prerenderMarker = readPrerenderMarker();
+  const prerenderOptions = prerenderMarker ? cachedDocumentSpanOptions(prerenderMarker) : undefined;
   const span = startBrowserTracingPageLoadSpan(
     client,
-    shellOptions
+    prerenderOptions
       ? {
           ...spanOptions,
-          attributes: { ...spanOptions.attributes, ...shellOptions.attributes },
-          links: shellOptions.links,
+          attributes: { ...spanOptions.attributes, ...prerenderOptions.attributes },
+          links: prerenderOptions.links,
         }
       : spanOptions,
     traceMetaTags,

packages/nextjs/src/client/routing/traceMetaTags.ts

@@ -1,7 +1,7 @@
 import { SENTRY_LINK_TYPE } from '@sentry/conventions/attributes';
 import type { Span, SpanLink, StartSpanOptions } from '@sentry/core';
 import { extractTraceparentData, GLOBAL_OBJ } from '@sentry/core';
-import { SHELL_META_TAG_NAME } from '../../common/traceMetaTags';
+import { PRERENDER_META_TAG_NAME } from '../../common/traceMetaTags';
 import { WINDOW } from '@sentry/react';
 
 // `@opentelemetry/api` `TraceFlags`, inlined because core does not export its copies.
@@ -13,8 +13,8 @@ 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';
+/** Set on a pageload whose document was served from a cache, so no server render ran for the request. */
+export const DOCUMENT_CACHED_ATTRIBUTE = 'document.cached';
 
 function getDocument(): Document | undefined {
   return WINDOW.document;
@@ -159,19 +159,19 @@ export function addTraceMetaTagLink(span: Span, { sentryTrace }: TraceMetaTagVal
   }
 }
 
-/** Reads the marker the server writes into a shell while it prerenders it, see `nextSentryPropagator.ts`. */
-export function readShellMarker(): string | undefined {
+/** Reads the marker the server writes into a document while it prerenders it, see `nextSentryPropagator.ts`. */
+export function readPrerenderMarker(): string | undefined {
   const document = getDocument();
-  return document && lastMetaContent(document, SHELL_META_TAG_NAME);
+  return document && lastMetaContent(document, PRERENDER_META_TAG_NAME);
 }
 
 /**
- * The start options that mark a pageload whose document is a cached shell and link the request that
- * prerendered the shell. Applied at span start, so `tracesSampler` and `ignoreSpans` see the attribute.
- * The marker is never continued: the shell is served to every later visitor, and the request behind it
- * handled none of their visits.
+ * The start options that mark a pageload whose document was served from a cache and link the request
+ * that prerendered it. Applied at span start, so `tracesSampler` and `ignoreSpans` see the attribute.
+ * The marker is never continued: the document is served to every later visitor, and the request behind
+ * it handled none of their visits.
  */
-export function cachedShellSpanOptions(marker: string): Pick<StartSpanOptions, 'attributes' | 'links'> {
+export function cachedDocumentSpanOptions(marker: string): Pick<StartSpanOptions, 'attributes' | 'links'> {
   const link = traceMetaTagLink(marker, 'cache_origin');
-  return { attributes: { [CACHED_SHELL_ATTRIBUTE]: true }, ...(link && { links: [link] }) };
+  return { attributes: { [DOCUMENT_CACHED_ATTRIBUTE]: true }, ...(link && { links: [link] }) };
 }

packages/nextjs/src/common/traceMetaTags.ts

@@ -1,7 +1,7 @@
 /**
  * Name of the meta tag the server writes instead of `sentry-trace` while Next.js prerenders a document.
- * Its content is the `sentry-trace` value of the prerender. A prerendered shell is cached and served to
- * later visitors, so the client never continues it, it only marks the pageload as served from a cached
- * shell and links the request that generated it.
+ * Its content is the `sentry-trace` value of the prerender. A prerendered document is cached and served
+ * to later visitors, so the client never continues it, it only marks the pageload as served from a
+ * cached document and links the request that generated it.
  */
-export const SHELL_META_TAG_NAME = 'sentry-shell';
+export const PRERENDER_META_TAG_NAME = 'sentry-prerender';

packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectUtils.ts

@@ -1,4 +1,4 @@
-import { SHELL_META_TAG_NAME } from '../../common/traceMetaTags';
+import { PRERENDER_META_TAG_NAME } from '../../common/traceMetaTags';
 import { debug, isMatchingPattern, parseSemver } from '@sentry/core';
 import { getSentryRelease } from '@sentry/node';
 import * as fs from 'fs';
@@ -149,7 +149,7 @@ export function maybeSetClientTraceMetadataOption(
       incomingUserNextConfigObject.experimental.clientTraceMetadata = [
         'baggage',
         'sentry-trace',
-        SHELL_META_TAG_NAME,
+        PRERENDER_META_TAG_NAME,
         ...(incomingUserNextConfigObject.experimental?.clientTraceMetadata || []),
       ];
     }

packages/nextjs/src/server/nextSentryPropagator.ts

@@ -1,14 +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 { PRERENDER_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. The shell
- * gets a `sentry-shell` marker tag with the prerender's trace instead, which the client only ever links.
+ * gets a `sentry-prerender` 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
@@ -28,7 +28,7 @@ export class NextSentryPropagator extends SentryPropagator {
     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);
+      setter.set(carrier, PRERENDER_META_TAG_NAME, sentryTrace);
     }
   }
 }

packages/nextjs/test/client/appRouterRoutingInstrumentation.test.ts

@@ -325,7 +325,7 @@ describe('appRouterInstrumentPageLoad', () => {
     const { core, pageload } = await setup('static');
     Object.defineProperty(document, 'readyState', { value: 'complete', configurable: true });
     const meta = document.createElement('meta');
-    meta.name = 'sentry-shell';
+    meta.name = 'sentry-prerender';
     meta.content = '11111111111111111111111111111111-1111111111111111-1';
     document.head.appendChild(meta);
 
@@ -335,7 +335,7 @@ describe('appRouterInstrumentPageLoad', () => {
     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.attributes?.['document.cached']).toBe(true);
     expect(spanJson.trace_id).not.toBe('11111111111111111111111111111111');
     expect(spanJson.links).toEqual([
       expect.objectContaining({

packages/nextjs/test/client/traceMetaTags.test.ts

@@ -4,8 +4,8 @@ import type { Span } from '@sentry/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   addTraceMetaTagLink,
-  cachedShellSpanOptions,
-  readShellMarker,
+  cachedDocumentSpanOptions,
+  readPrerenderMarker,
   canWaitForTraceMetaTag,
   readTraceMetaTags,
   waitForTraceMetaTag,
@@ -220,23 +220,23 @@ describe('addTraceMetaTagLink', () => {
   });
 });
 
-describe('readShellMarker', () => {
-  it('returns nothing without a sentry-shell tag', () => {
-    expect(readShellMarker()).toBeUndefined();
+describe('readPrerenderMarker', () => {
+  it('returns nothing without a sentry-prerender tag', () => {
+    expect(readPrerenderMarker()).toBeUndefined();
   });
 
-  it('reads the last sentry-shell tag', () => {
-    appendMeta(document.head, 'sentry-shell', HEAD_TRACE);
-    appendMeta(document.body, 'sentry-shell', BODY_TRACE);
+  it('reads the last sentry-prerender tag', () => {
+    appendMeta(document.head, 'sentry-prerender', HEAD_TRACE);
+    appendMeta(document.body, 'sentry-prerender', BODY_TRACE);
 
-    expect(readShellMarker()).toBe(BODY_TRACE);
+    expect(readPrerenderMarker()).toBe(BODY_TRACE);
   });
 });
 
-describe('cachedShellSpanOptions', () => {
+describe('cachedDocumentSpanOptions', () => {
   it('marks the span and links the prerender as cache origin', () => {
-    expect(cachedShellSpanOptions(HEAD_TRACE)).toEqual({
-      attributes: { 'sentry.nextjs.cached_shell': true },
+    expect(cachedDocumentSpanOptions(HEAD_TRACE)).toEqual({
+      attributes: { 'document.cached': true },
       links: [
         {
           context: { traceId: '11111111111111111111111111111111', spanId: '1111111111111111', traceFlags: 1 },
@@ -247,6 +247,6 @@ describe('cachedShellSpanOptions', () => {
   });
 
   it('marks the span even when the marker is not a sentry-trace value', () => {
-    expect(cachedShellSpanOptions('prerendered')).toEqual({ attributes: { 'sentry.nextjs.cached_shell': true } });
+    expect(cachedDocumentSpanOptions('prerendered')).toEqual({ attributes: { 'document.cached': true } });
   });
 });