Unverified Commit d5dc166f authored by Josh Story's avatar Josh Story Committed by GitHub

[Cache Components] Allow span creation while prerendering (#82350)

When creating spans with OTel random values must be created to follow
the OTel spec and is expected in practical implementations. While it is
a loose concession Next.js will allow spans to be created while
prerendering that have ids generated with random values. and by reading
the current time from the system clock.

This is pragmatic but potentially risky because if you are not careful
and for instance wrap a "use cache" function in a span it is possible
you will accidentally pass the span into the cache function causing it
to miss on every invocation due to the random nature of one of it's
arguments.

To defend against this we do check whether `startActiveSpan` is being
passed a Cache Function. However it is easy to circumvent by wrapping it
in an intermediate function or by using startSpan and context.with
yourself.

In the long run we should consider tainting the Span objects created in
these scopes so they cannot be sent through to a cache. I will consider
a follow up PR to land this if we determine taint is likely to be
stabilized in React.

The pratical implementation of this change is to patch the tracer
provider so that it always provides a patched tracer which exits the
workUnitStorage on span start/creation and re-enters the scope on inner
function exectuion.
parent bdd41bbc
......@@ -772,5 +772,6 @@
"771": "\\`%s\\` was called during a runtime prerender. Next.js should be preventing %s from being included in server components statically, but did not in this case.",
"772": "FetchStrategy.PPRRuntime should never be used when `experimental.clientSegmentCache` is disabled",
"773": "Missing workStore in createPrerenderParamsForClientSegment",
"774": "Route %s used %s outside of a Server Component. This is not allowed."
"774": "Route %s used %s outside of a Server Component. This is not allowed.",
"775": "Node.js instrumentation extensions should not be loaded in the Edge runtime."
}
......@@ -6,6 +6,7 @@ import type {
InstrumentationOnRequestError,
} from '../../instrumentation/types'
import { interopDefault } from '../../../lib/interop-default'
import { afterRegistration as extendInstrumentationAfterRegistration } from './instrumentation-node-extensions'
let cachedInstrumentationModule: InstrumentationModule
......@@ -55,6 +56,7 @@ async function registerInstrumentation(projectDir: string, distDir: string) {
if (instrumentation?.register) {
try {
await instrumentation.register()
extendInstrumentationAfterRegistration()
} catch (err: any) {
err.message = `An error occurred while loading instrumentation hook: ${err.message}`
throw err
......
/**
* This extension augments opentelemetry after registration if applicable.
* This extension must only be loaded in Node environments.
*/
import type { Tracer } from '@opentelemetry/api'
import {
type WorkUnitStore,
workUnitAsyncStorage,
} from '../../app-render/work-unit-async-storage.external'
import { InvariantError } from '../../../shared/lib/invariant-error'
import { isUseCacheFunction } from '../../../lib/client-and-server-references'
export function afterRegistration(): void {
if (process.env.NEXT_RUNTIME === 'edge') {
throw new InvariantError(
'Node.js instrumentation extensions should not be loaded in the Edge runtime.'
)
}
extendTracerProviderForCacheComponents()
}
// In theory we only want to enable this extension when cacheComponents is enabled
// however there are certain servers that might load instrumentation before nextConfig is available
// and so gating it on the config might lead to skipping this extension even when it is necessary.
// When cacheComponents is disabled this extension should be a no-op so we enable it universally.
// Additionally, soon, cacheComponents will be enabled always so this just pulls the extension forward in time
function extendTracerProviderForCacheComponents(): void {
let api: typeof import('next/dist/compiled/@opentelemetry/api')
// we want to allow users to use their own version of @opentelemetry/api if they
// want to, so we try to require it first, and if it fails we fall back to the
// version that is bundled with Next.js
// this is because @opentelemetry/api has to be synced with the version of
// @opentelemetry/tracing that is used, and we don't want to force users to use
// the version that is bundled with Next.js.
// the API is ~stable, so this should be fine
try {
api = require('@opentelemetry/api') as typeof import('@opentelemetry/api')
} catch (err) {
api =
require('next/dist/compiled/@opentelemetry/api') as typeof import('next/dist/compiled/@opentelemetry/api')
}
const provider = api.trace.getTracerProvider()
// When Cache Components is enabled we need to instrument the tracer
// to exit the workUnitAsyncStorage context when generating spans.
const originalGetTracer = provider.getTracer.bind(provider)
provider.getTracer = (...args) => {
const tracer = originalGetTracer.apply(provider, args)
if (WeakTracers.has(tracer)) {
return tracer
}
const originalStartSpan = tracer.startSpan
tracer.startSpan = (...startSpanArgs) => {
return workUnitAsyncStorage.exit(() =>
originalStartSpan.apply(tracer, startSpanArgs)
)
}
const originalStartActiveSpan = tracer.startActiveSpan
// @ts-ignore TS doesn't recognize the overloads correctly
tracer.startActiveSpan = (...startActiveSpanArgs: any[]) => {
const workUnitStore = workUnitAsyncStorage.getStore()
if (!workUnitStore) {
// @ts-ignore TS doesn't recognize the overloads correctly
return originalStartActiveSpan.apply(tracer, startActiveSpanArgs)
}
let fnIdx: number = 0
if (
startActiveSpanArgs.length === 2 &&
typeof startActiveSpanArgs[1] === 'function'
) {
fnIdx = 1
} else if (
startActiveSpanArgs.length === 3 &&
typeof startActiveSpanArgs[2] === 'function'
) {
fnIdx = 2
} else if (
startActiveSpanArgs.length > 3 &&
typeof startActiveSpanArgs[3] === 'function'
) {
fnIdx = 3
}
if (fnIdx) {
const originalFn = startActiveSpanArgs[fnIdx]
if (isUseCacheFunction(originalFn)) {
console.error(
'A Cache Function (`use cache`) was passed to startActiveSpan which means it will receive a Span argument with a possibly random ID on every invocation leading to cache misses. Provide a wrapping function around the Cache Function that does not forward the Span argument to avoid this issue.'
)
}
startActiveSpanArgs[fnIdx] = withWorkUnitContext(
workUnitStore,
originalFn
)
}
return workUnitAsyncStorage.exit(() => {
// @ts-ignore TS doesn't recognize the overloads correctly
return originalStartActiveSpan.apply(tracer, startActiveSpanArgs)
})
}
WeakTracers.add(tracer)
return tracer
}
}
const WeakTracers = new WeakSet<Tracer>()
function withWorkUnitContext(
workUnitStore: WorkUnitStore,
fn: (...args: any[]) => any
) {
return (...args: any[]) =>
workUnitAsyncStorage.run(workUnitStore, fn, ...args)
}
node_modules
pnpm-lock.yaml
\ No newline at end of file
import {
CachedInnerTraceManualSpan,
InnerTraceManualSpan,
CachedTracedComponentManualSpan,
TracedComponentManualSpan,
CachedInnerTraceActiveSpan,
InnerTraceActiveSpan,
CachedTracedComponentActiveSpan,
TracedComponentActiveSpan,
} from '../../traced-work'
export function generateStaticParams() {
return [{ slug: 'prerendered' }]
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
'use cache'
return (
<>
<h1>{(await params).slug}</h1>
<div>We are inside a "use cache" scope</div>
<CachedInnerTraceManualSpan />
<InnerTraceManualSpan />
<CachedTracedComponentManualSpan />
<TracedComponentManualSpan />
<CachedInnerTraceActiveSpan />
<InnerTraceActiveSpan />
<CachedTracedComponentActiveSpan />
<TracedComponentActiveSpan />
</>
)
}
import { Suspense } from 'react'
export default async function Layout({
children,
}: {
children: React.ReactNode
}) {
return <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
}
import {
CachedInnerTraceManualSpan,
InnerTraceManualSpan,
CachedTracedComponentManualSpan,
TracedComponentManualSpan,
CachedInnerTraceActiveSpan,
InnerTraceActiveSpan,
CachedTracedComponentActiveSpan,
TracedComponentActiveSpan,
} from '../../traced-work'
export function generateStaticParams() {
return [{ slug: 'prerendered' }]
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
return (
<>
<h1>{(await params).slug}</h1>
<div>We are inside a "use server" scope</div>
<CachedInnerTraceManualSpan />
<InnerTraceManualSpan />
<CachedTracedComponentManualSpan />
<TracedComponentManualSpan />
<CachedInnerTraceActiveSpan />
<InnerTraceActiveSpan />
<CachedTracedComponentActiveSpan />
<TracedComponentActiveSpan />
</>
)
}
import {
CachedInnerTraceManualSpan,
InnerTraceManualSpan,
CachedTracedComponentManualSpan,
TracedComponentManualSpan,
CachedInnerTraceActiveSpan,
InnerTraceActiveSpan,
CachedTracedComponentActiveSpan,
TracedComponentActiveSpan,
} from '../../traced-work'
export function generateStaticParams() {
return [{ slug: 'prerendered' }]
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
return (
<>
<h1>{(await params).slug}</h1>
<div>We are inside a "use server" scope</div>
<CachedInnerTraceManualSpan />
<InnerTraceManualSpan />
<CachedTracedComponentManualSpan />
<TracedComponentManualSpan />
<CachedInnerTraceActiveSpan />
<InnerTraceActiveSpan />
<CachedTracedComponentActiveSpan />
<TracedComponentActiveSpan />
</>
)
}
export default function Root({ children }: { children: React.ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return (
<main>
<h1>OTel Cache Components Compat Test</h1>
<p>
Span generation causes random IDs to be created. There is a tradeoff
with this while prerendering since sync IO like Math.random() should be
excluded from static prerenders but spans are so widely used for
providing telemetry for rendering and they would ideally be side effect
free. Next.js now allows random id generation and current time reading
while OTel spans are constructed. However it is possible for the span
object to be passed to a Cache Component where the random ID will cause
cache misses while prerendering. It is important that Span objects not
be passed into Cache Functions for proper functioning of Cache
Components.
</p>
<ul>
<li>
<a href="/novel/cache">
"use cache" Page without build-time prerendering
</a>
</li>
<li>
<a href="/prerendered/cache">
"use cache" Page with build-time prerendering
</a>
</li>
<li>
<a href="/novel/server">
Server Page without build-time prerendering
</a>
</li>
<li>
<a href="/prerendered/server">
Server Page with build-time prerendering
</a>
</li>
</ul>
</main>
)
}
import { type Span, trace, context } from '@opentelemetry/api'
import { Suspense } from 'react'
async function asyncWork() {
await new Promise((resolve) => setTimeout(resolve, 1000))
return 42
}
async function cachedAsyncWork() {
'use cache'
return asyncWork()
}
function withSpan(fn) {
return function () {
const tracer = trace.getTracer('tracer-manual-span')
const span = tracer.startSpan('span-manual-span')
const ctx = trace.setSpan(context.active(), span)
return context.with(ctx, fn)
}
}
function withActiveSpan(fn) {
return function () {
const tracer = trace.getTracer('tracer-active-span')
return tracer.startActiveSpan('span-active-span', fn)
}
}
const asyncWorkWithManualSpan = withSpan(asyncWork)
const asyncWorkWithActiveSpan = withActiveSpan(asyncWork)
const cachedAsyncWorkWithManualSpan = withSpan(cachedAsyncWork)
const cachedAsyncWorkWithActiveSpan = withActiveSpan(cachedAsyncWork)
export function CachedInnerTraceManualSpan() {
async function Inner() {
const result = await cachedAsyncWorkWithManualSpan()
return <p className="result">{result}</p>
}
return (
<section id="t1">
<h2>(Manual Span) Cached Async Work</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
}
export function InnerTraceManualSpan() {
async function Inner() {
const result = await asyncWorkWithManualSpan()
return <p className="result">{result}</p>
}
return (
<section id="t2">
<h2>(Manual Span) Async Work</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
}
export const CachedTracedComponentManualSpan = withSpan(async function () {
async function Inner() {
const result = await cachedAsyncWork()
return <Result>{result}</Result>
}
return (
<section id="t3">
<h2>(Manual Span) Inner Traced "use cache" Function</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
})
export const TracedComponentManualSpan = withSpan(async function () {
async function Inner() {
const result = await asyncWork()
return <Result>{result}</Result>
}
return (
<section id="t4">
<h2>(Manual Span) Inner Traced Function</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
})
export function CachedInnerTraceActiveSpan() {
async function Inner() {
const result = await cachedAsyncWorkWithActiveSpan()
return <Result>{result}</Result>
}
return (
<section id="t5">
<h2>(Active Span) Cached Async Work</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
}
export function InnerTraceActiveSpan() {
async function Inner() {
const result = await asyncWorkWithActiveSpan()
return <Result>{result}</Result>
}
return (
<section id="t6">
<h2>(Active Span) Async Work</h2>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</section>
)
}
export const CachedTracedComponentActiveSpan = withActiveSpan(async function (
span: Span
) {
async function Inner() {
const result = await cachedAsyncWork()
return <Result>{result}</Result>
}
return (
<section id="t7">
<h2>(Active Span) Inner Traced "use cache" Function</h2>
<div>
<p>
Span Representative{' '}
<span className="span" suppressHydrationWarning>
{parseInt(span.spanContext().spanId.slice(10), 16)}
</span>
</p>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</div>
</section>
)
})
export const TracedComponentActiveSpan = withActiveSpan(async function (
span: Span
) {
async function Inner() {
const result = await asyncWork()
return <Result>{result}</Result>
}
return (
<section id="t8">
<h2>(Active Span) Inner Traced Function</h2>
<div>
<p>
Span Representative{' '}
<span className="span" suppressHydrationWarning>
{parseInt(span.spanContext().spanId.slice(10), 16)}
</span>
</p>
<Suspense fallback={<Loading />}>
<Inner />
</Suspense>
</div>
</section>
)
})
function Loading() {
return <span className="fallback">loading...</span>
}
function Result({ children }: { children: React.ReactNode }) {
return <p className="result">{children}</p>
}
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'
import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express'
const sdk = new NodeSDK({
serviceName: 'nextjs-otel-app',
traceExporter: new OTLPTraceExporter({
url:
process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
'http://localhost:4318/v1/traces',
}),
instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
})
sdk.start()
export async function register() {
if (process.env.NEXT_RUNTIME !== 'edge') {
await import('./instrumentation.node')
}
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
experimental: {
cacheComponents: true,
},
}
module.exports = nextConfig
{
"dependencies": {
"@opentelemetry/api": "^1.9.0",
"@opentelemetry/auto-instrumentations-node": "^0.62.0",
"@opentelemetry/exporter-jaeger": "^2.0.1",
"@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
"@opentelemetry/instrumentation-express": "^0.52.0",
"@opentelemetry/instrumentation-http": "^0.203.0",
"@opentelemetry/resources": "^2.0.1",
"@opentelemetry/sdk-node": "^0.203.0",
"@opentelemetry/semantic-conventions": "^1.36.0",
"@opentelemetry/winston-transport": "^0.14.0"
}
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment