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

Record Instant Insights validation worker spans

Co-authored-by: 's avatarDavid Ilie <david@davidilie.com>
Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent fff74ebf
......@@ -184,6 +184,16 @@ describe('request insights trace viewer', () => {
'next.span_type': 'AppRender.instantInsights.runValidation',
},
},
...['warmup', 'staticShell', 'validate'].map((phase, index) => ({
name: phase,
spanId: `phase-${phase}`,
parentSpanId: 'validate',
startTime: 126 + index,
durationMs: 1,
attributes: {
'next.span_type': `AppRender.instantInsights.${phase}`,
},
})),
],
})
......@@ -196,6 +206,9 @@ describe('request insights trace viewer', () => {
{ label: 'Instant Insights', depth: 0 },
{ label: 'Prepare validation inputs', depth: 1 },
{ label: 'Run validation', depth: 1 },
{ label: 'warmup', depth: 2 },
{ label: 'static shell', depth: 2 },
{ label: 'validate', depth: 2 },
])
})
......
......@@ -45,6 +45,9 @@ const DEFAULT_VISIBLE_SPAN_TYPES = new Set([
'AppRender.instantInsights',
'AppRender.instantInsights.prepareValidation',
'AppRender.instantInsights.runValidation',
'AppRender.instantInsights.warmup',
'AppRender.instantInsights.staticShell',
'AppRender.instantInsights.validate',
FETCH_SPAN_TYPE,
'NextNodeServer.waitForFirstResponseChunk',
'NextNodeServer.startResponse',
......
......@@ -117,8 +117,15 @@ import {
runWithRequestInsightsIdentity,
} from '../lib/trace/request-insights-identity'
import { getTracer, SpanStatusCode } from '../lib/trace/tracer'
import { traceLocalSpan } from '../lib/trace/local-span-recorder'
import { isRequestInsightsEnabled } from '../lib/trace/request-insights'
import {
getActiveLocalSpan,
isLocalSpanRecordingEnabled,
traceLocalSpan,
} from '../lib/trace/local-span-recorder'
import {
importRequestInsightSpans,
isRequestInsightsEnabled,
} from '../lib/trace/request-insights'
import { FlightRenderResult } from './flight-render-result'
import {
createReactServerErrorHandler,
......@@ -4844,6 +4851,9 @@ function runDevValidationInBackground(
const devValidationWorker = getDevValidationWorker()
if (devValidationWorker) {
const runValidationSpan = getActiveLocalSpan()
const runValidationSpanContext = runValidationSpan?.spanContext()
const requestInsightsIdentity = getRequestInsightsIdentity()
const snapshot = await buildDevValidationSnapshot(
ctx,
instantInputs,
......@@ -4853,15 +4863,42 @@ function runDevValidationInBackground(
devRenderDidError
)
const chunks = await devValidationWorker(
const workerResult = await devValidationWorker(
snapshot,
validationAbortSignal
validationAbortSignal,
{
captureLocalSpans: Boolean(
runValidationSpanContext && requestInsightsIdentity
),
}
)
// A newer navigation may have superseded this validation while
// the worker ran; don't surface stale insights for a page the user
// left.
if (chunks && !validationAbortSignal.aborted) {
if (!validationAbortSignal.aborted) {
if (
workerResult.localSpans &&
runValidationSpanContext &&
requestInsightsIdentity
) {
importRequestInsightSpans(
requestInsightsIdentity,
runValidationSpanContext,
workerResult.localSpans
)
if (workerResult.localSpans.droppedSpanCount > 0) {
runValidationSpan?.setAttribute(
'next.request_insights.omitted_spans',
workerResult.localSpans.droppedSpanCount
)
}
}
const chunks = workerResult.chunks
if (!chunks) {
return
}
const { sendErrorsToBrowser } = ctx.renderOpts
if (!sendErrorsToBrowser) {
throw new InvariantError(
......@@ -6774,6 +6811,9 @@ async function runValidationInDev(
devRenderDidError: boolean,
validationAbortSignal: AbortSignal
): Promise<Array<unknown> | undefined> {
const runSpan = isLocalSpanRecordingEnabled()
? runInstantInsightsSpan
: runWithoutInstantInsightsSpan
const { componentMod: ComponentMod, getDynamicParamFromSegment } = ctx
const loaderTree = ComponentMod.routeModule.userland.loaderTree
const rootParams = getRootParams(loaderTree, getDynamicParamFromSegment)
......@@ -6796,21 +6836,26 @@ async function runValidationInDev(
// First we warmup SSR with the runtime chunks. This ensures that when we do
// the full prerender pass with dynamic tracking module loading won't
// interrupt the prerender and can properly observe the entire content
await warmupClientModulesForStagedValidation(
// if we're going to be validating prefetches, we'll be rendering some segments in the dynamic stage.
// otherwise, for static shell validation, we only need to warm up to the runtime stage.
// we also need to use a different store type, because instant validation allows more APIs to resolve.
needsInstantValidation ? 'validation-client' : 'prerender-client',
needsInstantValidation
? accumulatedChunks[RenderStage.Dynamic]
: accumulatedChunks[RenderStage.Runtime],
accumulatedChunks[RenderStage.Dynamic],
rootParams,
fallbackRouteParams,
ctx,
validationSamples,
validationSampleTracking,
validationAbortSignal
await runSpan(
AppRenderSpan.instantInsightsWarmup,
'Warm up validation modules',
() =>
warmupClientModulesForStagedValidation(
// if we're going to be validating prefetches, we'll be rendering some segments in the dynamic stage.
// otherwise, for static shell validation, we only need to warm up to the runtime stage.
// we also need to use a different store type, because instant validation allows more APIs to resolve.
needsInstantValidation ? 'validation-client' : 'prerender-client',
needsInstantValidation
? accumulatedChunks[RenderStage.Dynamic]
: accumulatedChunks[RenderStage.Runtime],
accumulatedChunks[RenderStage.Dynamic],
rootParams,
fallbackRouteParams,
ctx,
validationSamples,
validationSampleTracking,
validationAbortSignal
)
)
}
......@@ -6853,14 +6898,19 @@ async function runValidationInDev(
: null
const hmrRefreshHash = getHmrRefreshHash(inputs.requestStore)
const result = await validateStaticShell(
inputs,
ctx,
rootParams,
fallbackRouteParams,
debugChunks,
hmrRefreshHash,
validationAbortSignal
const result = await runSpan(
AppRenderSpan.instantInsightsStaticShell,
'Validate static shell',
() =>
validateStaticShell(
inputs,
ctx,
rootParams,
fallbackRouteParams,
debugChunks,
hmrRefreshHash,
validationAbortSignal
)
)
// A newer render superseded this validation while its render ran, so its
// result is stale. Don't surface errors for a page the user left.
......@@ -6890,19 +6940,24 @@ async function runValidationInDev(
: null
const hmrRefreshHash = getHmrRefreshHash(inputs.requestStore)
const result = await validateInstantConfigs(
prefetchMode,
inputs.accumulatedChunks,
debugChunks,
inputs.startTime,
inputs.stageEndTimes,
rootParams,
fallbackRouteParams,
ctx,
hmrRefreshHash,
validationSamples,
devRenderDidError,
validationAbortSignal
const result = await runSpan(
AppRenderSpan.instantInsightsValidate,
'Validate instant navigation',
() =>
validateInstantConfigs(
prefetchMode,
inputs.accumulatedChunks,
debugChunks,
inputs.startTime,
inputs.stageEndTimes,
rootParams,
fallbackRouteParams,
ctx,
hmrRefreshHash,
validationSamples,
devRenderDidError,
validationAbortSignal
)
)
// A newer render superseded this work. Don't surface stale validation
......
......@@ -6,6 +6,7 @@ import type { NextConfigComplete, ValidationLevel } from '../config-shared'
import type { ImageConfigComplete } from '../../shared/lib/image-config'
import type { StageEndTimes } from './instant-validation/instant-validation'
import type { AdvanceableRenderStage } from './staged-rendering'
import type { LocalSpanBatch } from '../lib/trace/span-store'
/**
* Cross-module handoff for the dev validation worker (client-module warmup,
......@@ -132,14 +133,21 @@ export interface DevValidationInstallFields {
* the main-thread snapshot plus the pool's install-time fields.
*/
export type DevValidationWorkerMessage = DevValidationSnapshot &
DevValidationInstallFields
DevValidationInstallFields & {
captureLocalSpans: boolean
}
/**
* The RSC-encoded `{ errors }` Flight chunks for the dev overlay,
* or null when validation produced no errors or was aborted. The worker also
* logs the errors to its own stderr (piped to the parent) with code frames.
* or null when validation produced no errors or was aborted. A completed
* worker trace is returned as one bounded batch for the parent realm to
* consume. The worker also logs errors to its own stderr (piped to the parent)
* with code frames.
*/
export type DevValidationWorkerResult = Uint8Array[] | null
export type DevValidationWorkerResult = {
chunks: Uint8Array[] | null
localSpans: LocalSpanBatch | null
}
/**
* Worker hook installed by the dev server. Given the render snapshot and the
......@@ -152,7 +160,10 @@ export type DevValidationWorkerResult = Uint8Array[] | null
*/
export type DevValidationWorker = (
snapshot: DevValidationSnapshot,
validationAbortSignal: AbortSignal
validationAbortSignal: AbortSignal,
options?: {
captureLocalSpans?: boolean
}
) => Promise<DevValidationWorkerResult>
interface WorkerHolder {
......
......@@ -204,17 +204,21 @@ export function installDevValidationWorker(options: InstallOptions): void {
const runValidation = async (
snapshot: DevValidationSnapshot,
validationAbortSignal: AbortSignal
validationAbortSignal: AbortSignal,
captureOptions?: {
captureLocalSpans?: boolean
}
): Promise<DevValidationWorkerResult> => {
let activePool: ValidationPool
try {
activePool = getPool()
} catch {
return null
return { chunks: null, localSpans: null }
}
const message: DevValidationWorkerMessage = {
...snapshot,
captureLocalSpans: captureOptions?.captureLocalSpans ?? false,
distDir,
buildId,
deploymentId,
......@@ -255,7 +259,7 @@ export function installDevValidationWorker(options: InstallOptions): void {
// Worker crash or IPC error: tear down so the next validation starts
// fresh. The main thread treats a missing result as "nothing to deliver."
await tearDownPool()
return null
return { chunks: null, localSpans: null }
} finally {
// `once` only auto-removes the listener if it fired, so remove it
// explicitly to bound its lifetime to this run when validation completed
......
......@@ -4,6 +4,7 @@ import type {
DevValidationWorkerResult,
} from '../app-render/dev-validation-worker-globals'
import type { NodeJsPartialHmrUpdate } from '../../build/swc/types'
import type { LocalSpanBatch, SpanStoreRecord } from '../lib/trace/span-store'
import '../require-hook'
import '../node-environment'
......@@ -28,6 +29,69 @@ import {
} from '../app-render/manifests-singleton'
import { setBundlerFindSourceMapImplementation } from '../patch-error-inspect'
import type { ModernSourceMapPayload } from '../lib/source-maps'
import { registerLocalSpanRecorder } from '../lib/trace/local-span-recorder'
import { runWithLocalSpanSink } from '../lib/trace/span-store'
// Development runtimes externalize the recorder and span store, so the worker
// and the App Page runtime share one local tracing core. Register sink-only
// policy once for this worker realm; each validation still owns its collector
// through AsyncLocalStorage.
registerLocalSpanRecorder({ sinkOnly: true })
// Bound the worker IPC payload independently from Request Insights retention.
// The count limits per-record serialization/traversal work for many small
// spans, while the byte limit protects against spans with large payloads.
const MAX_WORKER_SPAN_BATCH_COUNT = 256
const MAX_WORKER_SPAN_BATCH_BYTES = 256 * 1024
function createWorkerSpanCollector() {
const spans: SpanStoreRecord[] = []
let serializedByteLength = 2
let droppedSpanCount = 0
let closed = false
return {
record(span: SpanStoreRecord): void {
if (closed) {
return
}
if (spans.length >= MAX_WORKER_SPAN_BATCH_COUNT) {
droppedSpanCount++
return
}
let spanByteLength: number
try {
const serializedSpan = JSON.stringify(span)
if (serializedSpan === undefined) {
droppedSpanCount++
return
}
spanByteLength = Buffer.byteLength(serializedSpan, 'utf8')
} catch {
droppedSpanCount++
return
}
const separatorByteLength = spans.length === 0 ? 0 : 1
if (
serializedByteLength + separatorByteLength + spanByteLength >
MAX_WORKER_SPAN_BATCH_BYTES
) {
droppedSpanCount++
return
}
spans.push(span)
serializedByteLength += separatorByteLength + spanByteLength
},
finish(): LocalSpanBatch {
closed = true
return { spans, droppedSpanCount }
},
}
}
/**
* Resolves a chunk's source map by reading the `.map` file the bundler emitted
......@@ -310,6 +374,56 @@ export async function runDevValidation(
message: DevValidationWorkerMessage,
abortBuffer: SharedArrayBuffer
): Promise<DevValidationWorkerResult> {
const { signal, cleanup } = createSupersedeSignal(abortBuffer)
const collector = message.captureLocalSpans
? createWorkerSpanCollector()
: null
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: 'validation_start',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
responseFinished: message.responseFinished,
})
)
}
try {
const chunks = collector
? await runWithLocalSpanSink(collector.record, () =>
runDevValidationOperation(message, signal)
)
: await runDevValidationOperation(message, signal)
return {
chunks,
// Superseded validation is stale as a whole. Do not import a partial
// worker trace for a page the user has already left.
localSpans: signal.aborted ? null : (collector?.finish() ?? null),
}
} finally {
// Async work can retain the collector after this validation was aborted
// or threw. Close it on those paths too, before reusing the worker.
collector?.finish()
cleanup()
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: signal.aborted ? 'validation_aborted' : 'validation_end',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
})
)
}
}
}
async function runDevValidationOperation(
message: DevValidationWorkerMessage,
signal: AbortSignal
): Promise<Uint8Array[] | null> {
// Load the native SWC bindings and wire the code-frame renderer so the errors
// logged below render with a source-mapped code frame, matching the
// in-process dev output (the E2E tests snapshot the CLI text between the
......@@ -344,67 +458,41 @@ export async function runDevValidation(
message.additionalClientReferenceManifestPages
)
const { signal, cleanup } = createSupersedeSignal(abortBuffer)
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: 'validation_start',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
responseFinished: message.responseFinished,
})
)
await applyTestValidationDelay(signal)
}
try {
if (isTestLoggingEnabled) {
await applyTestValidationDelay(signal)
}
if (signal.aborted) {
return null
}
// Crossing into the app-page bundle: the entire validation runs there, so
// the client prerenders use the same React the user's client components
// resolve through `ComponentMod`.
const validationErrors = await ComponentMod.routeModule.runValidationInDev(
ComponentMod,
message,
signal
)
if (signal.aborted) {
return null
}
if (validationErrors === undefined || signal.aborted) {
return null
}
// Crossing into the app-page bundle: the entire validation runs there, so
// the client prerenders use the same React the user's client components
// resolve through `ComponentMod`.
const validationErrors = await ComponentMod.routeModule.runValidationInDev(
ComponentMod,
message,
signal
)
const errors: Error[] = []
for (const validationError of validationErrors) {
// Log to the worker's stderr; `node-environment` +
// `installCodeFrameSupport` render the source-mapped stack and code frame
// there, matching the in-process CLI output.
console.error(validationError)
if (validationError instanceof Error) {
errors.push(validationError)
}
}
if (validationErrors === undefined || signal.aborted) {
return null
}
if (errors.length === 0) {
return null
const errors: Error[] = []
for (const validationError of validationErrors) {
// Log to the worker's stderr; `node-environment` +
// `installCodeFrameSupport` render the source-mapped stack and code frame
// there, matching the in-process CLI output.
console.error(validationError)
if (validationError instanceof Error) {
errors.push(validationError)
}
}
return await serializeValidationErrorsToFlight(ComponentMod, errors)
} finally {
cleanup()
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: signal.aborted ? 'validation_aborted' : 'validation_end',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
})
)
}
if (errors.length === 0) {
return null
}
return await serializeValidationErrorsToFlight(ComponentMod, errors)
}
......@@ -98,6 +98,9 @@ enum AppRenderSpan {
instantInsights = 'AppRender.instantInsights',
instantInsightsPrepareValidation = 'AppRender.instantInsights.prepareValidation',
instantInsightsRunValidation = 'AppRender.instantInsights.runValidation',
instantInsightsWarmup = 'AppRender.instantInsights.warmup',
instantInsightsStaticShell = 'AppRender.instantInsights.staticShell',
instantInsightsValidate = 'AppRender.instantInsights.validate',
}
enum DevBundlerServiceSpan {
......
......@@ -4,16 +4,19 @@ import type {
SpanContext,
SpanOptions,
} from 'next/dist/compiled/@opentelemetry/api'
import { getOrCreateGlobalAsyncLocalStorage } from '../../app-render/async-local-storage'
import { SpanStatusCode, trace } from 'next/dist/compiled/@opentelemetry/api'
import {
isLocalSpanRecordingEnabled,
isLocalSpanSinkActive,
captureLocalSpanRecorder,
type SpanStoreAttributes,
type SpanStoreEvent,
type SpanStoreLink,
type SpanStoreRecord,
type LocalSpanParent,
} from './span-store'
import type { RequestInsightKind } from '../../../next-devtools/shared/request-insights'
import { getOrCreateGlobalAsyncLocalStorage } from '../../app-render/async-local-storage'
export { isLocalSpanRecordingEnabled } from './span-store'
......@@ -49,16 +52,18 @@ type TraceLocalSpanOptions = Omit<
let lastLocalTraceId = 0
let lastLocalSpanId = 0
type LocalSpanScope = {
span: Span
publicContext: SpanContext | undefined
}
const getLocalTraceId = () =>
(++lastLocalTraceId).toString(16).padStart(TRACE_ID_HEX_LENGTH, '0')
function getLocalTraceId(): string {
return (++lastLocalTraceId).toString(16).padStart(TRACE_ID_HEX_LENGTH, '0')
}
const getLocalSpanId = () =>
(++lastLocalSpanId).toString(16).padStart(SPAN_ID_HEX_LENGTH, '0')
export function createLocalSpanId(excludedId?: string): string {
let spanId: string
do {
spanId = (++lastLocalSpanId).toString(16).padStart(SPAN_ID_HEX_LENGTH, '0')
} while (spanId === excludedId)
return spanId
}
export function createLocalSpan({
name,
......@@ -80,7 +85,7 @@ export function createLocalSpan({
delegateSpan,
publicParentSpan,
traceId: traceId ?? getLocalTraceId(),
spanId: spanId ?? getLocalSpanId(),
spanId: spanId ?? createLocalSpanId(),
parentSpanId,
requestIdentity: getCurrentRequestIdentity(),
isolateOpenTelemetry: isolateOpenTelemetry ?? false,
......@@ -112,6 +117,47 @@ export function getOpenTelemetrySpan(span: Span): Span | undefined {
return span instanceof LocalRecordingSpan ? span.getOpenTelemetrySpan() : span
}
export function captureLocalSpanContext(parent: LocalSpanParent) {
return {
...getCurrentRequestIdentity(),
traceId: parent.traceId,
parentSpanId: parent.spanId,
}
}
export function reparentLocalSpans(
parent: LocalSpanParent,
spans: readonly SpanStoreRecord[]
): SpanStoreRecord[] {
const importedIds = new Map<string, string>()
const key = (traceId: string, spanId: string) => `${traceId}:${spanId}`
for (const span of spans) {
if (span.traceId && span.spanId) {
importedIds.set(
key(span.traceId, span.spanId),
createLocalSpanId(parent.spanId)
)
}
}
return spans.map((span) => ({
...span,
traceId: parent.traceId,
spanId:
(span.traceId && span.spanId
? importedIds.get(key(span.traceId, span.spanId))
: undefined) ?? createLocalSpanId(parent.spanId),
parentSpanId:
(span.traceId && span.parentSpanId
? importedIds.get(key(span.traceId, span.parentSpanId))
: undefined) ?? parent.spanId,
links: span.links?.map((link) => {
const spanId = importedIds.get(key(link.traceId, link.spanId))
return spanId ? { ...link, traceId: parent.traceId, spanId } : link
}),
}))
}
export function isLocalRecordingSpan(span: Span): boolean {
return span instanceof LocalRecordingSpan
}
......@@ -167,35 +213,57 @@ export type LocalSpanRecorder = {
isLocalRecordingSpan: typeof isLocalRecordingSpan
isOpenTelemetryIsolatedSpan: typeof isOpenTelemetryIsolatedSpan
isLocalSpanRecordingEnabled: typeof isLocalSpanRecordingEnabled
isLocalSpanSinkActive: typeof isLocalSpanSinkActive
traceLocalSpan: typeof traceLocalSpan
withLocalSpan: typeof withLocalSpan
}
export function registerLocalSpanRecorder(): void {
const key = Symbol.for(
`@next/local-span-recorder@${process.env.__NEXT_VERSION}`
)
;(
globalThis as typeof globalThis & {
[key]?: LocalSpanRecorder
}
)[key] = {
// Some development entrypoints, including the proxy adapter, bundle their own
// tracer copy. This versioned function-only registry lets those copies reach
// the externalized recorder without sharing any per-request state globally.
const LOCAL_SPAN_RECORDER_KEY = Symbol.for(
`@next/local-span-recorder@${process.env.__NEXT_VERSION}`
)
type GlobalWithLocalSpanRecorder = typeof globalThis & {
[LOCAL_SPAN_RECORDER_KEY]?: LocalSpanRecorder
}
function getLocalSpanRecorderApi({
sinkOnly,
}: {
sinkOnly: boolean
}): LocalSpanRecorder {
return {
createLocalSpan,
getActiveLocalSpan,
getLocalParentSpan,
getOpenTelemetrySpan,
isLocalRecordingSpan,
isOpenTelemetryIsolatedSpan,
isLocalSpanRecordingEnabled,
isLocalSpanRecordingEnabled: sinkOnly
? isLocalSpanSinkActive
: isLocalSpanRecordingEnabled,
isLocalSpanSinkActive,
traceLocalSpan,
withLocalSpan,
}
}
export function registerLocalSpanRecorder({
sinkOnly = false,
}: {
sinkOnly?: boolean
} = {}): void {
;(globalThis as GlobalWithLocalSpanRecorder)[LOCAL_SPAN_RECORDER_KEY] =
getLocalSpanRecorderApi({ sinkOnly })
}
function getLocalSpanAsyncStorage() {
return getOrCreateGlobalAsyncLocalStorage<LocalSpanScope>(
'local-span-storage'
)
return getOrCreateGlobalAsyncLocalStorage<{
span: Span
publicContext: SpanContext | undefined
}>('local-span-storage')
}
type RequestIdentity = {
......
import {
clearRequestInsightsForTest,
getRequestInsightsSnapshot,
importRequestInsightSpans,
recordRequestInsightFetch,
registerRequestInsightsExporter,
subscribeRequestInsights,
......@@ -156,6 +157,98 @@ describe('request insights', () => {
unsubscribe()
})
it('imports a worker span batch with the main-thread identity', () => {
process.env.__NEXT_REQUEST_INSIGHTS = 'true'
const listener = jest.fn()
const unsubscribe = subscribeRequestInsights(listener)
importRequestInsightSpans(
{
requestId: 'instant_1',
kind: 'instant-insights',
htmlRequestId: 'html_1',
url: '/dashboard',
},
{ traceId: 'main-trace', spanId: 'main-parent' },
{
spans: [
{
name: 'worker root',
timestamp: 1,
traceId: 'worker-trace',
spanId: 'worker-root',
url: '/worker-only-url',
},
{
name: 'worker child',
timestamp: 2,
traceId: 'worker-trace',
spanId: 'worker-child',
parentSpanId: 'worker-root',
links: [
{ traceId: 'worker-trace', spanId: 'worker-root' },
{ traceId: 'external-trace', spanId: 'external-span' },
],
},
{
name: 'worker orphan',
timestamp: 3,
traceId: 'worker-trace',
spanId: 'worker-orphan',
parentSpanId: 'dropped-parent',
},
],
droppedSpanCount: 1,
}
)
expect(listener).toHaveBeenCalledTimes(1)
const [request] = getRequestInsightsSnapshot().requests
const workerRoot = request.spans.find(
(span) => span.name === 'worker root'
)!
const workerChild = request.spans.find(
(span) => span.name === 'worker child'
)!
const workerOrphan = request.spans.find(
(span) => span.name === 'worker orphan'
)!
expect(request).toEqual(
expect.objectContaining({
requestId: 'instant_1',
kind: 'instant-insights',
htmlRequestId: 'html_1',
url: '/dashboard',
})
)
expect(workerRoot).toEqual(
expect.objectContaining({
traceId: 'main-trace',
parentSpanId: 'main-parent',
})
)
expect(workerRoot.spanId).not.toBe('worker-root')
expect(workerChild).toEqual(
expect.objectContaining({
traceId: 'main-trace',
parentSpanId: workerRoot.spanId,
links: [
{ traceId: 'main-trace', spanId: workerRoot.spanId },
{ traceId: 'external-trace', spanId: 'external-span' },
],
})
)
expect(workerOrphan).toEqual(
expect.objectContaining({
traceId: 'main-trace',
parentSpanId: 'main-parent',
})
)
unsubscribe()
})
it('uses the HTTP request span as the end-to-end request timing', () => {
process.env.__NEXT_REQUEST_INSIGHTS = 'true'
......
......@@ -9,8 +9,18 @@ import {
getRequestInsightKey,
getRequestInsightKind,
} from '../../../shared/lib/request-insights'
import type { SpanStoreRecord } from './span-store'
import { isRequestInsightsEnabled, setLocalSpanExporter } from './span-store'
import {
isRequestInsightsEnabled,
recordSpans,
setLocalSpanExporter,
} from './span-store'
import type {
LocalSpanBatch,
LocalSpanParent,
SpanStoreRecord,
} from './span-store'
import type { RequestInsightsIdentity } from './request-insights-identity'
import { reparentLocalSpans } from './local-span-recorder'
export { isRequestInsightsEnabled } from './span-store'
const MAX_REQUEST_INSIGHTS = 100
......@@ -39,6 +49,7 @@ const SAFE_SPAN_ATTRIBUTE_KEYS = new Set([
'next.fetch.cache_status',
'next.fetch.idx',
'next.route',
'next.request_insights.omitted_spans',
'next.rsc',
'next.segment',
'next.span_category',
......@@ -280,15 +291,38 @@ export function registerRequestInsightsExporter(): void {
}
export function recordRequestInsightSpan(span: SpanStoreRecord): void {
if (
span.attributes?.['next.span_type'] === CLIENT_COMPONENT_LOADING_SPAN_TYPE
) {
if (!shouldRecordRequestInsightSpan(span)) {
return
}
getRequestInsightsStore().recordSpan(span)
}
export function importRequestInsightSpans(
identity: RequestInsightsIdentity,
parent: LocalSpanParent,
batch: LocalSpanBatch
): void {
recordSpans(
reparentLocalSpans(
parent,
batch.spans.filter(shouldRecordRequestInsightSpan)
).map((span) => ({
...span,
requestId: identity.requestId,
requestInsightKind: identity.kind,
htmlRequestId: identity.htmlRequestId,
url: identity.url,
}))
)
}
function shouldRecordRequestInsightSpan(span: SpanStoreRecord): boolean {
return (
span.attributes?.['next.span_type'] !== CLIENT_COMPONENT_LOADING_SPAN_TYPE
)
}
export function recordRequestInsightFetch(
identity: RequestInsightIdentity,
fetch: RequestInsightFetch
......
......@@ -46,6 +46,16 @@ export type SpanStoreRecord = {
}
}
export type LocalSpanParent = {
traceId: string
spanId: string
}
export type LocalSpanBatch = {
spans: SpanStoreRecord[]
droppedSpanCount: number
}
type SpanRecorderForTest = (span: SpanStoreRecord) => void
type LocalSpanSink = (span: SpanStoreRecord) => void
......
......@@ -18,7 +18,12 @@ import {
trace,
} from '@opentelemetry/api'
import { setSpanRecorderForTest, type SpanStoreRecord } from './span-store'
import {
isLocalSpanRecordingEnabled,
runWithLocalSpanSink,
setSpanRecorderForTest,
type SpanStoreRecord,
} from './span-store'
import {
registerLocalSpanRecorder,
traceLocalSpan,
......@@ -204,6 +209,44 @@ describe('local span recording', () => {
expect(getSpanRecords()).toEqual([])
})
it('records a local-only trace only while a worker sink is active', async () => {
setSpanRecorderForTest(undefined)
const workerRecords: SpanStoreRecord[] = []
registerLocalSpanRecorder({ sinkOnly: true })
getTracer().trace(NodeSpan.runHandler, () => undefined)
expect(workerRecords).toEqual([])
await runWithLocalSpanSink(
(span) => workerRecords.push(span),
() => {
expect(isLocalSpanRecordingEnabled()).toBe(true)
return getTracer().trace(
LoadComponentsSpan.loadRouteModule,
{ spanName: 'load route module' },
() => getTracer().trace(NodeSpan.runHandler, () => Promise.resolve())
)
}
)
const loadSpan = workerRecords.find(
(span) => span.name === 'load route module'
)!
const handlerSpan = workerRecords.find(
(span) => span.name === NodeSpan.runHandler
)!
expect(loadSpan.parentSpanId).toBeUndefined()
expect(handlerSpan).toEqual(
expect.objectContaining({
traceId: loadSpan.traceId,
parentSpanId: loadSpan.spanId,
})
)
getTracer().trace(NodeSpan.runHandler, () => undefined)
expect(workerRecords).toHaveLength(2)
registerLocalSpanRecorder()
})
it('records non-vanilla trace and wrapped spans for request insights', () => {
process.env.__NEXT_REQUEST_INSIGHTS = 'true'
......
......@@ -16,6 +16,10 @@ import type {
import { isThenable } from '../../../shared/lib/is-thenable'
const NEXT_OTEL_PERFORMANCE_PREFIX = process.env.NEXT_OTEL_PERFORMANCE_PREFIX
// Development entrypoints can contain their own tracer copy even though the
// recorder is externalized. The registry contains only the recorder API; active
// spans and validation collectors remain scoped by AsyncLocalStorage.
const LOCAL_SPAN_RECORDER_KEY = Symbol.for(
`@next/local-span-recorder@${process.env.__NEXT_VERSION}`
)
......@@ -348,6 +352,8 @@ class NextTracerImpl implements NextTracer {
const localSpanRecorder = getLocalSpanRecorder()
const localSpanRecordingEnabled =
localSpanRecorder?.isLocalSpanRecordingEnabled() ?? false
const localSpanSinkActive =
localSpanRecorder?.isLocalSpanSinkActive() ?? false
if (!tracingEnabled && !localSpanRecordingEnabled) {
return typeof fnOrOptions === 'function' ? fnOrOptions() : fnOrEmpty()
......@@ -379,6 +385,7 @@ class NextTracerImpl implements NextTracer {
? parentSpan
: undefined
const shouldDelegateSpan =
!localSpanSinkActive &&
!isolatedParentSpan &&
(NextVanillaSpanAllowlist.has(type) ||
process.env.NEXT_OTEL_VERBOSE === '1')
......@@ -420,7 +427,7 @@ class NextTracerImpl implements NextTracer {
tracingEnabled && shouldDelegateSpan,
localSpanRecordingEnabled,
parentSpan,
isolatedParentSpan !== undefined,
isolatedParentSpan !== undefined || localSpanSinkActive,
(span: Span) => {
let startTime: number | undefined
if (
......@@ -666,13 +673,17 @@ class NextTracerImpl implements NextTracer {
: context.active()
const localSpanRecordingEnabled =
localSpanRecorder?.isLocalSpanRecordingEnabled() ?? false
const localSpanSinkActive =
localSpanRecorder?.isLocalSpanSinkActive() ?? false
if (!localSpanRecordingEnabled) {
return this.getTracerInstance().startSpan(type, options, parentContext)
}
const delegateSpan =
!isolatedParentSpan && this.isOpenTelemetryEnabled()
!localSpanSinkActive &&
!isolatedParentSpan &&
this.isOpenTelemetryEnabled()
? this.getTracerInstance().startSpan(type, options, parentContext)
: undefined
......@@ -682,7 +693,7 @@ class NextTracerImpl implements NextTracer {
parentContext,
delegateSpan,
parentSpan,
isolatedParentSpan !== undefined
isolatedParentSpan !== undefined || localSpanSinkActive
)
}
......
......@@ -16,8 +16,10 @@ type RequestInsight = {
status: 'ok'
spans: Array<{
name?: string
traceId?: string
spanId?: string
parentSpanId?: string
status?: 'ok' | 'error'
attributes?: Record<string, string | number | boolean>
}>
fetches: Array<{
......@@ -30,7 +32,7 @@ type RequestInsight = {
}
describe('request insights', () => {
const { next } = nextTestSetup({
const { next, isTurbopack } = nextTestSetup({
files: __dirname,
})
......@@ -257,6 +259,69 @@ describe('request insights', () => {
rootSpans?.some((rootSpan) => rootSpan.spanId === span.parentSpanId)
).toBe(true)
}
const runValidationSpan = pipelineSpans?.find(
(span) =>
span.attributes?.['next.span_type'] ===
'AppRender.instantInsights.runValidation'
)
const workerLoadSpan = instantInsights?.spans.find(
(span) =>
span.attributes?.['next.span_type'] ===
'LoadComponents.loadRouteModule'
)
for (const spanType of [
'AppRender.instantInsights.warmup',
'AppRender.instantInsights.staticShell',
]) {
const phase = instantInsights?.spans.find(
(span) => span.attributes?.['next.span_type'] === spanType
)
expect(phase).toEqual(
expect.objectContaining({
parentSpanId: runValidationSpan?.spanId,
traceId: runValidationSpan?.traceId,
status: 'ok',
durationMs: expect.any(Number),
})
)
}
if (isTurbopack) {
const spansById = new Map(
instantInsights?.spans.flatMap((span) =>
span.spanId ? [[span.spanId, span] as const] : []
)
)
const expectDescendantOfRunValidation = (
span: RequestInsight['spans'][number] | undefined
) => {
const visited = new Set<string>()
let ancestor = span
while (
ancestor?.parentSpanId &&
ancestor.parentSpanId !== runValidationSpan?.spanId
) {
expect(visited.has(ancestor.parentSpanId)).toBe(false)
visited.add(ancestor.parentSpanId)
ancestor = spansById.get(ancestor.parentSpanId)
}
expect(ancestor?.parentSpanId).toBe(runValidationSpan?.spanId)
}
expect(workerLoadSpan).toEqual(
expect.objectContaining({
name: 'load route module',
traceId: runValidationSpan?.traceId,
status: 'ok',
})
)
expectDescendantOfRunValidation(workerLoadSpan)
} else {
// The dev validation worker only runs with Turbopack. Do not invent a
// worker span for the in-process Webpack validation path.
expect(workerLoadSpan).toBeUndefined()
}
expect(
request?.spans.some(
(span) =>
......
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