Add clientTraceMetadata experimental option to propagate tracing data to the client

packages/next-swc/crates/next-core/src/next_config.rs

@@ -514,6 +514,7 @@ pub struct ExperimentalConfig {
     gzip_size: Option<bool>,
 
     instrumentation_hook: Option<bool>,
+    client_trace_metadata: Option<Vec<String>>,
     large_page_data_bytes: Option<f64>,
     logging: Option<serde_json::Value>,
     memory_based_workers_count: Option<bool>,

packages/next/src/build/webpack-config.ts

@@ -2057,6 +2057,7 @@ export default async function getBaseWebpackConfig(
     emotion: config.compiler?.emotion,
     modularizeImports: config.modularizeImports,
     imageLoaderFile: config.images.loaderFile,
+    clientTraceMetadata: config.experimental.clientTraceMetadata,
   })
 
   const cache: any = {

packages/next/src/export/index.ts

@@ -420,6 +420,7 @@ export async function exportAppImpl(
     deploymentId: nextConfig.deploymentId,
     experimental: {
       isAppPPREnabled: checkIsAppPPREnabled(nextConfig.experimental.ppr),
+      clientTraceMetadata: nextConfig.experimental.clientTraceMetadata,
       swrDelta: nextConfig.experimental.swrDelta,
     },
   }

packages/next/src/server/app-render/app-render.tsx

@@ -76,7 +76,10 @@ import { appendMutableCookies } from '../web/spec-extension/adapters/request-coo
 import { createServerInsertedHTML } from './server-inserted-html'
 import { getRequiredScripts } from './required-scripts'
 import { addPathPrefix } from '../../shared/lib/router/utils/add-path-prefix'
-import { makeGetServerInsertedHTML } from './make-get-server-inserted-html'
+import {
+  getTracedMetadata,
+  makeGetServerInsertedHTML,
+} from './make-get-server-inserted-html'
 import { walkTreeWithFlightRouterState } from './walk-tree-with-flight-router-state'
 import { createComponentTree } from './create-component-tree'
 import { getAssetQueryString } from './get-asset-query-string'
@@ -912,6 +915,11 @@ async function renderToHTMLOrFlightImpl(
       tree,
       formState,
     }: RenderToStreamOptions): Promise<RenderToStreamResult> => {
+      const tracingMetadata = getTracedMetadata(
+        getTracer().getTracePropagationData(),
+        renderOpts.experimental.clientTraceMetadata
+      )
+
       const polyfills: JSX.IntrinsicElements['script'][] =
         buildManifest.polyfillFiles
           .filter(
@@ -995,6 +1003,7 @@ async function renderToHTMLOrFlightImpl(
         renderServerInsertedHTML,
         serverCapturedErrors: allCapturedErrors,
         basePath: renderOpts.basePath,
+        tracingMetadata: tracingMetadata,
       })
 
       const renderer = createStaticRenderer({
@@ -1319,6 +1328,7 @@ async function renderToHTMLOrFlightImpl(
                 renderServerInsertedHTML,
                 serverCapturedErrors: [],
                 basePath: renderOpts.basePath,
+                tracingMetadata: tracingMetadata,
               }),
               serverInsertedHTMLToHead: true,
               validateRootLayout,

packages/next/src/server/app-render/make-get-server-inserted-html.tsx

@@ -9,15 +9,26 @@ import { renderToReadableStream } from 'react-dom/server.edge'
 import { streamToString } from '../stream-utils/node-web-streams-helper'
 import { RedirectStatusCode } from '../../client/components/redirect-status-code'
 import { addPathPrefix } from '../../shared/lib/router/utils/add-path-prefix'
+import type { ClientTraceDataEntry } from '../lib/trace/tracer'
+
+export function getTracedMetadata(
+  traceData: ClientTraceDataEntry[],
+  clientTraceMetadata: string[] | undefined
+): ClientTraceDataEntry[] | undefined {
+  if (!clientTraceMetadata) return undefined
+  return traceData.filter(({ key }) => clientTraceMetadata.includes(key))
+}
 
 export function makeGetServerInsertedHTML({
   polyfills,
   renderServerInsertedHTML,
   serverCapturedErrors,
+  tracingMetadata,
   basePath,
 }: {
   polyfills: JSX.IntrinsicElements['script'][]
   renderServerInsertedHTML: () => React.ReactNode
+  tracingMetadata: ClientTraceDataEntry[] | undefined
   serverCapturedErrors: Error[]
   basePath: string
 }) {
@@ -82,6 +93,17 @@ export function makeGetServerInsertedHTML({
             })
         }
         {serverInsertedHTML}
+        {tracingMetadata
+          ? tracingMetadata.map(({ key, value }) => {
+              return (
+                <meta
+                  key={`next-trace-data-${key}:${value}`}
+                  name={key}
+                  content={value}
+                />
+              )
+            })
+          : null}
         {errorMetaTags}
       </>,
       {

packages/next/src/server/app-render/types.ts

@@ -170,6 +170,7 @@ export interface RenderOptsPartial {
      */
     isRoutePPREnabled?: boolean
     swrDelta: SwrDelta | undefined
+    clientTraceMetadata: string[] | undefined
   }
   postponed?: string
   /**

packages/next/src/server/base-server.ts

@@ -556,6 +556,7 @@ export default abstract class Server<
       experimental: {
         isAppPPREnabled,
         swrDelta: this.nextConfig.experimental.swrDelta,
+        clientTraceMetadata: this.nextConfig.experimental.clientTraceMetadata,
       },
     }
 

packages/next/src/server/config-schema.ts

@@ -390,6 +390,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
         optimizePackageImports: z.array(z.string()).optional(),
         optimizeServerReact: z.boolean().optional(),
         instrumentationHook: z.boolean().optional(),
+        clientTraceMetadata: z.array(z.string()).optional(),
         turbotrace: z
           .object({
             logLevel: z

packages/next/src/server/config-shared.ts

@@ -365,6 +365,11 @@ export interface ExperimentalConfig {
    */
   instrumentationHook?: boolean
 
+  /**
+   * The array of the meta tags to the client injected by tracing propagation data.
+   */
+  clientTraceMetadata?: string[]
+
   /**
    * Using this feature will enable the `react@experimental` for the `app` directory.
    */
@@ -919,6 +924,7 @@ export const defaultConfig: NextConfig = {
     turbotrace: undefined,
     typedRoutes: false,
     instrumentationHook: false,
+    clientTraceMetadata: undefined,
     parallelServerCompiles: false,
     parallelServerBuildTraces: false,
     ppr:

packages/next/src/server/lib/trace/tracer.ts

@@ -1,4 +1,5 @@
 import type { FetchEventResult } from '../../web/types'
+import type { TextMapSetter } from '@opentelemetry/api'
 import type { SpanTypes } from './constants'
 import { LogSpanAllowList, NextVanillaSpanAllowlist } from './constants'
 
@@ -149,6 +150,12 @@ interface NextTracer {
    * Returns undefined otherwise.
    */
   getActiveScopeSpan(): Span | undefined
+
+  /**
+   * Returns trace propagation data for the currently active context. The format is equal to data provided
+   * through the OpenTelemetry propagator API.
+   */
+  getTracePropagationData(): ClientTraceDataEntry[]
 }
 
 type NextAttributeNames =
@@ -171,6 +178,20 @@ const rootSpanIdKey = api.createContextKey('next.rootSpanId')
 let lastSpanId = 0
 const getSpanId = () => lastSpanId++
 
+export interface ClientTraceDataEntry {
+  key: string
+  value: string
+}
+
+const clientTraceDataSetter: TextMapSetter<ClientTraceDataEntry[]> = {
+  set(carrier, key, value) {
+    carrier.push({
+      key,
+      value,
+    })
+  },
+}
+
 class NextTracerImpl implements NextTracer {
   /**
    * Returns an instance to the trace with configured name.
@@ -185,6 +206,13 @@ class NextTracerImpl implements NextTracer {
     return context
   }
 
+  public getTracePropagationData(): ClientTraceDataEntry[] {
+    const activeContext = context.active()
+    const entries: ClientTraceDataEntry[] = []
+    propagation.inject(activeContext, entries, clientTraceDataSetter)
+    return entries
+  }
+
   public getActiveScopeSpan(): Span | undefined {
     return trace.getSpan(context?.active())
   }

test/e2e/opentelemetry/client-trace-metadata/.gitignore

@@ -0,0 +1,2 @@
+# files generated by next.js
+node_modules/

test/e2e/opentelemetry/client-trace-metadata/app/dynamic-page/page.tsx

@@ -0,0 +1,5 @@
+export const dynamic = 'force-dynamic'
+
+export default function DynamicPage() {
+  return <h1 id="dynamic-page-header">Dynamic Page</h1>
+}

test/e2e/opentelemetry/client-trace-metadata/app/layout.tsx

@@ -0,0 +1,7 @@
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/opentelemetry/client-trace-metadata/app/static-page-2/page.tsx

@@ -0,0 +1,3 @@
+export default function StaticPage() {
+  return <h1 id="static-page-2-header">Static Page 2</h1>
+}

test/e2e/opentelemetry/client-trace-metadata/app/static-page/page.tsx

@@ -0,0 +1,15 @@
+import Link from 'next/link'
+
+export default function StaticPage() {
+  return (
+    <>
+      <h1 id="static-page-header">Static Page</h1>
+      <Link href="/dynamic-page" id="go-to-dynamic-page">
+        Go to dynamic page
+      </Link>
+      <Link href="/static-page-2" id="go-to-static-page">
+        Go to static page
+      </Link>
+    </>
+  )
+}