Unverified Commit e3c2f637 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Start the request span before route module preparation (#100349)

## Summary

Bottom of a stack: this PR → #100294 → #100324 → #100350 → #100392.

In direct entrypoints (Vercel, adapters, standalone handlers, i.e.
without next-server), `prepare route module` ran before the request span
started. Since 16.4 every request therefore produced an extra parentless
`prepare route module` trace next to the request trace. Now it is part
of the request span:

```
[P →] GET /page (BaseServer.handleRequest)
       └─ prepare route module → render …
```

### How

- New `RouteModule.traceRequest` (`@internal`, kept out of the published
declaration types) starts the request span **before** `prepare`. It uses
the caller's tracer. When the handler is wrapped by next-server, which
already started the request span, it runs inside that active span
instead.
- Callers first await the new `RouteModule.ensureInstrumentation`
(`@internal`), split out of `prepareImpl`: it registers
`instrumentation.ts`, which usually installs the tracer provider, so a
span started earlier would not be recorded. `prepareImpl` still calls
it, and patches `res.setHeader` as before.
- The app-page, app-route, pages and pages-api templates/handlers call
`ensureInstrumentation` and then `traceRequest`, and handle the response
through one code path: `traceRequest` passes the request span and the
request's root span (the span that was active when the handler was
invoked — next-server's request span or a platform/host span — or the
request span itself), and the route name is propagated to the root span
when it isn't the request span.
- Parenting of the request span itself (incoming `traceparent`, host
span, root) is unchanged.

## Verification

- Collector suite `test/e2e/opentelemetry/instrumentation`: direct
entrypoint cold and warm requests for all four handler types, with and
without an incoming `traceparent` and with a host span, assert
`RouteModule.prepare` is inside the request's trace, and route names on
the request and parent spans.
- New deploy-capable e2e suite `test/e2e/app-dir/otel-middleware-trace`
(moved down from #100294): `proxy.ts` and Edge `middleware.ts` variants,
plus a custom server with a host span. The app records its spans with a
SpanProcessor; the middleware and the render report the spans they can
see, and the test asserts the stitched span tree (with `http.target`,
`http.route`, `next.route` and `http.status_code` where set at report
time) in inline snapshots for pages, route handlers, rewrites,
redirects, direct responses, matcher misses, incoming `traceparent`,
header overrides and a middleware-set `traceparent`, in dev, start,
Cache Components and deploy. Here it records the current behavior
(middleware and render in separate traces); #100294 shows the change.
- Unit tests for the tracer changes (`tracer.test.ts`).

<!-- NEXT_JS_LLM -->


<!-- fleet ce0ecb23-b14c-4679-92a9-e676130f618e -->

---------
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarNiklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
Co-authored-by: 's avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by: 's avatarLuke Sandberg <210140+lukesandberg@users.noreply.github.com>
parent 269a6915
...@@ -15,7 +15,6 @@ import { RouteKind } from '../../server/route-kind' with { 'turbopack-transition ...@@ -15,7 +15,6 @@ import { RouteKind } from '../../server/route-kind' with { 'turbopack-transition
import { getRevalidateReason } from '../../server/instrumentation/utils' with { 'turbopack-transition': 'next-server-utility' } import { getRevalidateReason } from '../../server/instrumentation/utils' with { 'turbopack-transition': 'next-server-utility' }
import { import {
getTracer, getTracer,
SpanKind,
SpanStatusCode, SpanStatusCode,
type Span, type Span,
} from '../../server/lib/trace/tracer' with { 'turbopack-transition': 'next-server-utility' } } from '../../server/lib/trace/tracer' with { 'turbopack-transition': 'next-server-utility' }
...@@ -245,6 +244,42 @@ export function createAppPageEntrypoint({ ...@@ -245,6 +244,42 @@ export function createAppPageEntrypoint({
const multiZoneDraftMode = process.env const multiZoneDraftMode = process.env
.__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean .__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean
// Registering `instrumentation.ts` usually installs the tracer provider, so
// do it before starting the request span. The span is started before
// `prepare`, so route module preparation is part of the request's trace.
await routeModule.ensureInstrumentation(req)
return routeModule.traceRequest(
req,
{
tracer: getTracer(),
spanName: `${req.method || 'GET'} ${srcPage}`,
httpTarget,
},
(requestSpan, requestRootSpan) =>
handleRequest(
req,
res,
ctx,
isMinimalMode,
multiZoneDraftMode,
requestSpan,
requestRootSpan
)
)
}
async function handleRequest(
req: IncomingMessage,
res: ServerResponse,
ctx: {
waitUntil?: (prom: Promise<void>) => void
requestMeta?: RequestMeta
},
isMinimalMode: boolean,
multiZoneDraftMode: boolean,
requestSpan: Span | undefined,
requestRootSpan: Span | undefined
) {
const prepareResult = await routeModule.prepare(req, res, { const prepareResult = await routeModule.prepare(req, res, {
srcPage, srcPage,
multiZoneDraftMode, multiZoneDraftMode,
...@@ -758,10 +793,6 @@ export function createAppPageEntrypoint({ ...@@ -758,10 +793,6 @@ export function createAppPageEntrypoint({
const method = req.method || 'GET' const method = req.method || 'GET'
const tracer = getTracer() const tracer = getTracer()
const activeSpan = tracer.getActiveScopeSpan()
const isWrappedByNextServer = Boolean(
routerServerContext?.isWrappedByNextServer
)
const render404 = async () => { const render404 = async () => {
// TODO: should route-module itself handle rendering the 404 // TODO: should route-module itself handle rendering the 404
if (routerServerContext?.render404) { if (routerServerContext?.render404) {
...@@ -779,7 +810,6 @@ export function createAppPageEntrypoint({ ...@@ -779,7 +810,6 @@ export function createAppPageEntrypoint({
interceptionRoutePatterns interceptionRoutePatterns
) )
res.setHeader('Vary', varyHeader) res.setHeader('Vary', varyHeader)
let parentSpan: Span | undefined
const invokeRouteModule = async ( const invokeRouteModule = async (
span: Span | undefined, span: Span | undefined,
context: AppPageRouteHandlerContext, context: AppPageRouteHandlerContext,
...@@ -841,11 +871,12 @@ export function createAppPageEntrypoint({ ...@@ -841,11 +871,12 @@ export function createAppPageEntrypoint({
}) })
span.updateName(name) span.updateName(name)
// Propagate http.route to the parent span if one exists (e.g. // Propagate http.route to the request's root span if it isn't the
// a platform-created HTTP span in adapter deployments). // request span (e.g. a platform-created HTTP span in adapter
if (parentSpan && parentSpan !== span) { // deployments).
parentSpan.setAttribute('http.route', route) if (requestRootSpan && requestRootSpan !== span) {
parentSpan.updateName(name) requestRootSpan.setAttribute('http.route', route)
requestRootSpan.updateName(name)
} }
}) })
} }
...@@ -2423,31 +2454,7 @@ export function createAppPageEntrypoint({ ...@@ -2423,31 +2454,7 @@ export function createAppPageEntrypoint({
}) })
} }
// TODO: activeSpan code path is for when wrapped by return await handleResponse(requestSpan)
// next-server can be removed when this is no longer used
if (isWrappedByNextServer && activeSpan) {
await handleResponse(activeSpan)
} else {
parentSpan = tracer.getActiveScopeSpan()
return await tracer.withPropagatedContext(
req.headers,
() =>
tracer.trace(
BaseServerSpan.handleRequest,
{
spanName: `${method} ${srcPage}`,
kind: SpanKind.SERVER,
attributes: {
'http.method': method,
'http.target': httpTarget,
},
},
handleResponse
),
undefined,
!isWrappedByNextServer
)
}
} catch (err) { } catch (err) {
// If an Instant Navigation Testing document render fails (e.g. the page // If an Instant Navigation Testing document render fails (e.g. the page
// blocks at the root with no Suspense boundary above it, producing an empty // blocks at the root with no Suspense boundary above it, producing an empty
......
...@@ -15,7 +15,6 @@ import { ...@@ -15,7 +15,6 @@ import {
import { import {
getTracer, getTracer,
type Span, type Span,
SpanKind,
SpanStatusCode, SpanStatusCode,
} from '../../server/lib/trace/tracer' } from '../../server/lib/trace/tracer'
import { setManifestsSingleton } from '../../server/app-render/manifests-singleton' import { setManifestsSingleton } from '../../server/app-render/manifests-singleton'
...@@ -131,6 +130,42 @@ export async function handler( ...@@ -131,6 +130,42 @@ export async function handler(
const multiZoneDraftMode = process.env const multiZoneDraftMode = process.env
.__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean .__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean
// Registering `instrumentation.ts` usually installs the tracer provider, so
// do it before starting the request span. The span is started before
// `prepare`, so route module preparation is part of the request's trace.
await routeModule.ensureInstrumentation(req)
return routeModule.traceRequest(
req,
{
tracer: getTracer(),
spanName: `${req.method || 'GET'} ${srcPage}`,
httpTarget: req.url,
},
(requestSpan, requestRootSpan) =>
handleRequest(
req,
res,
ctx,
srcPage,
multiZoneDraftMode,
requestSpan,
requestRootSpan
)
)
}
async function handleRequest(
req: IncomingMessage,
res: ServerResponse,
ctx: {
waitUntil?: (prom: Promise<void>) => void
requestMeta?: RequestMeta
},
srcPage: string,
multiZoneDraftMode: boolean,
requestSpan: Span | undefined,
requestRootSpan: Span | undefined
) {
const prepareResult = await routeModule.prepare(req, res, { const prepareResult = await routeModule.prepare(req, res, {
srcPage, srcPage,
multiZoneDraftMode, multiZoneDraftMode,
...@@ -220,7 +255,6 @@ export async function handler( ...@@ -220,7 +255,6 @@ export async function handler(
const method = req.method || 'GET' const method = req.method || 'GET'
const tracer = getTracer() const tracer = getTracer()
const activeSpan = tracer.getActiveScopeSpan()
const isWrappedByNextServer = Boolean( const isWrappedByNextServer = Boolean(
routerServerContext?.isWrappedByNextServer routerServerContext?.isWrappedByNextServer
) )
...@@ -391,10 +425,7 @@ export async function handler( ...@@ -391,10 +425,7 @@ export async function handler(
} }
} }
const handleResponse = async ( const handleResponse = async (currentSpan: Span | undefined) => {
currentSpan: Span | undefined,
parentSpan: Span | undefined
) => {
try { try {
const cacheEntry = await routeModule.handleResponse({ const cacheEntry = await routeModule.handleResponse({
req, req,
...@@ -579,39 +610,22 @@ export async function handler( ...@@ -579,39 +610,22 @@ export async function handler(
}) })
currentSpan.updateName(name) currentSpan.updateName(name)
// Propagate http.route to the parent span if one exists (e.g. // Propagate http.route to the request's root span if it isn't the
// a platform-created HTTP span in adapter deployments). // request span (e.g. a platform-created HTTP span in adapter
if (parentSpan && parentSpan !== currentSpan) { // deployments).
parentSpan.setAttribute('http.route', route) if (requestRootSpan && requestRootSpan !== currentSpan) {
parentSpan.updateName(name) requestRootSpan.setAttribute('http.route', route)
requestRootSpan.updateName(name)
} }
})() })()
} }
} }
// TODO: activeSpan code path is for when wrapped by // When invoked directly, the request span was started before `prepare`;
// next-server can be removed when this is no longer used // record the request target as normalized by it. next-server's request span
if (isWrappedByNextServer && activeSpan) { // already has it.
await handleResponse(activeSpan, undefined) if (!isWrappedByNextServer && req.url !== undefined) {
} else { requestSpan?.setAttribute('http.target', req.url)
let parentSpan = tracer.getActiveScopeSpan()
await tracer.withPropagatedContext(
req.headers,
() =>
tracer.trace(
BaseServerSpan.handleRequest,
{
spanName: `${method} ${srcPage}`,
kind: SpanKind.SERVER,
attributes: {
'http.method': method,
'http.target': req.url,
},
},
(span) => handleResponse(span, parentSpan)
),
undefined,
!isWrappedByNextServer
)
} }
await handleResponse(requestSpan)
} }
...@@ -12,7 +12,7 @@ import { hoist } from './helpers' ...@@ -12,7 +12,7 @@ import { hoist } from './helpers'
import * as userland from 'VAR_USERLAND' import * as userland from 'VAR_USERLAND'
import { import {
getTracer, getTracer,
SpanKind, recordSpanError,
SpanStatusCode, SpanStatusCode,
} from '../../server/lib/trace/tracer' } from '../../server/lib/trace/tracer'
import { BaseServerSpan } from '../../server/lib/trace/constants' import { BaseServerSpan } from '../../server/lib/trace/constants'
...@@ -67,6 +67,33 @@ export async function handler( ...@@ -67,6 +67,33 @@ export async function handler(
srcPage = srcPage.replace(/\/index$/, '') || '/' srcPage = srcPage.replace(/\/index$/, '') || '/'
} }
// Registering `instrumentation.ts` usually installs the tracer provider, so
// do it before starting the request span. The span is started before
// `prepare`, so route module preparation is part of the request's trace.
await routeModule.ensureInstrumentation(req)
return routeModule.traceRequest(
req,
{
tracer: getTracer(),
spanName: `${req.method || 'GET'} ${srcPage}`,
httpTarget: req.url,
},
(requestSpan, requestRootSpan) =>
handleRequest(req, res, ctx, srcPage, requestSpan, requestRootSpan)
)
}
async function handleRequest(
req: IncomingMessage,
res: ServerResponse,
ctx: {
waitUntil?: (prom: Promise<void>) => void
requestMeta?: RequestMeta
},
srcPage: string,
requestSpan: Span | undefined,
requestRootSpan: Span | undefined
) {
const prepareResult = await routeModule.prepare(req, res, { srcPage }) const prepareResult = await routeModule.prepare(req, res, { srcPage })
if (!prepareResult) { if (!prepareResult) {
...@@ -82,14 +109,12 @@ export async function handler( ...@@ -82,14 +109,12 @@ export async function handler(
const method = req.method || 'GET' const method = req.method || 'GET'
const tracer = getTracer() const tracer = getTracer()
const activeSpan = tracer.getActiveScopeSpan()
const isWrappedByNextServer = Boolean( const isWrappedByNextServer = Boolean(
routerServerContext?.isWrappedByNextServer routerServerContext?.isWrappedByNextServer
) )
const onRequestError = const onRequestError =
routeModule.instrumentationOnRequestError.bind(routeModule) routeModule.instrumentationOnRequestError.bind(routeModule)
let parentSpan: Span | undefined
const invokeRouteModule = async (span?: Span) => const invokeRouteModule = async (span?: Span) =>
routeModule routeModule
.render(req, res, { .render(req, res, {
...@@ -161,38 +186,31 @@ export async function handler( ...@@ -161,38 +186,31 @@ export async function handler(
}) })
span.updateName(name) span.updateName(name)
// Propagate http.route to the parent span if one exists (e.g. // Propagate http.route to the request's root span if it isn't the
// a platform-created HTTP span in adapter deployments). // request span (e.g. a platform-created HTTP span in adapter
if (parentSpan && parentSpan !== span) { // deployments).
parentSpan.setAttribute('http.route', route) if (requestRootSpan && requestRootSpan !== span) {
parentSpan.updateName(name) requestRootSpan.setAttribute('http.route', route)
requestRootSpan.updateName(name)
} }
}) })
// TODO: activeSpan code path is for when wrapped by // When invoked directly, the request span was started before `prepare`;
// next-server can be removed when this is no longer used // record the request target as normalized by it. next-server's request
if (isWrappedByNextServer && activeSpan) { // span already has it.
await invokeRouteModule(activeSpan) if (!isWrappedByNextServer && req.url !== undefined) {
} else { requestSpan?.setAttribute('http.target', req.url)
parentSpan = tracer.getActiveScopeSpan() }
await tracer.withPropagatedContext( try {
req.headers, await invokeRouteModule(requestSpan)
() => } catch (err) {
tracer.trace( // A request span started for a direct invocation outlives the error
BaseServerSpan.handleRequest, // handling below, which only rethrows in dev: record the error on the
{ // span here otherwise.
spanName: `${method} ${srcPage}`, if (!isWrappedByNextServer && requestSpan && !routeModule.isDev) {
kind: SpanKind.SERVER, recordSpanError(requestSpan, err as Error)
attributes: { }
'http.method': method, throw err
'http.target': req.url,
},
},
invokeRouteModule
),
undefined,
!isWrappedByNextServer
)
} }
} catch (err) { } catch (err) {
// we re-throw in dev to show the error overlay // we re-throw in dev to show the error overlay
......
...@@ -33,7 +33,14 @@ import { ...@@ -33,7 +33,14 @@ import {
NodeSpan, NodeSpan,
RouteModuleSpan, RouteModuleSpan,
} from './constants' } from './constants'
import { SpanKind, SpanStatusCode, getTracer } from './tracer' import {
BubbledError,
recordSpanError,
SpanKind,
SpanStatusCode,
getTracer,
type Span,
} from './tracer'
const customContextKey = createContextKey('next.tracer.test.custom-context') const customContextKey = createContextKey('next.tracer.test.custom-context')
const originalRequestInsights = process.env.__NEXT_REQUEST_INSIGHTS const originalRequestInsights = process.env.__NEXT_REQUEST_INSIGHTS
...@@ -827,3 +834,40 @@ describe('local span recording', () => { ...@@ -827,3 +834,40 @@ describe('local span recording', () => {
}) })
}) })
}) })
describe('recordSpanError', () => {
function createSpan() {
return {
recordException: jest.fn(),
setAttribute: jest.fn(),
setStatus: jest.fn(),
end: jest.fn(),
}
}
it('records the error on the span without ending it', () => {
const span = createSpan()
const error = new TypeError('boom')
recordSpanError(span as unknown as Span, error)
expect(span.recordException).toHaveBeenCalledWith(error)
expect(span.setAttribute).toHaveBeenCalledWith('error.type', 'TypeError')
expect(span.setStatus).toHaveBeenCalledWith({
code: SpanStatusCode.ERROR,
message: 'boom',
})
expect(span.end).not.toHaveBeenCalled()
})
it('only marks bubbled errors', () => {
const span = createSpan()
recordSpanError(span as unknown as Span, new BubbledError(true))
expect(span.setAttribute).toHaveBeenCalledWith('next.bubble', true)
expect(span.recordException).not.toHaveBeenCalled()
expect(span.setStatus).not.toHaveBeenCalled()
expect(span.end).not.toHaveBeenCalled()
})
})
...@@ -67,11 +67,11 @@ export function isBubbledError(error: unknown): error is BubbledError { ...@@ -67,11 +67,11 @@ export function isBubbledError(error: unknown): error is BubbledError {
return error instanceof BubbledError return error instanceof BubbledError
} }
const closeSpanWithError = ( /**
span: Span, * Records `error` on `span` the way a span traced with `NextTracer.trace` that
error?: Error, * throws it does, without ending the span.
endTime?: Parameters<Span['end']>[0] */
) => { export const recordSpanError = (span: Span, error?: Error) => {
if (isBubbledError(error) && error.bubble) { if (isBubbledError(error) && error.bubble) {
span.setAttribute('next.bubble', true) span.setAttribute('next.bubble', true)
} else { } else {
...@@ -81,6 +81,14 @@ const closeSpanWithError = ( ...@@ -81,6 +81,14 @@ const closeSpanWithError = (
} }
span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message }) span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message })
} }
}
const closeSpanWithError = (
span: Span,
error?: Error,
endTime?: Parameters<Span['end']>[0]
) => {
recordSpanError(span, error)
span.end(endTime) span.end(endTime)
} }
......
...@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http' ...@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
import type { ParsedUrlQuery } from 'node:querystring' import type { ParsedUrlQuery } from 'node:querystring'
import { RouteKind } from '../../route-kind' import { RouteKind } from '../../route-kind'
import { BaseServerSpan } from '../../lib/trace/constants' import { BaseServerSpan } from '../../lib/trace/constants'
import { getTracer, SpanKind, type Span } from '../../lib/trace/tracer' import { getTracer, type Span } from '../../lib/trace/tracer'
import { formatUrl } from '../../../shared/lib/router/utils/format-url' import { formatUrl } from '../../../shared/lib/router/utils/format-url'
import { import {
addRequestMeta, addRequestMeta,
...@@ -100,6 +100,42 @@ export const getHandler = ({ ...@@ -100,6 +100,42 @@ export const getHandler = ({
const multiZoneDraftMode = process.env const multiZoneDraftMode = process.env
.__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean .__NEXT_MULTI_ZONE_DRAFT_MODE as any as boolean
// Registering `instrumentation.ts` usually installs the tracer provider, so
// do it before starting the request span. The span is started before
// `prepare`, so route module preparation is part of the request's trace.
await routeModule.ensureInstrumentation(req)
return routeModule.traceRequest(
req,
{
tracer: getTracer(),
spanName: `${req.method || 'GET'} ${srcPage}`,
httpTarget: req.url,
},
(requestSpan, requestRootSpan) =>
handleRequest(
req,
res,
ctx,
srcPage,
multiZoneDraftMode,
requestSpan,
requestRootSpan
)
)
}
async function handleRequest(
req: IncomingMessage,
res: ServerResponse,
ctx: {
waitUntil?: (prom: Promise<void>) => void
requestMeta?: RequestMeta
},
srcPage: string,
multiZoneDraftMode: boolean,
requestSpan: Span | undefined,
requestRootSpan: Span | undefined
) {
const prepareResult = await routeModule.prepare(req, res, { const prepareResult = await routeModule.prepare(req, res, {
srcPage, srcPage,
multiZoneDraftMode, multiZoneDraftMode,
...@@ -250,7 +286,6 @@ export const getHandler = ({ ...@@ -250,7 +286,6 @@ export const getHandler = ({
} }
const tracer = getTracer() const tracer = getTracer()
const activeSpan = tracer.getActiveScopeSpan()
const isWrappedByNextServer = Boolean( const isWrappedByNextServer = Boolean(
routerServerContext?.isWrappedByNextServer routerServerContext?.isWrappedByNextServer
) )
...@@ -265,7 +300,6 @@ export const getHandler = ({ ...@@ -265,7 +300,6 @@ export const getHandler = ({
query: hasStaticProps ? {} : originalQuery, query: hasStaticProps ? {} : originalQuery,
}) })
let parentSpan: Span | undefined
const handleResponse = async (span?: Span) => { const handleResponse = async (span?: Span) => {
const responseGenerator: ResponseGenerator = async ({ const responseGenerator: ResponseGenerator = async ({
previousCacheEntry, previousCacheEntry,
...@@ -822,41 +856,23 @@ export const getHandler = ({ ...@@ -822,41 +856,23 @@ export const getHandler = ({
}) })
span.updateName(name) span.updateName(name)
// Propagate http.route to the parent span if one exists // Propagate http.route to the request's root span if it isn't
// (e.g. a platform-created HTTP span in adapter // the request span (e.g. a platform-created HTTP span in adapter
// deployments). // deployments).
if (parentSpan && parentSpan !== span) { if (requestRootSpan && requestRootSpan !== span) {
parentSpan.setAttribute('http.route', route) requestRootSpan.setAttribute('http.route', route)
parentSpan.updateName(name) requestRootSpan.updateName(name)
} }
})() })()
} }
} }
// TODO: activeSpan code path is for when wrapped by // When invoked directly, the request span was started before `prepare`;
// next-server can be removed when this is no longer used // record the request target as normalized by it. next-server's request
if (isWrappedByNextServer && activeSpan) { // span already has it.
await handleResponse(activeSpan) if (!isWrappedByNextServer && req.url !== undefined) {
} else { requestSpan?.setAttribute('http.target', req.url)
parentSpan = tracer.getActiveScopeSpan()
await tracer.withPropagatedContext(
req.headers,
() =>
tracer.trace(
BaseServerSpan.handleRequest,
{
spanName: `${method} ${srcPage}`,
kind: SpanKind.SERVER,
attributes: {
'http.method': method,
'http.target': req.url,
},
},
handleResponse
),
undefined,
!isWrappedByNextServer
)
} }
await handleResponse(requestSpan)
} }
} }
...@@ -78,8 +78,8 @@ import { ...@@ -78,8 +78,8 @@ import {
import { decodePathParams } from '../lib/router-utils/decode-path-params' import { decodePathParams } from '../lib/router-utils/decode-path-params'
import { removeTrailingSlash } from '../../shared/lib/router/utils/remove-trailing-slash' import { removeTrailingSlash } from '../../shared/lib/router/utils/remove-trailing-slash'
import { isInterceptionRouteRewrite } from '../../lib/is-interception-route-rewrite' import { isInterceptionRouteRewrite } from '../../lib/is-interception-route-rewrite'
import { getTracer } from '../lib/trace/tracer' import { getTracer, SpanKind, type Span } from '../lib/trace/tracer'
import { RouteModuleSpan } from '../lib/trace/constants' import { BaseServerSpan, RouteModuleSpan } from '../lib/trace/constants'
/** /**
* RouteModuleOptions is the options that are passed to the route module, other * RouteModuleOptions is the options that are passed to the route module, other
...@@ -632,6 +632,76 @@ export abstract class RouteModule< ...@@ -632,6 +632,76 @@ export abstract class RouteModule<
return { nextConfig, deploymentId } return { nextConfig, deploymentId }
} }
/**
* Runs a route handler that was invoked directly (e.g. by an adapter or a
* deployment, without next-server) inside its request span
* (`BaseServer.handleRequest`).
*
* The span is started before `fn` calls `prepare`, so everything done for
* the request, including route module preparation, belongs to the request's
* trace. When the handler is wrapped by next-server, which already started
* the request span, `fn` runs inside that active span instead.
*
* Callers must await `ensureInstrumentation` before calling this: on the
* first request, registering `instrumentation.ts` usually installs the
* tracer provider, and a span started earlier would not be recorded.
*
* `fn` receives the request span and the request's root span: the span that
* was active when the handler was invoked (next-server's request span, or a
* platform-created HTTP span), or the request span itself when there is no
* such span.
*
* `tracer` must be the caller's tracer: route modules are bundled with their
* own copy of the tracer, whose root span bookkeeping (e.g.
* `getRootSpanAttributes`) the caller can't see.
*
* @internal - only called by the Next.js build templates. Kept out of the
* published type declarations, which can't reference the tracer's types.
*/
public async traceRequest<T>(
req: IncomingMessage,
{
tracer,
spanName,
httpTarget,
}: {
tracer: ReturnType<typeof getTracer>
spanName: string
httpTarget: string | undefined
},
fn: (span: Span | undefined, rootSpan: Span | undefined) => Promise<T>
): Promise<T> {
const activeSpan = tracer.getActiveScopeSpan()
const isWrappedByNextServer = Boolean(
this.getRouterServerContext(req)?.isWrappedByNextServer
)
// TODO: activeSpan code path is for when wrapped by
// next-server can be removed when this is no longer used
if (isWrappedByNextServer && activeSpan) {
return fn(activeSpan, activeSpan)
}
return tracer.withPropagatedContext(
req.headers,
() =>
tracer.trace(
BaseServerSpan.handleRequest,
{
spanName,
kind: SpanKind.SERVER,
attributes: {
'http.method': req.method || 'GET',
'http.target': httpTarget,
},
},
(span) => fn(span, activeSpan ?? span)
),
undefined,
!isWrappedByNextServer
)
}
public prepare( public prepare(
req: IncomingMessage | BaseNextRequest, req: IncomingMessage | BaseNextRequest,
res: ServerResponse | null, res: ServerResponse | null,
...@@ -647,6 +717,49 @@ export abstract class RouteModule< ...@@ -647,6 +717,49 @@ export abstract class RouteModule<
) )
} }
/**
* Makes sure `instrumentation.ts` is registered for the Node.js runtime.
* Safe to call more than once per request. Returns the absolute project
* directory (`undefined` in the edge runtime, which handles loading
* instrumentation at the edge adapter level).
*
* @internal - called by `prepare` and by the Next.js build templates before
* `traceRequest`.
*/
public async ensureInstrumentation(
req: IncomingMessage | BaseNextRequest
): Promise<string | undefined> {
let absoluteProjectDir: string | undefined
if (process.env.NEXT_RUNTIME !== 'edge') {
const { join, relative } =
require('node:path') as typeof import('node:path')
absoluteProjectDir = join(
/* turbopackIgnore: true */
process.cwd(),
getRequestMeta(req, 'relativeProjectDir') || this.relativeProjectDir
)
const absoluteDistDir = getRequestMeta(req, 'distDir')
if (absoluteDistDir) {
this.distDir = relative(absoluteProjectDir, absoluteDistDir)
}
const { ensureInstrumentationRegistered } = await import(
'../lib/router-utils/instrumentation-globals.external.js'
)
// ensure instrumentation is registered and pass
// onRequestError below. Awaited so any caller of `RouteModule.prepare`
// that bypasses `BaseServer.handleRequest` (where this is also awaited
// via `prepareImpl`) still observes the instrumentation hook completing
// before the userland route handler runs.
await ensureInstrumentationRegistered(absoluteProjectDir, this.distDir)
}
return absoluteProjectDir
}
private async prepareImpl( private async prepareImpl(
req: IncomingMessage | BaseNextRequest, req: IncomingMessage | BaseNextRequest,
res: ServerResponse | null, res: ServerResponse | null,
...@@ -701,38 +814,10 @@ export abstract class RouteModule< ...@@ -701,38 +814,10 @@ export abstract class RouteModule<
} }
| undefined | undefined
> { > {
let absoluteProjectDir: string | undefined if (process.env.NEXT_RUNTIME !== 'edge' && res) {
patchSetHeaderWithCookieSupport(req, res)
// edge runtime handles loading instrumentation at the edge adapter level
if (process.env.NEXT_RUNTIME !== 'edge') {
if (res) {
patchSetHeaderWithCookieSupport(req, res)
}
const { join, relative } =
require('node:path') as typeof import('node:path')
absoluteProjectDir = join(
/* turbopackIgnore: true */
process.cwd(),
getRequestMeta(req, 'relativeProjectDir') || this.relativeProjectDir
)
const absoluteDistDir = getRequestMeta(req, 'distDir')
if (absoluteDistDir) {
this.distDir = relative(absoluteProjectDir, absoluteDistDir)
}
const { ensureInstrumentationRegistered } = await import(
'../lib/router-utils/instrumentation-globals.external.js'
)
// ensure instrumentation is registered and pass
// onRequestError below. Awaited so any caller of `RouteModule.prepare`
// that bypasses `BaseServer.handleRequest` (where this is also awaited
// via `prepareImpl`) still observes the instrumentation hook completing
// before the userland route handler runs.
await ensureInstrumentationRegistered(absoluteProjectDir, this.distDir)
} }
const absoluteProjectDir = await this.ensureInstrumentation(req)
const manifests = getTracer().trace( const manifests = getTracer().trace(
RouteModuleSpan.loadManifests, RouteModuleSpan.loadManifests,
{ spanName: 'load route manifests' }, { spanName: 'load route manifests' },
......
import { headers } from 'next/headers'
import { Suspense } from 'react'
import { getRenderSpans } from '../../trace-recorder'
import { markMetadataGenerated, metadataGenerated } from '../../metadata-ready'
async function RequestInfo() {
const requestHeaders = Object.fromEntries((await headers()).entries())
await metadataGenerated()
return (
<>
<pre id="spans">{JSON.stringify(getRenderSpans())}</pre>
<pre id="headers">{JSON.stringify(requestHeaders)}</pre>
</>
)
}
export default function Page() {
return (
<Suspense>
<RequestInfo />
</Suspense>
)
}
export async function generateMetadata() {
markMetadataGenerated('page')
return {}
}
import type { ReactNode } from 'react'
import { markMetadataGenerated } from '../metadata-ready'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
// Traced as `generateMetadata` spans in the render.
export async function generateMetadata() {
markMetadataGenerated('layout')
return {}
}
export default function Home() {
return <p>otel-middleware-trace</p>
}
export async function generateMetadata() {
return {}
}
import { headers } from 'next/headers'
import { Suspense } from 'react'
import { getRenderSpans } from '../../trace-recorder'
import { markMetadataGenerated, metadataGenerated } from '../../metadata-ready'
async function Spans() {
// Reading request headers also makes this run at request time, so the
// reported spans belong to the request.
await headers()
await metadataGenerated()
return <pre id="spans">{JSON.stringify(getRenderSpans())}</pre>
}
export default function Page() {
return (
<Suspense>
<Spans />
</Suspense>
)
}
export async function generateMetadata() {
markMetadataGenerated('page')
return {}
}
import { connection } from 'next/server'
import { getRenderSpans } from '../../trace-recorder'
export async function GET() {
// Run at request time so the reported spans belong to the request.
await connection()
return Response.json({ spans: getRenderSpans() })
}
import { connection } from 'next/server'
import { Suspense } from 'react'
import { getRenderSpans } from '../../trace-recorder'
import { markMetadataGenerated, metadataGenerated } from '../../metadata-ready'
async function Spans() {
// Run at request time so the reported spans belong to the request.
await connection()
await metadataGenerated()
return <pre id="spans">{JSON.stringify(getRenderSpans())}</pre>
}
// Not matched by the middleware: a baseline for requests without middleware.
export default function Page() {
return (
<Suspense>
<Spans />
</Suspense>
)
}
export async function generateMetadata() {
markMetadataGenerated('page')
return {}
}
const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')
const getPort = require('get-port')
const { trace } = require('@opentelemetry/api')
// A custom server that wraps every request in an active host span, like an
// APM's HTTP instrumentation does. The tracer provider is the one
// `instrumentation.ts` registers (with the span recorder) during `prepare()`.
async function main() {
const hostname = 'localhost'
const port = await getPort()
const app = next({
dev: process.env.NODE_ENV === 'development',
hostname,
port,
dir: __dirname,
})
const handle = app.getRequestHandler()
await app.prepare()
const tracer = trace.getTracer('custom-server')
createServer((req, res) => {
tracer.startActiveSpan('custom-server-request', async (span) => {
try {
await handle(req, res, parse(req.url ?? '/', true))
} catch (err) {
span.recordException(err)
res.statusCode = 500
res.end('Internal Server Error')
} finally {
span.end()
}
})
}).listen(port, hostname, () => {
console.log(`- Local: http://${hostname}:${port}`)
})
}
main().catch((err) => {
console.error(err)
process.exit(1)
})
import { registerOTel } from '@vercel/otel'
import { spanRecorder } from './trace-recorder'
export function register() {
// No exporter is needed: the app itself reports the spans of a request, so
// the suite also works when deployed (where no local collector is
// reachable).
registerOTel({
serviceName: 'otel-middleware-trace',
spanProcessors: [spanRecorder],
})
}
import { cache } from 'react'
// `generateMetadata` runs concurrently with the page. The page reports the
// render's spans once `generateMetadata` of the layout and the page ran (per
// request, via `cache`), so the `generateMetadata` spans are always among them.
type Segment = 'layout' | 'page'
const getDeferred = cache((_segment: Segment) => {
let resolve!: () => void
const promise = new Promise<void>((r) => {
resolve = r
})
return { promise, resolve }
})
export function markMetadataGenerated(segment: Segment) {
getDeferred(segment).resolve()
}
export async function metadataGenerated() {
// Don't hang when `generateMetadata` doesn't run for this render (e.g. its
// result was prerendered).
let timeout: ReturnType<typeof setTimeout> | undefined
await Promise.race([
Promise.all([getDeferred('layout').promise, getDeferred('page').promise]),
new Promise<void>((resolve) => {
timeout = setTimeout(resolve, 5_000)
}),
])
clearTimeout(timeout)
}
import { NextResponse, type NextRequest } from 'next/server'
import { getMiddlewareSpans } from './trace-recorder'
export const USER_TRACE_ID = '0af7651916cd43dd8448eb211c80319c'
export const USER_SPAN_ID = 'b7ad6b7169203331'
// Shared by `proxy.ts` (Node.js runtime) and `middleware.ts` (Edge runtime).
export function handler(request: NextRequest) {
// The middleware's span and its ancestors started in this process, for the
// test to print the request's span tree.
const spans = getMiddlewareSpans()
const { pathname } = request.nextUrl
let response: NextResponse
if (pathname === '/rewrite') {
response = NextResponse.rewrite(new URL('/page', request.url))
} else if (pathname === '/redirect') {
response = NextResponse.redirect(new URL('/page', request.url))
} else if (pathname === '/direct') {
response = new NextResponse('direct response from middleware')
} else if (pathname === '/user-overrides') {
const headers = new Headers(request.headers)
headers.set('x-user-added', 'added-by-middleware')
headers.delete('x-delete-me')
response = NextResponse.rewrite(new URL('/headers-echo', request.url), {
request: { headers },
})
} else if (pathname === '/user-traceparent') {
const headers = new Headers(request.headers)
headers.set('traceparent', `00-${USER_TRACE_ID}-${USER_SPAN_ID}-01`)
response = NextResponse.rewrite(new URL('/headers-echo', request.url), {
request: { headers },
})
} else {
response = NextResponse.next()
}
response.headers.set('x-mw-spans', JSON.stringify(spans))
return response
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {}
export default nextConfig
import { trace, type Context } from '@opentelemetry/api'
import type {
ReadableSpan,
Span as SdkSpan,
SpanProcessor,
} from '@opentelemetry/sdk-trace-base'
// Records every span started in this process with its parent, using only
// public OpenTelemetry APIs (`onStart`'s parent context), so the app can report
// the spans of a request itself. This works in the Node.js and Edge runtimes
// and when deployed, where no collector is reachable.
export interface RecordedSpan {
id: string
parentId: string | undefined
traceId: string
name: string
/** The `next.span_type` attribute. */
type: string | undefined
/** The span's `PRINTED_ATTRIBUTES` that are set, when reported. */
attributes?: Record<string, string | number | boolean>
}
// Attributes shown in the span trees, set by Next.js at different points of a
// request (some of them only once the request span ends, so they're only
// shown if they were set when the spans were reported).
const PRINTED_ATTRIBUTES = [
'http.target',
'http.route',
'next.route',
'http.status_code',
]
interface Entry {
span: SdkSpan
parentId: string | undefined
}
const MAX_RECORDED_SPANS = 10_000
function getRecordedSpans(): Map<string, Entry> {
const store = globalThis as typeof globalThis & {
__otelTestRecordedSpans?: Map<string, Entry>
}
store.__otelTestRecordedSpans ??= new Map()
return store.__otelTestRecordedSpans
}
export const spanRecorder: SpanProcessor = {
onStart(span: SdkSpan, parentContext: Context) {
const spans = getRecordedSpans()
if (spans.size >= MAX_RECORDED_SPANS) {
// Drop the oldest entry (Map iterates in insertion order).
spans.delete(spans.keys().next().value!)
}
spans.set(span.spanContext().spanId, {
span,
parentId: trace.getSpanContext(parentContext)?.spanId,
})
},
onEnd(_span: ReadableSpan) {},
forceFlush: () => Promise.resolve(),
shutdown: () => Promise.resolve(),
}
// Read when reported, so spans renamed after they started (e.g. a request
// span named after its route) show their current name.
function toRecordedSpan({ span, parentId }: Entry): RecordedSpan {
const type = span.attributes['next.span_type']
const attributes: Record<string, string | number | boolean> = {}
for (const key of PRINTED_ATTRIBUTES) {
const value = span.attributes[key]
if (
typeof value === 'string' ||
typeof value === 'number' ||
typeof value === 'boolean'
) {
attributes[key] = value
}
}
return {
id: span.spanContext().spanId,
parentId,
traceId: span.spanContext().traceId,
name: span.name,
type: typeof type === 'string' ? type : undefined,
attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
}
}
/** The given span and its ancestors, as far as they were started here. */
function getChain(spanId: string | undefined) {
const spans = getRecordedSpans()
const chain: RecordedSpan[] = []
let entry = spanId ? spans.get(spanId) : undefined
while (entry) {
chain.push(toRecordedSpan(entry))
entry = entry.parentId ? spans.get(entry.parentId) : undefined
}
return chain
}
/** The spans started here so far below the given span (not the span itself). */
function getDescendants(spanId: string) {
return [...getRecordedSpans().values()]
.filter(({ parentId }) =>
getChain(parentId).some((span) => span.id === spanId)
)
.map(toRecordedSpan)
}
/**
* The middleware's spans: its active span, that span's ancestors, and the
* descendants started so far of the topmost of them (e.g. spans started next
* to the middleware span in the root inserted by the middleware adapter).
*/
export function getMiddlewareSpans() {
const chain = getChain(trace.getActiveSpan()?.spanContext().spanId)
if (chain.length === 0) {
return chain
}
const ids = new Set(chain.map((span) => span.id))
return [
...chain,
...getDescendants(chain[chain.length - 1].id).filter(
(span) => !ids.has(span.id)
),
]
}
/**
* The render's spans: its request span (the nearest `BaseServer.handleRequest`
* ancestor of the active span), that span's ancestors, and the request span's
* descendants started so far.
*/
export function getRenderSpans() {
const chain = getChain(trace.getActiveSpan()?.spanContext().spanId)
const index = chain.findIndex(
(span) => span.type === 'BaseServer.handleRequest'
)
if (index === -1) {
return chain
}
const requestSpanId = chain[index].id
return [...chain.slice(index), ...getDescendants(requestSpanId)]
}
...@@ -3,6 +3,12 @@ import { SavedSpan } from './constants' ...@@ -3,6 +3,12 @@ import { SavedSpan } from './constants'
export interface Collector { export interface Collector {
getSpans: () => SavedSpan[] getSpans: () => SavedSpan[]
/**
* Like `getSpans`, but also includes spans marked `next.bubble` (e.g.
* next-server's middleware-invoke `handleRequest` span), which are needed to
* check the full span hierarchy of a request.
*/
getAllSpans: () => SavedSpan[]
reset: () => void reset: () => void
shutdown: () => Promise<void> shutdown: () => Promise<void>
} }
...@@ -13,6 +19,7 @@ export async function connectCollector({ ...@@ -13,6 +19,7 @@ export async function connectCollector({
port: number port: number
}): Promise<Collector> { }): Promise<Collector> {
const spans: SavedSpan[] = [] const spans: SavedSpan[] = []
const allSpans: SavedSpan[] = []
const server = new HttpServer(async (req, res) => { const server = new HttpServer(async (req, res) => {
if (req.method !== 'POST') { if (req.method !== 'POST') {
...@@ -33,6 +40,7 @@ export async function connectCollector({ ...@@ -33,6 +40,7 @@ export async function connectCollector({
}) })
const newSpans = JSON.parse(body.toString('utf-8')) as SavedSpan[] const newSpans = JSON.parse(body.toString('utf-8')) as SavedSpan[]
allSpans.push(...newSpans)
const filteredSpans = newSpans.filter((span) => { const filteredSpans = newSpans.filter((span) => {
if (span.attributes?.['next.bubble'] === true) { if (span.attributes?.['next.bubble'] === true) {
return false return false
...@@ -61,8 +69,12 @@ export async function connectCollector({ ...@@ -61,8 +69,12 @@ export async function connectCollector({
getSpans() { getSpans() {
return spans return spans
}, },
getAllSpans() {
return allSpans
},
reset() { reset() {
spans.length = 0 spans.length = 0
allSpans.length = 0
}, },
shutdown() { shutdown() {
return new Promise<void>((resolve, reject) => return new Promise<void>((resolve, reject) =>
......
...@@ -2032,68 +2032,158 @@ describe.each( ...@@ -2032,68 +2032,158 @@ describe.each(
}) })
if (isNextStart) { if (isNextStart) {
describe('opentelemetry route module preparation with direct entrypoint handler', () => { describe.each([
let collector: Collector | undefined { name: 'without parent span', withParentSpan: false },
const { next, skipped } = nextTestSetup({ { name: 'with parent span', withParentSpan: true },
files: __dirname, ])(
skipStart: true, 'opentelemetry route module preparation with direct entrypoint handler $name',
dependencies: require('./package.json').dependencies, ({ withParentSpan }) => {
startCommand: 'pnpm start-entrypoint', let collector: Collector | undefined
packageJson: { const { next, skipped } = nextTestSetup({
scripts: { files: __dirname,
'start-entrypoint': skipStart: true,
'pnpm tsx custom-entrypoint-server.ts --without-parent-span', dependencies: require('./package.json').dependencies,
startCommand: 'pnpm start-entrypoint',
packageJson: {
scripts: {
'start-entrypoint': withParentSpan
? 'pnpm tsx custom-entrypoint-server.ts'
: 'pnpm tsx custom-entrypoint-server.ts --without-parent-span',
},
}, },
}, serverReadyPattern: /- Local:/,
serverReadyPattern: /- Local:/, env: {
env: { TEST_OTEL_COLLECTOR_PORT: String(ROUTE_PREPARATION_COLLECTOR_PORT),
TEST_OTEL_COLLECTOR_PORT: String(ROUTE_PREPARATION_COLLECTOR_PORT), NEXT_TELEMETRY_DISABLED: '1',
NEXT_TELEMETRY_DISABLED: '1', NODE_ENV: 'production',
NODE_ENV: 'production', },
}, })
})
if (skipped) {
return
}
afterAll(async () => { if (skipped) {
await collector?.shutdown() return
}) }
it('should trace route module preparation', async () => { afterAll(async () => {
const connectedCollector = await connectCollector({ await collector?.shutdown()
port: ROUTE_PREPARATION_COLLECTOR_PORT,
}) })
collector = connectedCollector
await next.start()
await next.fetch('/app/param/rsc-fetch') const pathnames = [
await next.fetch('/api/app/param/data') '/app/param/rsc-fetch',
'/api/app/param/data',
'/pages/param/getServerSideProps',
'/api/pages/param/basic',
]
await retry(async () => { it('should trace route module preparation inside the request span', async () => {
const prepareSpans = connectedCollector const connectedCollector = await connectCollector({
.getSpans() port: ROUTE_PREPARATION_COLLECTOR_PORT,
.filter( })
collector = connectedCollector
await next.start()
// The first request starts the process (cold: instrumentation is
// registered and route modules are loaded), the later ones are warm.
// The parent-span harness starts its own root span without extracting
// incoming headers, so incoming propagation only applies without it.
const requests: { id: string; cold: boolean; traceparent: boolean }[] =
[]
for (const [index, pathname] of pathnames.entries()) {
for (const variant of [
{ traceparent: false },
{ traceparent: false },
...(withParentSpan ? [] : [{ traceparent: true }]),
]) {
const id = Math.random().toString(36).slice(2)
const res = await next.fetch(`${pathname}?id=${id}`, {
headers: variant.traceparent
? {
traceparent: `00-${EXTERNAL.traceId}-${EXTERNAL.spanId}-01`,
}
: {},
})
expect(res.status).toBe(200)
requests.push({
id,
cold: index === 0 && requests.length === 0,
traceparent: variant.traceparent,
})
}
}
await retry(async () => {
const spans = connectedCollector.getAllSpans()
const byId = new Map(spans.map((span) => [span.id, span]))
const prepareSpans = spans.filter(
(span) => (span) =>
span.attributes?.['next.span_type'] === 'RouteModule.prepare' span.attributes?.['next.span_type'] === 'RouteModule.prepare'
) )
expect(prepareSpans).toEqual([ // Every route module preparation belongs to a request: none starts
expect.objectContaining({ // a trace of its own.
runtime: 'nodejs', for (const span of prepareSpans) {
name: 'prepare route module', expect(span).toEqual(
attributes: { expect.objectContaining({
'next.span_category': 'nextjs', // The parent-span harness exports through its own provider,
'next.span_name': 'prepare route module', // which doesn't record the runtime.
'next.span_type': 'RouteModule.prepare', ...(withParentSpan ? {} : { runtime: 'nodejs' }),
}, name: 'prepare route module',
status: { code: 0 }, attributes: {
}), 'next.span_category': 'nextjs',
]) 'next.span_name': 'prepare route module',
'next.span_type': 'RouteModule.prepare',
},
status: { code: 0 },
})
)
const parent = byId.get(span.parentId!)
expect(parent?.attributes?.['next.span_type']).toBe(
'BaseServer.handleRequest'
)
expect(span.traceId).toMatch(/^[0-9a-f]{32}$/)
expect(span.traceId).toBe(parent!.traceId)
}
for (const { id, cold, traceparent } of requests) {
const requestSpans = spans.filter(
(span) =>
span.attributes?.['next.span_type'] ===
'BaseServer.handleRequest' &&
String(span.attributes?.['http.target'] ?? '').includes(
`id=${id}`
)
)
expect({ id, cold, requestSpans: requestSpans.length }).toEqual({
id,
cold,
requestSpans: 1,
})
const [requestSpan] = requestSpans
expect(requestSpan.traceId).toMatch(/^[0-9a-f]{32}$/)
// The request's route module preparation is nested in its span.
const requestPrepareSpans = prepareSpans.filter(
(span) => span.parentId === requestSpan.id
)
expect(requestPrepareSpans).toHaveLength(1)
expect(requestPrepareSpans[0].traceId).toBe(requestSpan.traceId)
// ...and the request span continues the request's context.
if (withParentSpan) {
const parent = byId.get(requestSpan.parentId!)
expect(parent).toBeDefined()
expect(parent!.attributes?.['next.span_type']).toBeUndefined()
expect(parent!.traceId).toBe(requestSpan.traceId)
} else if (traceparent) {
expect(requestSpan.traceId).toBe(EXTERNAL.traceId)
expect(requestSpan.parentId).toBe(EXTERNAL.spanId)
} else {
expect(requestSpan.parentId).toBeUndefined()
}
}
})
}) })
}) }
}) )
} }
describe.each( describe.each(
......
/**
* Prints OpenTelemetry spans as an indented tree, for snapshot tests of the
* trace shape. Span IDs are left out, but trace identity is kept: every tree
* root is labelled with its trace (the name of a known trace context, e.g.
* `incoming` for the test's incoming `traceparent`, otherwise `A`, `B`, … in
* order of appearance), and a span whose trace differs from its parent's is
* marked with its own label. Parents that aren't among the spans are shown as
* `[<name> traceparent]` (a known trace context) or `[remote]`. A span's
* `attributes`, if any, are appended in braces.
*
* ```
* [trace A] GET (Next.request) {http.target=/page}
* ├─ GET /page (BaseServer.handleRequest) {http.target=/page}
* │ └─ render route (app) /page (AppRender.getBodyResult)
* └─ middleware GET (Middleware.execute)
* ```
*/
export interface TreeSpan {
id: string
parentId?: string
traceId: string
name: string
/** The `next.span_type` attribute. */
type?: string
/** Attributes to print, in the given order. */
attributes?: Record<string, string | number | boolean>
}
interface Node {
label: string
traceId: string
children: Node[]
}
/** A trace context the test knows, e.g. the `traceparent` it sends. */
export interface KnownTraceContext {
name: string
traceId: string
spanId: string
}
/**
* One-time work outside of the request's own work: instrumentation
* registration, app route module loading (in the first request only), and
* route module prewarming at startup (root `LoadComponents.loadRouteModule`
* spans, which can still arrive during the first test). Omit it (`omit`) so
* span tree snapshots don't depend on the test order.
*/
export function isOneTimeSpan(span: TreeSpan) {
return (
span.type === 'Instrumentation.loadModule' ||
span.type === 'Instrumentation.register' ||
span.type === 'AppRouteRouteModule.loadUserland' ||
(!span.parentId && span.type === 'LoadComponents.loadRouteModule')
)
}
export function printSpanTree(
allSpans: TreeSpan[],
{
known = [],
omit = () => false,
}: {
known?: KnownTraceContext[]
/** Spans to leave out, with their descendants (e.g. `isOneTimeSpan`). */
omit?: (span: TreeSpan) => boolean
} = {}
): string {
const omitted = new Set<string>()
for (let changed = true; changed; ) {
changed = false
for (const span of allSpans) {
if (
!omitted.has(span.id) &&
(omit(span) || (span.parentId && omitted.has(span.parentId)))
) {
omitted.add(span.id)
changed = true
}
}
}
const spans = allSpans.filter((span) => !omitted.has(span.id))
const knownNames = new Set(known.map((context) => context.name))
const traceLabels = new Map<string, string>()
for (const context of known) {
traceLabels.set(context.traceId, context.name)
}
const traceLabel = (traceId: string) => {
let label = traceLabels.get(traceId)
if (!label) {
const count = [...traceLabels.values()].filter(
(value) => !knownNames.has(value)
).length
label =
count < 26
? String.fromCharCode('A'.charCodeAt(0) + count)
: String(count + 1)
traceLabels.set(traceId, label)
}
return label
}
const nodes = new Map<string, Node>()
for (const span of spans) {
const label =
span.type && span.type !== span.name
? `${span.name} (${span.type})`
: span.name
const attributes = Object.entries(span.attributes ?? {})
.map(([key, value]) => `${key}=${value}`)
.join(', ')
nodes.set(span.id, {
label: attributes ? `${label} {${attributes}}` : label,
traceId: span.traceId,
children: [],
})
}
// Parents that aren't among the spans, by parent span ID.
const missingParents = new Map<string, Node>()
const roots: Node[] = []
for (const span of spans) {
const node = nodes.get(span.id)!
if (!span.parentId) {
roots.push(node)
continue
}
let parent = nodes.get(span.parentId) ?? missingParents.get(span.parentId)
if (!parent) {
const context = known.find(({ spanId }) => spanId === span.parentId)
parent = {
label: context ? `[${context.name} traceparent]` : '[remote]',
traceId: span.traceId,
children: [],
}
missingParents.set(span.parentId, parent)
roots.push(parent)
}
parent.children.push(node)
}
const sortNodes = (list: Node[]) =>
list.sort((a, b) => a.label.localeCompare(b.label))
// Assign trace labels in a deterministic order (sorted roots, depth first),
// so the labels don't depend on the order the spans were collected in.
const assignLabels = (node: Node) => {
traceLabel(node.traceId)
sortNodes(node.children).forEach(assignLabels)
}
sortNodes(roots).forEach(assignLabels)
roots.sort(
(a, b) =>
traceLabel(a.traceId).localeCompare(traceLabel(b.traceId)) ||
a.label.localeCompare(b.label)
)
const lines: string[] = []
const print = (node: Node, prefix: string) => {
node.children.forEach((child, index) => {
const last = index === node.children.length - 1
const marker =
child.traceId !== node.traceId
? ` [trace ${traceLabel(child.traceId)}]`
: ''
lines.push(`${prefix}${last ? '└─ ' : '├─ '}${child.label}${marker}`)
print(child, prefix + (last ? ' ' : '│ '))
})
}
for (const root of roots) {
lines.push(`[trace ${traceLabel(root.traceId)}] ${root.label}`)
print(root, '')
}
return lines.join('\n')
}
...@@ -19,6 +19,7 @@ ...@@ -19,6 +19,7 @@
"test-data-service/*": ["./test/lib/test-data-service/*"], "test-data-service/*": ["./test/lib/test-data-service/*"],
"test-log": ["./test/lib/test-log"], "test-log": ["./test/lib/test-log"],
"router-act": ["./test/lib/router-act"], "router-act": ["./test/lib/router-act"],
"otel-span-tree": ["./test/lib/otel-span-tree"],
"@next/playwright": ["./packages/next-playwright/src/index.ts"] "@next/playwright": ["./packages/next-playwright/src/index.ts"]
} }
}, },
......
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