Unverified Commit 35e411ea authored by vercel-fleet-prod[bot]'s avatar vercel-fleet-prod[bot] Committed by GitHub

Add experimental OpenTelemetry tooling reporting

Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent c9af489c
...@@ -138,6 +138,7 @@ ...@@ -138,6 +138,7 @@
"@next/swc": "workspace:*", "@next/swc": "workspace:*",
"@next/third-parties": "workspace:*", "@next/third-parties": "workspace:*",
"@opentelemetry/api": "1.4.1", "@opentelemetry/api": "1.4.1",
"@opentelemetry/sdk-trace": "2.12.0",
"@picocss/pico": "1.5.10", "@picocss/pico": "1.5.10",
"@rspack/core": "1.6.7", "@rspack/core": "1.6.7",
"@slack/web-api": "7.9.1", "@slack/web-api": "7.9.1",
......
...@@ -2241,6 +2241,16 @@ export default async function build( ...@@ -2241,6 +2241,16 @@ export default async function build(
process.env.NEXT_PHASE = PHASE_PRODUCTION_BUILD process.env.NEXT_PHASE = PHASE_PRODUCTION_BUILD
if (process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING === '1') {
const { registerToolingBuildInstrumentation } =
require('../server/lib/router-utils/instrumentation-globals.external') as typeof import('../server/lib/router-utils/instrumentation-globals.external')
await registerToolingBuildInstrumentation(
dir,
distDir,
hasInstrumentationHook
)
}
staticWorker = createStaticWorker(config, { staticWorker = createStaticWorker(config, {
numberOfWorkers, numberOfWorkers,
debuggerPortOffset: getNextBuildDebuggerPortOffset({ debuggerPortOffset: getNextBuildDebuggerPortOffset({
...@@ -4722,6 +4732,11 @@ export default async function build( ...@@ -4722,6 +4732,11 @@ export default async function build(
// Ensure all buffered spans are on disk before `uploadTrace` reads the file. // Ensure all buffered spans are on disk before `uploadTrace` reads the file.
flushAllTraces() flushAllTraces()
if (process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING === '1') {
const { flushReporting } =
require('../trace/otel') as typeof import('../trace/otel')
await flushReporting()
}
teardownTraceSubscriber() teardownTraceSubscriber()
if (traceUploadUrl && loadedConfig) { if (traceUploadUrl && loadedConfig) {
......
...@@ -22,6 +22,8 @@ export type InstrumentationOnRequestError = ( ...@@ -22,6 +22,8 @@ export type InstrumentationOnRequestError = (
export type InstrumentationModule = { export type InstrumentationModule = {
register?(): void register?(): void
/** Experimental tooling-only cooperative flush; not used by production requests. */
flushTraces?(): void | Promise<void>
onRequestError?: InstrumentationOnRequestError onRequestError?: InstrumentationOnRequestError
} }
......
...@@ -102,9 +102,18 @@ export async function getInstrumentationModule( ...@@ -102,9 +102,18 @@ export async function getInstrumentationModule(
let instrumentationModulePromise: Promise<any> | null = null let instrumentationModulePromise: Promise<any> | null = null
async function registerInstrumentation(projectDir: string, distDir: string) { /**
// Ensure registerInstrumentation is not called in production build * Loads `instrumentation.ts` and calls its `register()`.
if (process.env.NEXT_PHASE === 'phase-production-build') { * Lifecycle spans are backdated and emitted afterward, since registration
* commonly installs the application's tracer provider.
*/
async function registerInstrumentation(
projectDir: string,
distDir: string,
forToolingBuild = false
) {
// Only the explicit, gated coordinator entry point may register during build.
if (process.env.NEXT_PHASE === 'phase-production-build' && !forToolingBuild) {
return return
} }
if (!instrumentationModulePromise) { if (!instrumentationModulePromise) {
...@@ -143,6 +152,47 @@ async function registerInstrumentation(projectDir: string, distDir: string) { ...@@ -143,6 +152,47 @@ async function registerInstrumentation(projectDir: string, distDir: string) {
} else { } else {
traceInstrumentationModuleLoad() traceInstrumentationModuleLoad()
} }
if (
process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING === '1' &&
(process.env.__NEXT_DEV_SERVER || forToolingBuild)
) {
const { enableReporting } =
require('../../../trace/otel') as typeof import('../../../trace/otel')
enableReporting(instrumentation?.flushTraces?.bind(instrumentation))
}
}
let toolingBuildRegistration: Promise<void> | undefined
/** Coordinator-only: register this build's entry or drain without a hook. */
export function registerToolingBuildInstrumentation(
projectDir: string,
distDir: string,
hasInstrumentationHook: boolean
) {
if (process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING !== '1') return
toolingBuildRegistration ??= (async () => {
const previousRuntime = process.env.NEXT_RUNTIME
process.env.NEXT_RUNTIME = 'nodejs'
try {
if (hasInstrumentationHook) {
await registerInstrumentation(
projectDir,
path.relative(projectDir, distDir),
true
)
} else {
// cleanDistDir:false can leave an old emitted entry behind. Only the
// current build's detected source entry may register application code.
const { enableReporting } =
require('../../../trace/otel') as typeof import('../../../trace/otel')
enableReporting()
}
} finally {
if (previousRuntime === undefined) delete process.env.NEXT_RUNTIME
else process.env.NEXT_RUNTIME = previousRuntime
}
})()
return toolingBuildRegistration
} }
export async function instrumentationOnRequestError( export async function instrumentationOnRequestError(
......
...@@ -429,6 +429,11 @@ export async function startServer( ...@@ -429,6 +429,11 @@ export async function startServer(
// Flush any remaining traces to the trace file on shutdown // Flush any remaining traces to the trace file on shutdown
flushAllTraces() flushAllTraces()
if (isDev && process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING === '1') {
const { flushReporting } =
require('../../trace/otel') as typeof import('../../trace/otel')
await flushReporting()
}
// Flush telemetry if this is a dev server // Flush telemetry if this is a dev server
if (isDev) { if (isDev) {
......
# Experimental OpenTelemetry tooling prototype
This is an opt-in architectural spike, **not a supported public API or default tracing migration**. Names, hooks, limits and packaging are provisional.
## Try it
Configure your application's OpenTelemetry provider/exporter in `instrumentation.ts` as usual, then run:
```sh
NEXT_EXPERIMENTAL_OTEL_TOOLING=1 next build
NEXT_EXPERIMENTAL_OTEL_TOOLING=1 NEXT_EXIT_TIMEOUT_MS=6000 next dev
```
There is no built-in external destination. The application owns the endpoint, exporter, resource, sampler, processors, context manager and propagators. Await provider initialization in `register()`; installing a provider later in fire-and-forget work does not recover spans already emitted to a no-op provider.
For cooperative flushing, optionally export `flushTraces()` from `instrumentation.ts`. This can call your own SDK's public `forceFlush()` method. Keep Node-only SDK imports behind `NEXT_RUNTIME === 'nodejs'`:
```ts
let flush: (() => void | Promise<void>) | undefined
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
// An application-owned module that initializes the provider/exporter.
const telemetry = await import('./telemetry.node')
await telemetry.start()
flush = () => telemetry.forceFlush()
}
}
export function flushTraces() {
return flush?.()
}
```
The hook is called after the tooling root has ended, completed tooling/worker records have been emitted, and the local trace writer has flushed. Next waits up to **5 seconds**, logs a nonfatal diagnostic on rejection/timeout, and never reaches into provider internals or shuts down the application's SDK. Without this hook, the SDK owns export completion; Next cannot guarantee a final remote drain.
**Dev shutdown:** the CLI normally gives its child only 100ms before SIGKILL. Set `NEXT_EXIT_TIMEOUT_MS` high enough for server cleanup and the cooperative hook (the command above allows 6 seconds). SIGKILL, crashes and forced restarts cannot guarantee remote completion. Production server shutdown/request tracing is unchanged by this prototype.
## Two independent lanes
- **Local:** the tooling Span records directly through the existing JSON reporters, independently of any application delegate. Like Request Insights' local recorder, it does not need a private provider. Legacy safe numeric IDs, monotonic microseconds, epoch-millisecond wall start and arbitrary raw tags remain independent of SDK attribute limits. This spike leaves Request Insights' request-specific recorder/context handling unchanged.
- **Application reporting:** tooling spans are explicitly paired/replayed using the application's global tracer (`next.js.tooling`) with explicit parent contexts. No active application context, provider, sampler, context manager or propagator is replaced. Application sampling and attribute limits apply to this lane only. Structured/array legacy tags are represented as JSON-valued strings for OTel; null/undefined tags are omitted there, not from local data.
`.next/dev/trace`, `.next/trace` and filtered `.next/trace-build` retain their existing newline-delimited array format, session ID, numeric IDs/parents, event names/tags, integer-microsecond durations and buffering/rotation semantics. Custom output directories are supported. The writer uses append mode in dev, but **ordinary dev startup cleanup still removes the prior session's trace**, as before. The legacy upload flag and custom upload wire format remain unchanged; they are not OTLP.
## Initialization and replay
Dev uses existing instrumentation compilation/registration. External tooling coverage starts in the dev-server child: startup, compilation/HMR and other child tooling operations. It intentionally does not export the CLI-parent `next-dev` session or invent a substitute parent.
An opted-in build registers the current build's compiled instrumentation entry in the **coordinator after compilation**, not via an early source loader. Ordinary builds continue skipping runtime registration. Compiler workers inherit the gate and return local tooling records through the existing coordinator path; they do not initialize the application SDK separately. The coordinator reconstructs each worker batch parent-first and suppresses redelivery. Arbitrary application-created prerender-worker spans and full Rust/native tracing are outside this spike; existing selected native compilation events remain included.
Early reporting records are retained until registration completes, with original start/end times. Live roots remain open; later children can join an ended startup parent. Storage is bounded by **10,000 records and 8 MiB** (UTF-8 names/normalized attributes plus per-record accounting). The same bounds apply to concurrently live reporting records. On overflow, external replay/new records or oversized attribute updates are dropped and a single diagnostic is emitted; local recording is unaffected. Completed reporting records release their attributes after registration, rather than accumulating every module span forever.
Direct parent handles preserve reporting context after end. Numeric-ID lookup uses live/queued spans and the pinned default startup parent. If an already-ended non-default numeric parent is no longer available, the reporting lane falls back to the known tooling root (or a root if none is available); `next.tooling.parent_id` retains the original numeric relation. Local parentage is unchanged. Reporting IDs are W3C IDs, not the legacy numeric/session IDs; `next.tooling.id` permits correlation.
Failures before successful compilation/registration still flush local traces once the output directory is known, but cannot report through an unavailable application provider. They do not load stale instrumentation output in the finalizer or when the current build has no instrumentation source entry, even with `cleanDistDir: false`. **Immediate process exits bypass finalizers:** in particular, the default `experimental.prerenderEarlyExit` policy exits the prerender worker and coordinator on a render error; use `prerenderEarlyExit: false` when evaluating controlled-failure flushing. Changing that existing exit policy is outside this spike. Hook failures, early replay overflow, missing hooks, abrupt termination and application sampling are explicit remote-reporting boundaries, not reasons to drop local diagnostics on the normal finalization path.
## Verification
The development suites `hmr-trace-timing`, `enabled-features-trace` and `rage-restart-trace` establish the legacy file contract first; the same assertions run with the gate enabled on Webpack and Turbopack. `test/e2e/app-dir/otel-tooling` exercises a custom HTTP exporter, custom dist directory, original timing/parentage, compiler-worker export, provider identity, AlwaysOff independence, registration count and flush ordering. Focused replay tests cover storage bounds, completed/live parents, worker ordering/redelivery and hook rejection/timeout. The existing writer/parser tests remain responsible for low-level buffered I/O and rotation edges.
This flag is for dev/build tooling, not an additional `next start` reporting mode. Production request tracing continues to use the existing instrumentation lifecycle; do not carry the prototype flag into a production deployment. Generalizing Request Insights and tooling recorders is separate work.
The framework adds no SDK provider or SDK dependency; it uses the OTel API to pair with the application's tracer, without requiring the application to use a particular SDK version. Dual recording adds allocation/normalization/export cost, particularly for per-module profiling. Full-scale performance review is required before considering a default rollout.
import type { Attributes, HrTime, Span } from '@opentelemetry/api'
const api =
require('next/dist/compiled/@opentelemetry/api') as typeof import('next/dist/compiled/@opentelemetry/api') as unknown as typeof import('@opentelemetry/api')
const { ROOT_CONTEXT, SpanStatusCode, trace } = api
import type { TraceEvent } from './types'
// Bounds apply to early replay and concurrently live reporting records, not to
// local diagnostics. Completed records release attributes after registration.
export const REPLAY_EVENT_LIMIT = 10_000
export const REPLAY_BYTE_LIMIT = 8 * 1024 * 1024
export const FLUSH_TIMEOUT_MS = 5_000
export type ReportingRecord = {
id: number
parentId?: number
name: string
start: HrTime
end?: HrTime
attributes: Attributes
parent?: ReportingRecord
span?: Span
retained: boolean
size: number
}
let ready = false
let suppressed = false
let warned = false
let retainedCount = 0
let retainedBytes = 0
let defaultParentId: number | undefined
let defaultParent: ReportingRecord | undefined
let flushHook: (() => void | Promise<void>) | undefined
const live = new Map<number, ReportingRecord>()
const pending = new Map<number, ReportingRecord>()
function warnLoss() {
if (!warned) {
warned = true
console.warn(
'Next.js tooling OTel replay limit reached or reporting failed; some external spans may be missing. Local trace files are unaffected.'
)
}
}
export function otelAttributes(tags: Record<string, unknown>): Attributes {
const attributes: Attributes = {}
for (const [key, value] of Object.entries(tags)) {
if (value === undefined || value === null) continue
if (
typeof value === 'string' ||
typeof value === 'number' ||
typeof value === 'boolean'
) {
attributes[key] = value
} else {
try {
attributes[key] = JSON.stringify(value)
} catch {
attributes[key] = String(value)
}
}
}
return attributes
}
function sizeOf(name: string, attributes: Attributes) {
return (
128 +
Buffer.byteLength(name) +
Buffer.byteLength(JSON.stringify(attributes))
)
}
function release(record: ReportingRecord) {
if (record.retained) {
record.retained = false
retainedCount--
retainedBytes -= record.size
}
record.attributes = {}
record.parent = undefined
live.delete(record.id)
}
function open(record: ReportingRecord): Span | undefined {
if (record.span) return record.span
if (!record.retained) return undefined
try {
const parent = record.parent ? open(record.parent) : undefined
const context = parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT
record.span = trace.getTracer('next.js.tooling').startSpan(
record.name,
{
startTime: record.start,
attributes: {
// Correlation must survive the application's SDK attribute limit.
// Legacy tags can number in the hundreds on compilation spans.
'next.tooling.id': record.id,
...(record.parentId === undefined
? {}
: { 'next.tooling.parent_id': record.parentId }),
...record.attributes,
},
},
context
)
if (record.end) finish(record)
return record.span
} catch {
warnLoss()
release(record)
return undefined
}
}
function finish(record: ReportingRecord) {
try {
if (record.attributes.failed === true) {
record.span?.setStatus({ code: SpanStatusCode.ERROR })
}
record.span?.setAttributes(record.attributes)
record.span?.end(record.end)
} catch {
warnLoss()
} finally {
release(record)
}
}
export function startReporting(
id: number,
parentId: number | undefined,
name: string,
start: HrTime,
tags: Record<string, unknown>,
parent?: ReportingRecord,
deferOpen = false
): ReportingRecord | undefined {
if (suppressed) return undefined
const attributes = otelAttributes(tags)
const size = sizeOf(name, attributes)
if (
retainedCount >= REPLAY_EVENT_LIMIT ||
retainedBytes + size > REPLAY_BYTE_LIMIT
) {
warnLoss()
return undefined
}
const record: ReportingRecord = {
id,
parentId,
name,
start,
attributes,
parent:
parent ??
live.get(parentId!) ??
pending.get(parentId!) ??
(parentId === undefined ? undefined : defaultParent),
retained: true,
size,
}
retainedCount++
retainedBytes += size
live.set(id, record)
if (id === defaultParentId) defaultParent = record
if (ready) {
if (!deferOpen) open(record)
} else {
pending.set(id, record)
}
return record
}
export function endReporting(record: ReportingRecord | undefined, end: HrTime) {
if (!record?.retained) return
record.end = end
live.delete(record.id)
if (ready) finish(record)
}
export function updateReporting(
record: ReportingRecord | undefined,
key: string,
value: unknown
) {
if (!record?.retained) return
const attributes = {
...record.attributes,
...otelAttributes({ [key]: value }),
}
const size = sizeOf(record.name, attributes)
if (retainedBytes - record.size + size > REPLAY_BYTE_LIMIT) {
warnLoss()
return
}
retainedBytes += size - record.size
record.size = size
record.attributes = attributes
}
export function configureReporting(
parentId: number | undefined,
worker: boolean
) {
defaultParentId = parentId
defaultParent = live.get(parentId!) ?? pending.get(parentId!)
suppressed = worker
if (worker) {
for (const record of pending.values()) release(record)
pending.clear()
}
}
export function replayCompleted(
events: TraceEvent[],
timing: (event: TraceEvent) => { start: HrTime; end: HrTime }
) {
const records = new Map<number, ReportingRecord>()
for (const event of events) {
const { start, end } = timing(event)
const record = startReporting(
event.id,
event.parentId,
event.name,
start,
event.tags ?? {},
undefined,
true
)
if (record) {
record.end = end
records.set(event.id, record)
live.delete(event.id)
}
}
// Worker arrays are in completion order, not tree order. Resolve the entire
// batch before opening any span so children use the real coordinator tree.
for (const record of records.values()) {
record.parent = records.get(record.parentId!) ?? record.parent
}
if (ready) {
for (const record of records.values()) open(record)
}
}
export function enableReporting(hook?: () => void | Promise<void>) {
if (ready || suppressed) return
ready = true
flushHook = hook
for (const record of pending.values()) open(record)
pending.clear()
}
export async function flushReporting() {
if (!ready || !flushHook) return
let timer: ReturnType<typeof setTimeout> | undefined
try {
await Promise.race([
Promise.resolve().then(flushHook),
new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error('timeout')), FLUSH_TIMEOUT_MS)
}),
])
} catch {
console.warn(
'Next.js tooling instrumentation.flushTraces() failed or timed out; local traces have already been flushed.'
)
} finally {
clearTimeout(timer)
}
}
// Node-only app-tracer pairing. Local spans keep their existing timing, IDs and
// reporter, independently of application sampling (as in Request Insights).
import type { HrTime } from '@opentelemetry/api'
import type { TraceEvent } from './types'
import {
configureReporting,
startReporting,
endReporting,
replayCompleted,
} from './otel-reporting'
import type { ReportingRecord } from './otel-reporting'
export {
enableReporting,
flushReporting,
updateReporting,
} from './otel-reporting'
const NS_PER_SECOND = BigInt(1_000_000_000)
const NS_PER_MS = BigInt(1_000_000)
const NS_PER_US = BigInt(1_000)
let epochOffset = BigInt(Date.now()) * NS_PER_MS - process.hrtime.bigint()
export function epochTime(monotonic: bigint): HrTime {
const ns = monotonic + epochOffset
return [Number(ns / NS_PER_SECOND), Number(ns % NS_PER_SECOND)]
}
export function startSpan(options: {
name: string
id: number
parentId?: number
attrs: Record<string, unknown>
startTime: bigint
reportingParent?: ReportingRecord
}): ReportingRecord | undefined {
return startReporting(
options.id,
options.parentId,
options.name,
epochTime(options.startTime),
options.attrs,
options.reportingParent
)
}
export function stopSpan(
record: ReportingRecord | undefined,
stopTime: bigint
) {
endReporting(record, epochTime(stopTime))
}
export function getClockOffset() {
return epochOffset.toString()
}
export function configureState(
parentId: number | undefined,
worker: boolean,
clockOffset?: string
) {
if (clockOffset) epochOffset = BigInt(clockOffset)
configureReporting(parentId, worker)
}
let importedThrough = 0
export function freshWorkerEvents(events: TraceEvent[]) {
const fresh = events.filter((event) => event.id > importedThrough)
for (const event of fresh)
importedThrough = Math.max(importedThrough, event.id)
return fresh
}
export function replayWorkerEvents(events: TraceEvent[]) {
replayCompleted(events, (event) => ({
start: epochTime(BigInt(event.timestamp) * NS_PER_US),
end: epochTime(BigInt(event.timestamp + event.duration) * NS_PER_US),
}))
}
import { reporter } from './report' import { reporter } from './report'
import type { SpanId, TraceEvent, TraceState } from './types' import type { SpanId, TraceEvent, TraceState } from './types'
import type { ReportingRecord } from './otel-reporting'
let otel: typeof import('./otel') | undefined
if (
process.env.NEXT_RUNTIME !== 'edge' &&
process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING === '1'
) {
otel = require('./otel') as typeof import('./otel')
} else {
otel = undefined
}
const NUM_OF_MICROSEC_IN_NANOSEC = BigInt('1000') const NUM_OF_MICROSEC_IN_NANOSEC = BigInt('1000')
const NUM_OF_MILLISEC_IN_NANOSEC = BigInt('1000000') const NUM_OF_MILLISEC_IN_NANOSEC = BigInt('1000000')
...@@ -29,13 +40,14 @@ interface Attributes { ...@@ -29,13 +40,14 @@ interface Attributes {
export class Span { export class Span {
private name: string private name: string
private reporting?: ReportingRecord
private id: SpanId private id: SpanId
private parentId?: SpanId private parentId?: SpanId
private attrs: { [key: string]: unknown } private attrs: { [key: string]: unknown }
private status: SpanStatus private status: SpanStatus
private now: number private now: number
// Number of nanoseconds since epoch. // Monotonic nanoseconds from process.hrtime.bigint().
private _start: bigint private _start: bigint
constructor({ constructor({
...@@ -43,25 +55,37 @@ export class Span { ...@@ -43,25 +55,37 @@ export class Span {
parentId, parentId,
attrs, attrs,
startTime, startTime,
wallStartTimeMs,
reportingParent,
}: { }: {
name: string name: string
parentId?: SpanId parentId?: SpanId
startTime?: bigint startTime?: bigint
wallStartTimeMs?: number
attrs?: Attributes attrs?: Attributes
reportingParent?: ReportingRecord
}) { }) {
this.name = name this.id = getId()
this.parentId = parentId ?? defaultParentSpanId this.parentId = parentId ?? defaultParentSpanId
this.name = name
this.attrs = attrs ? { ...attrs } : {} this.attrs = attrs ? { ...attrs } : {}
this.status = SpanStatus.Started this.status = SpanStatus.Started
this.id = getId()
this._start = startTime || process.hrtime.bigint() this._start = startTime || process.hrtime.bigint()
// hrtime cannot be used to reconstruct tracing span's actual start time // hrtime cannot be used to reconstruct tracing span's actual start time
// since it does not have relation to clock time: // since it does not have relation to clock time:
// `These times are relative to an arbitrary time in the past, and not related to the time of day and therefore not subject to clock drift` // `These times are relative to an arbitrary time in the past, and not related to the time of day and therefore not subject to clock drift`
// https://nodejs.org/api/process.html#processhrtimetime // https://nodejs.org/api/process.html#processhrtimetime
// Capturing current datetime as additional metadata for external reconstruction. // Capturing current datetime as additional metadata for external reconstruction.
this.now = Date.now() this.now = wallStartTimeMs ?? Date.now()
this.reporting = otel?.startSpan({
name,
id: this.id,
parentId: this.parentId,
attrs: this.attrs,
startTime: this._start,
reportingParent,
})
} }
// Durations are reported as microseconds. This gives 1000x the precision // Durations are reported as microseconds. This gives 1000x the precision
...@@ -90,16 +114,25 @@ export class Span { ...@@ -90,16 +114,25 @@ export class Span {
tags: this.attrs, tags: this.attrs,
startTime: this.now, startTime: this.now,
} }
try {
if (duration > RECORD_SPAN_THRESHOLD_MS * 1000) { if (duration > RECORD_SPAN_THRESHOLD_MS * 1000) {
reporter.report(traceEvent) reporter.report(traceEvent)
if (shouldSaveTraceEvents) { if (shouldSaveTraceEvents) {
savedTraceEvents.push(traceEvent) savedTraceEvents.push(traceEvent)
} }
} }
} finally {
otel?.stopSpan(this.reporting, end)
}
} }
traceChild(name: string, attrs?: Attributes) { traceChild(name: string, attrs?: Attributes) {
return new Span({ name, parentId: this.id, attrs }) return new Span({
name,
parentId: this.id,
attrs,
reportingParent: this.reporting,
})
} }
manualTraceChild( manualTraceChild(
...@@ -117,6 +150,7 @@ export class Span { ...@@ -117,6 +150,7 @@ export class Span {
name, name,
parentId: this.id, parentId: this.id,
attrs, attrs,
reportingParent: this.reporting,
startTime: startTime ? startTime + correction : process.hrtime.bigint(), startTime: startTime ? startTime + correction : process.hrtime.bigint(),
}) })
span.stop(stopTime ? stopTime + correction : process.hrtime.bigint()) span.stop(stopTime ? stopTime + correction : process.hrtime.bigint())
...@@ -128,13 +162,14 @@ export class Span { ...@@ -128,13 +162,14 @@ export class Span {
setAttribute(key: string, value: unknown) { setAttribute(key: string, value: unknown) {
this.attrs[key] = value this.attrs[key] = value
otel?.updateReporting(this.reporting, key, value)
} }
traceFn<T>(fn: (span: Span) => T): T { traceFn<T>(fn: (span: Span) => T): T {
try { try {
return fn(this) return fn(this)
} catch (e) { } catch (e) {
this.attrs['failed'] = true this.setAttribute('failed', true)
throw e throw e
} finally { } finally {
this.stop() this.stop()
...@@ -145,7 +180,7 @@ export class Span { ...@@ -145,7 +180,7 @@ export class Span {
try { try {
return await fn(this) return await fn(this)
} catch (e) { } catch (e) {
this.attrs['failed'] = true this.setAttribute('failed', true)
throw e throw e
} finally { } finally {
this.stop() this.stop()
...@@ -176,11 +211,23 @@ export const exportTraceState = (): TraceState => ({ ...@@ -176,11 +211,23 @@ export const exportTraceState = (): TraceState => ({
defaultParentSpanId, defaultParentSpanId,
lastId: count, lastId: count,
shouldSaveTraceEvents, shouldSaveTraceEvents,
...(otel
? {
otelClockOffset: otel.getClockOffset(),
}
: {}),
}) })
export const initializeTraceState = (state: TraceState) => { export const initializeTraceState = (state: TraceState) => {
count = state.lastId count = state.lastId
defaultParentSpanId = state.defaultParentSpanId defaultParentSpanId = state.defaultParentSpanId
shouldSaveTraceEvents = state.shouldSaveTraceEvents shouldSaveTraceEvents = state.shouldSaveTraceEvents
if (otel) {
otel.configureState(
defaultParentSpanId,
!!shouldSaveTraceEvents,
state.otelClockOffset
)
}
} }
export function getTraceEvents(): TraceEvent[] { export function getTraceEvents(): TraceEvent[] {
...@@ -188,6 +235,7 @@ export function getTraceEvents(): TraceEvent[] { ...@@ -188,6 +235,7 @@ export function getTraceEvents(): TraceEvent[] {
} }
export function recordTraceEvents(events: TraceEvent[]) { export function recordTraceEvents(events: TraceEvent[]) {
if (otel) events = otel.freshWorkerEvents(events)
for (const traceEvent of events) { for (const traceEvent of events) {
reporter.report(traceEvent) reporter.report(traceEvent)
if (traceEvent.id > count) { if (traceEvent.id > count) {
...@@ -197,6 +245,7 @@ export function recordTraceEvents(events: TraceEvent[]) { ...@@ -197,6 +245,7 @@ export function recordTraceEvents(events: TraceEvent[]) {
if (shouldSaveTraceEvents) { if (shouldSaveTraceEvents) {
savedTraceEvents.push(...events) savedTraceEvents.push(...events)
} }
otel?.replayWorkerEvents(events)
} }
export const clearTraceEvents = () => (savedTraceEvents = []) export const clearTraceEvents = () => (savedTraceEvents = [])
......
...@@ -4,6 +4,8 @@ export interface TraceState { ...@@ -4,6 +4,8 @@ export interface TraceState {
lastId: number lastId: number
defaultParentSpanId?: SpanId defaultParentSpanId?: SpanId
shouldSaveTraceEvents?: boolean shouldSaveTraceEvents?: boolean
/** Shared monotonic-to-epoch mapping for app-tracer worker replay. */
otelClockOffset?: string
} }
export type TraceEvent = { export type TraceEvent = {
......
...@@ -154,6 +154,9 @@ importers: ...@@ -154,6 +154,9 @@ importers:
'@opentelemetry/api': '@opentelemetry/api':
specifier: 1.4.1 specifier: 1.4.1
version: 1.4.1 version: 1.4.1
'@opentelemetry/sdk-trace':
specifier: 2.12.0
version: 2.12.0(@opentelemetry/api@1.4.1)
'@picocss/pico': '@picocss/pico':
specifier: 1.5.10 specifier: 1.5.10
version: 1.5.10 version: 1.5.10
...@@ -5524,10 +5527,32 @@ packages: ...@@ -5524,10 +5527,32 @@ packages:
peerDependencies: peerDependencies:
'@opentelemetry/api': '>=1.0.0 <1.5.0' '@opentelemetry/api': '>=1.0.0 <1.5.0'
'@opentelemetry/core@2.12.0':
resolution: {integrity: sha512-1HsSAuvT4/my0QrXWsyXFdWjKaPeCHsismKZgEEIb8NK13LP6DrMRlsUbvD/0F9mDWK3xDom9AMv3IscxgOnOQ==}
engines: {node: ^18.19.0 || >=20.6.0}
peerDependencies:
'@opentelemetry/api': '>=1.0.0 <1.10.0'
'@opentelemetry/resources@2.12.0':
resolution: {integrity: sha512-+rSRoOdln6NhXTVcBdHSlZxJDNzwxadeweK2ltZO3tVtfp6aklABc06xclDk6ovRR+EiGgIcSbh/6NgjFhnb3A==}
engines: {node: ^18.19.0 || >=20.6.0}
peerDependencies:
'@opentelemetry/api': '>=1.3.0 <1.10.0'
'@opentelemetry/sdk-trace@2.12.0':
resolution: {integrity: sha512-ImVuRQ6faOsTi1Wna88s2avgrrf/iDgXPigIeynkUhjstMuoQUDOJXgkez2j1mlU4btjXcXBGa+q7qKFYR3GsA==}
engines: {node: ^18.19.0 || >=20.6.0}
peerDependencies:
'@opentelemetry/api': '>=1.3.0 <1.10.0'
'@opentelemetry/semantic-conventions@1.15.2': '@opentelemetry/semantic-conventions@1.15.2':
resolution: {integrity: sha512-CjbOKwk2s+3xPIMcd5UNYQzsf+v94RczbdNix9/kQh38WiQkM90sUOi3if8eyHFgiBjBjhwXrA7W3ydiSQP9mw==} resolution: {integrity: sha512-CjbOKwk2s+3xPIMcd5UNYQzsf+v94RczbdNix9/kQh38WiQkM90sUOi3if8eyHFgiBjBjhwXrA7W3ydiSQP9mw==}
engines: {node: '>=14'} engines: {node: '>=14'}
'@opentelemetry/semantic-conventions@1.43.0':
resolution: {integrity: sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==}
engines: {node: '>=14'}
'@picocss/pico@1.5.10': '@picocss/pico@1.5.10':
resolution: {integrity: sha512-+LafMsrwPxXQMk6sI///TmSInCwwZmq+K7SikyL3N/4GhhwzyPC+TQLUEqmrLyjluR+uIpFFcqjty30Rtr6GxQ==} resolution: {integrity: sha512-+LafMsrwPxXQMk6sI///TmSInCwwZmq+K7SikyL3N/4GhhwzyPC+TQLUEqmrLyjluR+uIpFFcqjty30Rtr6GxQ==}
...@@ -22793,8 +22818,28 @@ snapshots: ...@@ -22793,8 +22818,28 @@ snapshots:
'@opentelemetry/api': 1.6.0 '@opentelemetry/api': 1.6.0
'@opentelemetry/semantic-conventions': 1.15.2 '@opentelemetry/semantic-conventions': 1.15.2
'@opentelemetry/core@2.12.0(@opentelemetry/api@1.4.1)':
dependencies:
'@opentelemetry/api': 1.4.1
'@opentelemetry/semantic-conventions': 1.43.0
'@opentelemetry/resources@2.12.0(@opentelemetry/api@1.4.1)':
dependencies:
'@opentelemetry/api': 1.4.1
'@opentelemetry/core': 2.12.0(@opentelemetry/api@1.4.1)
'@opentelemetry/semantic-conventions': 1.43.0
'@opentelemetry/sdk-trace@2.12.0(@opentelemetry/api@1.4.1)':
dependencies:
'@opentelemetry/api': 1.4.1
'@opentelemetry/core': 2.12.0(@opentelemetry/api@1.4.1)
'@opentelemetry/resources': 2.12.0(@opentelemetry/api@1.4.1)
'@opentelemetry/semantic-conventions': 1.43.0
'@opentelemetry/semantic-conventions@1.15.2': {} '@opentelemetry/semantic-conventions@1.15.2': {}
'@opentelemetry/semantic-conventions@1.43.0': {}
'@picocss/pico@1.5.10': {} '@picocss/pico@1.5.10': {}
'@pkgjs/parseargs@0.11.0': '@pkgjs/parseargs@0.11.0':
...@@ -4,7 +4,10 @@ import { readFileSync } from 'fs' ...@@ -4,7 +4,10 @@ import { readFileSync } from 'fs'
import { createServer } from 'http' import { createServer } from 'http'
import { spawn } from 'child_process' import { spawn } from 'child_process'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
import { parseTraceFile } from '../../../lib/parse-trace-file' import {
expectTraceEventContract,
parseTraceFile,
} from '../../../lib/parse-trace-file'
describe('enabled features in trace', () => { describe('enabled features in trace', () => {
const { next, isNextDev } = nextTestSetup({ const { next, isNextDev } = nextTestSetup({
...@@ -57,7 +60,8 @@ describe('enabled features in trace', () => { ...@@ -57,7 +60,8 @@ describe('enabled features in trace', () => {
}) })
it('should record enabled features on root span', async () => { it('should record enabled features on root span', async () => {
const { eventsByName } = parseTraceFile(tracePath) const { events, eventsByName } = parseTraceFile(tracePath)
expectTraceEventContract(events)
// Verify start-dev-server span has feature tags // Verify start-dev-server span has feature tags
const [startDevServerEvent] = eventsByName.get('start-dev-server') ?? [] const [startDevServerEvent] = eventsByName.get('start-dev-server') ?? []
......
export default async function SlowPage() {
// Give the e2e trace assertion a known lower bound in microseconds.
await new Promise((resolve) => setTimeout(resolve, 200))
return <p>slow page</p>
}
import { nextTestSetup } from 'e2e-utils' import { nextTestSetup } from 'e2e-utils'
import { join } from 'path' import { join } from 'path'
import { existsSync } from 'fs' import { existsSync } from 'fs'
import { parseTraceFile } from '../../../lib/parse-trace-file' import {
expectTraceEventContract,
parseTraceFile,
} from '../../../lib/parse-trace-file'
describe('render-path tracing', () => { describe('render-path tracing', () => {
const { next, isNextDev } = nextTestSetup({ const { next, isNextDev } = nextTestSetup({
files: __dirname, files: __dirname,
env: {
// Give the child time to flush response-close spans before SIGKILL.
NEXT_EXIT_TIMEOUT_MS: '30000',
},
}) })
if (!isNextDev) { if (!isNextDev) {
...@@ -13,34 +20,56 @@ describe('render-path tracing', () => { ...@@ -13,34 +20,56 @@ describe('render-path tracing', () => {
return return
} }
it('should record render-path events for page requests', async () => { it('records startup, compilation and backdated request spans across an edit', async () => {
const tracePath = join(next.testDir, '.next/dev/trace') const requestStartedAt = Date.now()
expect((await next.render$('/'))('p').text()).toBe('hello world')
// Trigger page request if trace doesn't exist yet await next.patchFile('app/page.tsx', (content) =>
if (!existsSync(tracePath)) { content.replace('hello world', 'hello after edit')
const browser = await next.browser('/') )
expect(await browser.elementByCss('p').text()).toBe('hello world') expect((await next.render$('/'))('p').text()).toBe('hello after edit')
await browser.close() expect((await next.render$('/slow'))('p').text()).toBe('slow page')
await next.stop('SIGTERM') const requestFinishedAt = Date.now()
await new Promise((resolve) => setTimeout(resolve, 500))
}
const traceStructure = parseTraceFile(tracePath)
// Check for render-path events // File existence alone is not evidence of request tracing: it may already
const renderPathEvents = traceStructure.eventsByName.get('render-path') // contain compilation spans. Stopping also flushes the response-close tail.
expect(renderPathEvents).toBeDefined() await next.stop('SIGTERM')
expect(renderPathEvents!.length).toBeGreaterThan(0) const { events, eventsByName } = parseTraceFile(
join(next.testDir, '.next/dev/trace')
)
expectTraceEventContract(events)
expect(existsSync(join(next.testDir, '.next/dev/trace-build'))).toBe(false)
// Verify the first render-path event has expected attributes const startup = eventsByName.get('start-dev-server') ?? []
const renderEvent = renderPathEvents![0] expect(startup).toHaveLength(1)
expect(renderEvent.tags).toBeDefined() expect(startup[0].parentId).toBeUndefined()
const renderTags = renderEvent.tags as any expect(eventsByName.get('compile-path')?.length).toBeGreaterThan(0)
expect(renderTags.path).toBeDefined() const slowRender = eventsByName
expect(typeof renderTags.path).toBe('string') .get('render-path')
?.find((event) => event.tags?.path === '/slow')
expect(slowRender).toBeDefined()
// A deliberately delayed render distinguishes microseconds from ms/ns.
expect(slowRender!.duration).toBeGreaterThanOrEqual(150_000)
expect(slowRender!.duration / 1000).toBeLessThanOrEqual(
requestFinishedAt - requestStartedAt + 10
)
// Verify render event has valid duration const renderEvents = eventsByName
expect(renderEvent.duration).toBeGreaterThan(0) .get('render-path')
?.filter((event) => event.tags?.path === '/')
expect(renderEvents?.length).toBeGreaterThanOrEqual(2)
for (const event of renderEvents!) {
expect(event.parentId).toBe(startup[0].id)
expect(event.traceId).toBe(startup[0].traceId)
expect(event.duration).toBeGreaterThan(0)
// manualTraceChild must preserve when rendering began, not the time at
// which the completed request is later recorded/exported.
expect(event.startTime).toBeGreaterThanOrEqual(requestStartedAt - 10)
expect(event.startTime).toBeLessThanOrEqual(requestFinishedAt)
expect(event.duration / 1000).toBeLessThanOrEqual(
requestFinishedAt - requestStartedAt + 10
)
}
}) })
}) })
...@@ -3,7 +3,10 @@ import { join, dirname } from 'node:path' ...@@ -3,7 +3,10 @@ import { join, dirname } from 'node:path'
import { execSync } from 'node:child_process' import { execSync } from 'node:child_process'
import { getCacheDirectory } from 'next/dist/lib/helpers/get-cache-directory' import { getCacheDirectory } from 'next/dist/lib/helpers/get-cache-directory'
import { nextTestSetup } from 'e2e-utils' import { nextTestSetup } from 'e2e-utils'
import { parseTraceFile } from '../../../lib/parse-trace-file' import {
expectTraceEventContract,
parseTraceFile,
} from '../../../lib/parse-trace-file'
describe('rage restart trace attributes', () => { describe('rage restart trace attributes', () => {
// Use a fake upload URL so traceUploadUrl is set and detection runs. // Use a fake upload URL so traceUploadUrl is set and detection runs.
...@@ -14,6 +17,7 @@ describe('rage restart trace attributes', () => { ...@@ -14,6 +17,7 @@ describe('rage restart trace attributes', () => {
files: __dirname, files: __dirname,
skipStart: true, skipStart: true,
startArgs: ['--experimental-upload-trace', fakeUploadUrl], startArgs: ['--experimental-upload-trace', fakeUploadUrl],
env: { NEXT_EXIT_TIMEOUT_MS: '30000' },
}) })
if (!isNextDev) { if (!isNextDev) {
...@@ -34,10 +38,11 @@ describe('rage restart trace attributes', () => { ...@@ -34,10 +38,11 @@ describe('rage restart trace attributes', () => {
const getStartDevServerSpan = () => { const getStartDevServerSpan = () => {
const traceStructure = parseTraceFile(getTracePath()) const traceStructure = parseTraceFile(getTracePath())
expectTraceEventContract(traceStructure.events)
const spans = traceStructure.eventsByName.get('start-dev-server') const spans = traceStructure.eventsByName.get('start-dev-server')
expect(spans).toBeDefined() expect(spans).toBeDefined()
expect(spans?.length).toBeGreaterThan(0) expect(spans?.length).toBeGreaterThan(0)
// Trace file is appended across restarts; take the most recent span. // Select the most recent startup event in the current trace file.
return spans?.[spans.length - 1] return spans?.[spans.length - 1]
} }
...@@ -56,12 +61,23 @@ describe('rage restart trace attributes', () => { ...@@ -56,12 +61,23 @@ describe('rage restart trace attributes', () => {
await next.start() await next.start()
await next.render$('/') await next.render$('/')
await next.stop('SIGTERM') await next.stop('SIGTERM')
const firstSession = parseTraceFile(getTracePath()).events
const firstSessionId = firstSession[0].traceId
// Second session: restart immediately — should be detected as a rage restart. // Second session: restart immediately — should be detected as a rage restart.
await next.start() await next.start()
await next.render$('/') await next.render$('/')
await next.stop('SIGTERM') await next.stop('SIGTERM')
const restarted = parseTraceFile(getTracePath()).events
// The writer uses append mode, but normal dev startup cleans the old trace.
// Preserve this observable behavior in both tracing implementations.
expect(
restarted.filter((event) => event.traceId === firstSessionId)
).toHaveLength(0)
expect(restarted.some((event) => event.traceId !== firstSessionId)).toBe(
true
)
const span = getStartDevServerSpan() const span = getStartDevServerSpan()
expect(span?.tags?.['rage-restart']).toBe(true) expect(span?.tags?.['rage-restart']).toBe(true)
expect(span?.tags?.['missing-next-dir']).toBe(false) expect(span?.tags?.['missing-next-dir']).toBe(false)
......
import type { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <p>hello world</p>
}
import { trace } from '@opentelemetry/api'
import {
AlwaysOffSampler,
AlwaysOnSampler,
BatchSpanProcessor,
TracerProvider,
} from '@opentelemetry/sdk-trace'
import type { SpanExporter } from '@opentelemetry/sdk-trace'
import { readFileSync } from 'node:fs'
let registrations = 0
let provider: TracerProvider
let registeredProvider: ReturnType<typeof trace.getTracerProvider>
async function send(body: unknown) {
const response = await fetch(process.env.TOOLING_ENDPOINT!, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
})
if (!response.ok) throw new Error('Test collector rejected traces')
}
export async function register() {
if (process.env.NEXT_RUNTIME !== 'nodejs') return
registrations++
const exporter: SpanExporter = {
export(spans, callback) {
void send({
kind: 'spans',
pid: process.pid,
spans: spans.map((span) => ({
name: span.name,
traceId: span.spanContext().traceId,
spanId: span.spanContext().spanId,
parentSpanId: span.parentSpanContext?.spanId,
startTime: span.startTime,
endTime: span.endTime,
attributes: span.attributes,
})),
}).then(
() => callback({ code: 0 }),
(error) => callback({ code: 1, error })
)
},
async shutdown() {},
}
provider = new TracerProvider({
sampler:
process.env.TOOLING_SAMPLER === 'off'
? new AlwaysOffSampler()
: new AlwaysOnSampler(),
spanProcessors: [
new BatchSpanProcessor({
exporter,
maxQueueSize: 20000,
maxExportBatchSize: 1000,
}),
],
})
const installed = trace.setGlobalTracerProvider(provider)
registeredProvider = trace.getTracerProvider()
await send({
kind: 'register',
pid: process.pid,
phase: process.env.NEXT_PHASE,
installed,
registrations,
time: Date.now(),
})
}
export async function flushTraces() {
// This assertion is deliberately in the application hook: it proves ordering
// at the real process boundary, not just after the test has stopped Next.
const lines = readFileSync(process.env.TOOLING_TRACE_FILE!, 'utf8')
.trim()
.split('\n')
const events = lines.flatMap((line) => JSON.parse(line))
await provider.forceFlush()
await send({
kind: 'flush',
pid: process.pid,
registrations,
identityStable: trace.getTracerProvider() === registeredProvider,
localHasRoot: events.some(
(event) =>
event.name ===
(process.env.NEXT_PHASE === 'phase-production-build'
? 'next-build'
: 'start-dev-server')
),
})
}
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
await (await import('./instrumentation-node')).register()
}
}
export async function flushTraces() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
await (await import('./instrumentation-node')).flushTraces()
}
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = { distDir: 'otel-output' }
export default nextConfig
This diff is collapsed.
...@@ -23,6 +23,54 @@ export function parseTraceEvents(tracePath: string): TraceEvent[] { ...@@ -23,6 +23,54 @@ export function parseTraceEvents(tracePath: string): TraceEvent[] {
return allEvents return allEvents
} }
/**
* The on-disk tooling trace contract, shared by legacy and OTel-backed e2e tests.
* Compare within each session: development appends sessions whose numeric IDs
* can start over, and intentionally filtered/unfinished parents may be absent.
*/
export function expectTraceEventContract(events: TraceEvent[]): void {
expect(events.length).toBeGreaterThan(0)
const sessions = new Map<string, TraceEvent[]>()
for (const event of events) {
expect(typeof event.name).toBe('string')
expect(event.name.length).toBeGreaterThan(0)
expect(Number.isSafeInteger(event.id)).toBe(true)
expect(event.id).toBeGreaterThan(0)
if (event.parentId !== undefined) {
expect(Number.isSafeInteger(event.parentId)).toBe(true)
expect(event.parentId).toBeGreaterThan(0)
expect(event.parentId).not.toBe(event.id)
}
expect(Number.isSafeInteger(event.timestamp)).toBe(true)
expect(event.timestamp).toBeGreaterThanOrEqual(0)
expect(Number.isSafeInteger(event.duration)).toBe(true)
expect(event.duration).toBeGreaterThanOrEqual(0)
expect(Number.isSafeInteger(event.startTime)).toBe(true)
expect(event.startTime).toBeGreaterThan(1_000_000_000_000)
// `timestamp` is monotonic microseconds, not epoch microseconds.
expect(event.timestamp).toBeLessThan(event.startTime! * 1000)
expect(event.tags).toEqual(expect.any(Object))
expect(typeof event.traceId).toBe('string')
expect(event.traceId!.length).toBeGreaterThan(0)
const session = sessions.get(event.traceId!) ?? []
session.push(event)
sessions.set(event.traceId!, session)
}
for (const session of sessions.values()) {
expect(new Set(session.map((event) => event.id)).size).toBe(session.length)
const reference = session[0]
for (const event of session) {
// The independent wall clock is only millisecond precision. This also
// catches accidentally reporting a timestamp in ms instead of µs.
const wallDeltaUs = (event.startTime! - reference.startTime!) * 1000
const monotonicDeltaUs = event.timestamp - reference.timestamp
expect(Math.abs(wallDeltaUs - monotonicDeltaUs)).toBeLessThan(10_000)
}
}
}
/** /**
* Parses a Next.js trace file and returns a structured representation * Parses a Next.js trace file and returns a structured representation
* with events indexed by name and id, plus root/orphaned classification. * with events indexed by name and id, plus root/orphaned classification.
......
import type { ReadableSpan } from '@opentelemetry/sdk-trace'
import type { TraceEvent } from '../../packages/next/src/trace/types'
// Replay is an ordering/bounded-storage algorithm. Keep its edge cases here;
// file compatibility and actual process lifecycle are covered by the e2e suites.
describe('tooling OTel replay', () => {
const previousGate = process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING
// Use emitted package types; the root test TS project does not load the
// framework's internal ambient declarations for the reporter's dependencies.
let tracing: typeof import('next/dist/trace/trace')
let api: typeof import('@opentelemetry/api')
let sdk: typeof import('@opentelemetry/sdk-trace')
let backend: typeof import('../../packages/next/src/trace/otel')
let reporting: typeof import('../../packages/next/src/trace/otel-reporting')
let local: TraceEvent[]
let exported: ReadableSpan[]
beforeEach(() => {
jest.resetModules()
api = require('next/dist/compiled/@opentelemetry/api')
api.trace.disable()
local = []
exported = []
process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING = '1'
jest.doMock('../../packages/next/src/trace/report', () => ({
reporter: { report: (event: TraceEvent) => local.push(event) },
}))
sdk = require('@opentelemetry/sdk-trace')
backend = require('../../packages/next/src/trace/otel')
reporting = require('../../packages/next/src/trace/otel-reporting')
tracing = require('../../packages/next/src/trace/trace')
})
afterEach(() => {
if (previousGate === undefined)
delete process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING
else process.env.NEXT_EXPERIMENTAL_OTEL_TOOLING = previousGate
jest.dontMock('../../packages/next/src/trace/report')
api.trace.disable()
api.context.disable()
jest.restoreAllMocks()
jest.useRealTimers()
})
function installApplicationProvider(sample = true) {
const provider = new sdk.TracerProvider({
sampler: sample ? new sdk.AlwaysOnSampler() : new sdk.AlwaysOffSampler(),
spanProcessors: [
{
onStart() {},
onEnd(span) {
exported.push(span)
},
async forceFlush() {},
async shutdown() {},
},
],
})
// Local recording must not register any provider of its own.
expect(api.trace.setGlobalTracerProvider(provider)).toBe(true)
return api.trace.getTracerProvider()
}
function span(
id: number,
parentId?: number,
reportingParent?: InstanceType<typeof tracing.Span>
) {
return reportingParent
? reportingParent.traceChild(`operation-${id}`)
: new tracing.Span({ name: `operation-${id}`, parentId })
}
function stopSpan(state: InstanceType<typeof tracing.Span>, end?: bigint) {
state.stop(end)
}
it('preserves original local timing, arbitrary tags, errors and idempotent end', () => {
installApplicationProvider()
const start = process.hrtime.bigint()
const tags = Object.fromEntries(
Array.from({ length: 200 }, (_, i) => [`tag-${i}`, i])
)
const state = new tracing.Span({
name: 'backdated',
startTime: start,
wallStartTimeMs: 1_700_000_000_000,
attrs: tags,
})
state.setAttribute('structured', {
unicode: '世界',
values: [1, 2],
})
state.setAttribute('failed', true)
stopSpan(state, start + BigInt(543_000))
stopSpan(state)
backend.enableReporting()
expect(local).toHaveLength(1)
expect(local[0]).toMatchObject({
id: 1,
timestamp: Number(start / BigInt(1000)),
duration: 543,
startTime: 1_700_000_000_000,
})
expect(local[0].tags).toMatchObject({
...tags,
failed: true,
structured: { unicode: '世界', values: [1, 2] },
})
expect(exported).toHaveLength(1)
expect(exported[0].status.code).toBe(api.SpanStatusCode.ERROR)
expect(exported[0].duration).toEqual([0, 543_000])
expect(exported[0].attributes['next.tooling.id']).toBe(1)
})
it('joins early, live and later children to the same ended startup parent without changing active context', () => {
const root = span(1)
backend.configureState(1, false)
const early = span(2, 1, root)
stopSpan(early)
const provider = installApplicationProvider()
const contextManager = new sdk.StackContextManager()
api.context.setGlobalContextManager(contextManager)
const key = api.createContextKey('tooling-replay-test')
const context = api.ROOT_CONTEXT.setValue(key, 'application')
api.context.with(context, () => {
backend.enableReporting()
backend.enableReporting()
stopSpan(root)
stopSpan(span(3, 1, root))
stopSpan(span(4, 1))
expect(api.context.active().getValue(key)).toBe('application')
expect(api.trace.getTracerProvider()).toBe(provider)
})
expect(exported).toHaveLength(4)
const parent = exported.find((entry) => entry.name === 'operation-1')!
for (const child of exported.filter((entry) => entry !== parent)) {
expect(child.parentSpanContext?.spanId).toBe(parent.spanContext().spanId)
}
})
it('preserves the original numeric parent while falling back to the known reporting root', () => {
const root = span(1)
backend.configureState(1, false)
stopSpan(span(2, 1, root))
installApplicationProvider()
backend.enableReporting()
stopSpan(root)
stopSpan(span(3, 2))
const parent = exported.find((entry) => entry.name === 'operation-1')!
const later = exported.find((entry) => entry.name === 'operation-3')!
expect(later.parentSpanContext?.spanId).toBe(parent.spanContext().spanId)
expect(later.attributes['next.tooling.parent_id']).toBe(2)
expect(local.find((entry) => entry.id === 3)?.parentId).toBe(2)
})
it('retains local records when the application sampler drops every span', () => {
installApplicationProvider(false)
backend.enableReporting()
stopSpan(span(1))
expect(local).toHaveLength(1)
expect(exported).toHaveLength(0)
})
it('replays completion-ordered worker records once under the live coordinator root', () => {
const root = span(1)
const timestamp = Number(process.hrtime.bigint() / BigInt(1000))
const records: TraceEvent[] = [
{ id: 3, parentId: 2, name: 'worker-leaf', timestamp, duration: 10 },
{ id: 2, parentId: 1, name: 'worker-parent', timestamp, duration: 20 },
]
backend.replayWorkerEvents(backend.freshWorkerEvents(records))
expect(backend.freshWorkerEvents(records)).toEqual([])
installApplicationProvider()
backend.enableReporting()
stopSpan(root)
expect(exported).toHaveLength(3)
const parent = exported.find((entry) => entry.name === 'worker-parent')!
const leaf = exported.find((entry) => entry.name === 'worker-leaf')!
const coordinator = exported.find((entry) => entry.name === 'operation-1')!
expect(parent.parentSpanContext?.spanId).toBe(
coordinator.spanContext().spanId
)
expect(leaf.parentSpanContext?.spanId).toBe(parent.spanContext().spanId)
})
it('bounds event-count replay, warns once, and never drops local diagnostics', () => {
const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
for (let id = 1; id <= reporting.REPLAY_EVENT_LIMIT + 2; id++)
stopSpan(span(id))
installApplicationProvider()
backend.enableReporting()
expect(local).toHaveLength(reporting.REPLAY_EVENT_LIMIT + 2)
expect(exported).toHaveLength(reporting.REPLAY_EVENT_LIMIT)
expect(warn).toHaveBeenCalledTimes(1)
})
it('bounds retained data size independently of event count', () => {
const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
stopSpan(span(1))
const state = new tracing.Span({
name: 'oversized',
attrs: { large: 'x'.repeat(reporting.REPLAY_BYTE_LIMIT) },
})
stopSpan(state)
installApplicationProvider()
backend.enableReporting()
expect(local).toHaveLength(2)
expect(local[1].tags!.large).toHaveLength(reporting.REPLAY_BYTE_LIMIT)
expect(exported).toHaveLength(1)
expect(warn).toHaveBeenCalledTimes(1)
})
it('does not export separately from compiler workers', () => {
backend.configureState(1, true)
installApplicationProvider()
stopSpan(span(2, 1))
backend.enableReporting()
expect(local).toHaveLength(1)
expect(exported).toHaveLength(0)
})
it.each(['missing', 'synchronous'])(
'supports a %s cooperative hook',
async (kind) => {
const hook = jest.fn()
backend.enableReporting(kind === 'missing' ? undefined : hook)
await backend.flushReporting()
expect(hook).toHaveBeenCalledTimes(kind === 'missing' ? 0 : 1)
}
)
it('treats a rejecting flush hook as a nonfatal diagnostic', async () => {
const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
backend.enableReporting(async () => {
throw new Error('export failed')
})
await expect(backend.flushReporting()).resolves.toBeUndefined()
expect(warn).toHaveBeenCalledTimes(1)
})
it('bounds a hanging flush hook and clears its timeout', async () => {
jest.useFakeTimers()
const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
backend.enableReporting(() => new Promise(() => {}))
const flush = backend.flushReporting()
await jest.advanceTimersByTimeAsync(reporting.FLUSH_TIMEOUT_MS)
await expect(flush).resolves.toBeUndefined()
expect(warn).toHaveBeenCalledTimes(1)
expect(jest.getTimerCount()).toBe(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