Unverified Commit 4abb437d authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Keep middleware and render in one OpenTelemetry trace as siblings (#100294)

## Summary

Stacked on #100349 (request span before route module preparation).

Relands #100136 (reverted in f1a69d7d) and changes the span shape so
middleware and the route are **siblings** in one trace per request.

### Resulting shapes

```
next start / next dev:
 handleRequest GET (bubble, root)
  ├─ middleware GET
  └─ GET /page

next start / next dev with host span / incoming traceparent P:
 P
  └─ handleRequest GET (bubble)
      ├─ middleware GET
      └─ GET /page

separately-invoked middleware (Vercel, adapters, direct entrypoints), no parent:
 GET (Next.request, root, inserted by the middleware adapter)
  ├─ middleware GET
  └─ GET /page

separately-invoked middleware with host span / incoming traceparent P:
 P
  ├─ middleware GET
  └─ GET /page
```

### How

- **Self-hosted:** next-server's middleware-invoke `handleRequest` pass
writes its W3C context onto the request (`traceparent`, and `tracestate`
only together with it: a received `tracestate` is removed when the
context has none). Middleware (Node in-process, or the Edge sandbox via
the header) and the render pass both continue it. The render pass forces
that extraction even under an active host span (custom server / APM), so
it nests under the bubble span; a different `traceparent` the middleware
explicitly set still wins.
- **Middleware adapter:** an active host span wins over a request
`traceparent`; otherwise the request's `traceparent` is continued, and
the middleware never changes it. Without any valid context (and OTEL
enabled) the adapter inserts a `Next.request` SERVER span (new
`NextSpan` enum) named after the method (`http.target` keeps the path).
When the downstream request doesn't already carry that shared parent,
its `traceparent`/`tracestate` are forwarded via the existing
`x-middleware-request-*` overrides, always as a pair: a user-set
`traceparent` keeps exactly the trace headers the user set. No headers
are added without OTEL.
- Request-header overrides replace the whole header set, so when the
user set no overrides, the received headers are listed alongside the
trace headers. There's no API to add a single header yet; that needs a
server and platform change.
- Node middleware is no longer detached via `ROOT_CONTEXT` (the 16.3
regression from #95306).

The inserted `Next.request` root ends when the middleware finishes, so
the render child (a separate invocation) can outlive it.

## Verification

- Trace shapes are asserted as printed span trees
(`test/lib/otel-span-tree.ts`, from #100349) in inline snapshots. Span
IDs are normalized away, but distinct traces keep distinct labels, so a
split trace shows up as `[trace A]` / `[trace B]`.
- `test/e2e/app-dir/otel-middleware-trace` (added in #100349 with the
previous behavior): this PR's snapshot diff shows middleware and render
becoming siblings in one trace, in dev, start, Cache Components and
deploy, for Node.js and Edge middleware and behind a custom server with
a host span (including an incoming `tracestate` not being paired with
the host span's context).
- Collector suite `test/e2e/opentelemetry/instrumentation`: the
middleware test asserts the full span tree in next start/dev, direct
entrypoints with/without host span, and the custom server (host span,
user-set `traceparent`).
- Unit tests for the tracer and `forwardTraceContextToRequest` changes.
- `test/e2e/middleware-request-header-overrides`,
`test/production/typescript-basic`,
`test/production/middleware-typescript` pass.

<!-- 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 avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by: 's avatarLuke Sandberg <210140+lukesandberg@users.noreply.github.com>
Co-authored-by: 's avatarNiklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
parent e3c2f637
...@@ -885,87 +885,137 @@ export default abstract class Server< ...@@ -885,87 +885,137 @@ export default abstract class Server<
const method = req.method.toUpperCase() const method = req.method.toUpperCase()
const tracer = getTracer() const tracer = getTracer()
const handleRequest = () => const handleRequest = () => {
tracer.withPropagatedContext(req.headers, () => { // The render pass after a middleware invocation continues the trace
// Capture the parent span before creating the handleRequest span. // context on the request, even when another span is active (e.g. a
// When deployed with an adapter, the platform's runtime may create its // custom server or APM HTTP span). That is the context the
// own OTEL HTTP server span before Next.js runs. We propagate http.route // middleware-invoke pass wrote onto the request, so the middleware span
// to this parent span so APM tools (e.g. Datadog) can derive the // and the render are siblings under that pass's span, or a `traceparent`
// resource name correctly. // the middleware explicitly set as a request-header override.
const parentSpan = tracer.getActiveScopeSpan() const forcePropagation =
!getRequestMeta(req, 'middlewareInvoke') &&
return tracer.trace( getRequestMeta(req, 'middlewareInvokeTraceparent') !== undefined
BaseServerSpan.handleRequest, // With forced propagation the active (host) span isn't the parent, so
{ // capture it before propagating to keep propagating `http.route` to it.
spanName: `${method}`, const hostSpan = forcePropagation
kind: SpanKind.SERVER, ? tracer.getActiveScopeSpan()
attributes: { : undefined
'http.method': method,
'http.target': req.url, return tracer.withPropagatedContext(
req.headers,
() => {
// Capture the parent span before creating the handleRequest span.
// When deployed with an adapter, the platform's runtime may create its
// own OTEL HTTP server span before Next.js runs. We propagate http.route
// to this parent span so APM tools (e.g. Datadog) can derive the
// resource name correctly.
const parentSpan = forcePropagation
? hostSpan
: tracer.getActiveScopeSpan()
return tracer.trace(
BaseServerSpan.handleRequest,
{
spanName: `${method}`,
kind: SpanKind.SERVER,
attributes: {
'http.method': method,
'http.target': req.url,
},
}, },
}, async (span) => {
async (span) => if (getRequestMeta(req, 'middlewareInvoke')) {
this.handleRequestImpl(req, res, parsedUrl).finally(() => { // When middleware lets the request continue, the router server
if (!span) return // calls `handleRequest` twice: once to run middleware (this pass)
// and once to render. Publish this span's W3C trace context on
const isRSCRequest = getRequestMeta(req, 'isRSCRequest') ?? false // the request, so the middleware span (including the Edge
span.setAttributes({ // sandbox, which extracts it from the request headers) and the
'http.status_code': res.statusCode, // render pass are both children of this span (siblings) instead
'next.rsc': isRSCRequest, // of starting new traces.
}) const traceContext = tracer.getTraceContextHeaders()
if (traceContext) {
if (res.statusCode && res.statusCode >= 500) { Object.assign(req.headers, traceContext)
// For 5xx status codes: SHOULD be set to 'Error' span status. if (!traceContext.tracestate) {
// x-ref: https://opentelemetry.io/docs/specs/semconv/http/http-spans/#status // Don't pair this span's `traceparent` with a
span.setStatus({ // `tracestate` of another trace context (e.g. an incoming
code: SpanStatusCode.ERROR, // one, when a host span is this span's parent).
}) delete req.headers.tracestate
// For span status 'Error', SHOULD set 'error.type' attribute. }
span.setAttribute('error.type', res.statusCode.toString()) addRequestMeta(
} req,
'middlewareInvokeTraceparent',
const rootSpanAttributes = tracer.getRootSpanAttributes() traceContext.traceparent
// We were unable to get attributes, probably OTEL is not enabled )
if (!rootSpanAttributes) return }
if (
rootSpanAttributes.get('next.span_type') !==
BaseServerSpan.handleRequest
) {
console.warn(
`Unexpected root span type '${rootSpanAttributes.get(
'next.span_type'
)}'. Please report this Next.js issue https://github.com/vercel/next.js`
)
return
} }
const route = rootSpanAttributes.get('next.route') return this.handleRequestImpl(req, res, parsedUrl).finally(() => {
if (route) { if (!span) return
const name = isRSCRequest
? `RSC ${method} ${route}`
: `${method} ${route}`
const isRSCRequest =
getRequestMeta(req, 'isRSCRequest') ?? false
span.setAttributes({ span.setAttributes({
'next.route': route, 'http.status_code': res.statusCode,
'http.route': route, 'next.rsc': isRSCRequest,
'next.span_name': name,
}) })
span.updateName(name)
if (res.statusCode && res.statusCode >= 500) {
// Propagate http.route to the parent span if one exists and // For 5xx status codes: SHOULD be set to 'Error' span status.
// is different from the handleRequest span. This ensures APM // x-ref: https://opentelemetry.io/docs/specs/semconv/http/http-spans/#status
// tools that read attributes from the outermost span (e.g. span.setStatus({
// a platform-created HTTP span) can derive the resource name. code: SpanStatusCode.ERROR,
if (parentSpan && parentSpan !== span) { })
parentSpan.setAttribute('http.route', route) // For span status 'Error', SHOULD set 'error.type' attribute.
span.setAttribute('error.type', res.statusCode.toString())
} }
} else {
span.updateName(isRSCRequest ? `RSC ${method}` : `${method}`) const rootSpanAttributes = tracer.getRootSpanAttributes()
} // We were unable to get attributes, probably OTEL is not enabled
}) if (!rootSpanAttributes) return
)
}) if (
rootSpanAttributes.get('next.span_type') !==
BaseServerSpan.handleRequest
) {
console.warn(
`Unexpected root span type '${rootSpanAttributes.get(
'next.span_type'
)}'. Please report this Next.js issue https://github.com/vercel/next.js`
)
return
}
const route = rootSpanAttributes.get('next.route')
if (route) {
const name = isRSCRequest
? `RSC ${method} ${route}`
: `${method} ${route}`
span.setAttributes({
'next.route': route,
'http.route': route,
'next.span_name': name,
})
span.updateName(name)
// Propagate http.route to the parent span if one exists and
// is different from the handleRequest span. This ensures APM
// tools that read attributes from the outermost span (e.g.
// a platform-created HTTP span) can derive the resource name.
if (parentSpan && parentSpan !== span) {
parentSpan.setAttribute('http.route', route)
}
} else {
span.updateName(isRSCRequest ? `RSC ${method}` : `${method}`)
}
})
}
)
},
undefined,
forcePropagation
)
}
if (!isRequestInsightsEnabled()) { if (!isRequestInsightsEnabled()) {
return handleRequest() return handleRequest()
......
...@@ -132,6 +132,13 @@ enum MiddlewareSpan { ...@@ -132,6 +132,13 @@ enum MiddlewareSpan {
execute = 'Middleware.execute', execute = 'Middleware.execute',
} }
enum NextSpan {
// Root span inserted by the middleware adapter when the request has no
// trace context (separately invoked middleware without a parent), so the
// middleware and the render are siblings in one trace.
request = 'Next.request',
}
type SpanTypes = type SpanTypes =
| `${BaseServerSpan}` | `${BaseServerSpan}`
| `${LoadComponentsSpan}` | `${LoadComponentsSpan}`
...@@ -149,10 +156,12 @@ type SpanTypes = ...@@ -149,10 +156,12 @@ type SpanTypes =
| `${RouteModuleSpan}` | `${RouteModuleSpan}`
| `${ResolveMetadataSpan}` | `${ResolveMetadataSpan}`
| `${MiddlewareSpan}` | `${MiddlewareSpan}`
| `${NextSpan}`
// This list is used to filter out spans that are not relevant to the user // This list is used to filter out spans that are not relevant to the user
export const NextVanillaSpanAllowlist = new Set([ export const NextVanillaSpanAllowlist = new Set([
MiddlewareSpan.execute, MiddlewareSpan.execute,
NextSpan.request,
BaseServerSpan.handleRequest, BaseServerSpan.handleRequest,
RenderSpan.getServerSideProps, RenderSpan.getServerSideProps,
RenderSpan.getStaticProps, RenderSpan.getStaticProps,
...@@ -200,6 +209,7 @@ export { ...@@ -200,6 +209,7 @@ export {
RouteModuleSpan, RouteModuleSpan,
ResolveMetadataSpan, ResolveMetadataSpan,
MiddlewareSpan, MiddlewareSpan,
NextSpan,
} }
export type { SpanTypes } export type { SpanTypes }
...@@ -7,6 +7,7 @@ import type { ...@@ -7,6 +7,7 @@ import type {
ContextManager, ContextManager,
TextMapGetter, TextMapGetter,
TextMapPropagator, TextMapPropagator,
TextMapSetter,
} from '@opentelemetry/api' } from '@opentelemetry/api'
import type { WorkStore } from '../../app-render/work-async-storage.external' import type { WorkStore } from '../../app-render/work-async-storage.external'
import type { WorkUnitStore } from '../../app-render/work-unit-async-storage.external' import type { WorkUnitStore } from '../../app-render/work-unit-async-storage.external'
...@@ -127,6 +128,48 @@ class CustomPropagator implements TextMapPropagator { ...@@ -127,6 +128,48 @@ class CustomPropagator implements TextMapPropagator {
} }
} }
// A minimal W3C `traceparent` propagator (`@opentelemetry/core` isn't a
// dependency here).
class TraceparentPropagator implements TextMapPropagator {
fields(): string[] {
return ['traceparent']
}
inject(
injectedContext: Context,
carrier: unknown,
setter: TextMapSetter<unknown>
): void {
const spanContext = trace.getSpanContext(injectedContext)
if (!spanContext) return
const flags = spanContext.traceFlags.toString(16).padStart(2, '0')
setter.set(
carrier,
'traceparent',
`00-${spanContext.traceId}-${spanContext.spanId}-${flags}`
)
}
extract(
extractedContext: Context,
carrier: Record<string, string | undefined>,
mapGetter: TextMapGetter<Record<string, string | undefined>>
): Context {
const value = mapGetter.get(carrier, 'traceparent')
const [, traceId, spanId, flags] =
(typeof value === 'string' && value.split('-')) || []
if (!traceId || !spanId || !flags) {
return extractedContext
}
return trace.setSpanContext(extractedContext, {
traceId,
spanId,
traceFlags: parseInt(flags, 16),
isRemote: true,
})
}
}
describe('withPropagatedContext', () => { describe('withPropagatedContext', () => {
beforeEach(() => { beforeEach(() => {
context.disable() context.disable()
...@@ -171,6 +214,74 @@ describe('withPropagatedContext', () => { ...@@ -171,6 +214,74 @@ describe('withPropagatedContext', () => {
}) })
}) })
describe('trace context with the W3C propagator', () => {
const TRACE_ID = '0af7651916cd43dd8448eb211c80319c'
const SPAN_ID = 'b7ad6b7169203331'
beforeEach(() => {
context.disable()
propagation.disable()
context.setGlobalContextManager(new TestContextManager())
propagation.setGlobalPropagator(new TraceparentPropagator())
})
afterEach(() => {
propagation.disable()
context.disable()
})
const withSpanContext = <T>(
spanContext: Parameters<typeof trace.wrapSpanContext>[0],
fn: () => T
) =>
context.with(
trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext)),
fn
)
it('prefers the carrier traceparent over the active span in force mode', () => {
const result = withSpanContext(
{
traceId: '0123456789abcdef0123456789abcdef',
spanId: '0123456789abcdef',
traceFlags: 1,
isRemote: false,
},
() =>
getTracer().withPropagatedContext(
{ traceparent: `00-${TRACE_ID}-${SPAN_ID}-01` },
() => trace.getSpanContext(context.active()),
getter,
true
)
)
expect(result).toMatchObject({ traceId: TRACE_ID, spanId: SPAN_ID })
})
it('always includes the tracestate key in the trace context headers', () => {
const spanContext = {
traceId: TRACE_ID,
spanId: SPAN_ID,
traceFlags: 1,
isRemote: false,
}
// A recording span, so OpenTelemetry counts as enabled.
const span = Object.assign(trace.wrapSpanContext(spanContext), {
isRecording: () => true,
})
const result = context.with(trace.setSpan(ROOT_CONTEXT, span), () =>
getTracer().getTraceContextHeaders()
)
expect(result).toStrictEqual({
traceparent: `00-${TRACE_ID}-${SPAN_ID}-01`,
tracestate: undefined,
})
})
})
describe('local span recording', () => { describe('local span recording', () => {
beforeEach(() => { beforeEach(() => {
process.env.__NEXT_DEV_SERVER = '1' process.env.__NEXT_DEV_SERVER = '1'
......
...@@ -186,6 +186,26 @@ interface NextTracer { ...@@ -186,6 +186,26 @@ interface NextTracer {
*/ */
getTracePropagationData(): ClientTraceDataEntry[] getTracePropagationData(): ClientTraceDataEntry[]
/**
* Returns the W3C trace context (`traceparent` / `tracestate`) of the
* currently active context, as produced by the configured propagator.
* Returns `undefined` when OpenTelemetry is not enabled, no span context is
* active, or the propagator doesn't produce a `traceparent`.
*/
getTraceContextHeaders(): TraceContextHeaders | undefined
/**
* Whether OpenTelemetry is enabled: a tracer provider is registered, or a
* recording span is active.
*/
isOpenTelemetryEnabled(): boolean
/**
* Whether the currently active context has a valid span context: an active
* span, or a remote parent extracted from incoming trace headers.
*/
hasActiveSpanContext(): boolean
/** /**
* Executes a function with the given span set as the active span in the context. * Executes a function with the given span set as the active span in the context.
* This allows child spans created within the function to automatically parent to this span. * This allows child spans created within the function to automatically parent to this span.
...@@ -219,6 +239,11 @@ export interface ClientTraceDataEntry { ...@@ -219,6 +239,11 @@ export interface ClientTraceDataEntry {
value: string value: string
} }
export interface TraceContextHeaders {
traceparent: string
tracestate?: string
}
const clientTraceDataSetter: TextMapSetter<ClientTraceDataEntry[]> = { const clientTraceDataSetter: TextMapSetter<ClientTraceDataEntry[]> = {
set(carrier, key, value) { set(carrier, key, value) {
carrier.push({ carrier.push({
...@@ -238,7 +263,7 @@ class NextTracerImpl implements NextTracer { ...@@ -238,7 +263,7 @@ class NextTracerImpl implements NextTracer {
return trace.getTracer('next.js', process.env.__NEXT_VERSION) return trace.getTracer('next.js', process.env.__NEXT_VERSION)
} }
private isOpenTelemetryEnabled(): boolean { public isOpenTelemetryEnabled(): boolean {
const activeSpan = trace.getSpan(context.active()) const activeSpan = trace.getSpan(context.active())
if (activeSpan?.isRecording()) { if (activeSpan?.isRecording()) {
return true return true
...@@ -268,6 +293,30 @@ class NextTracerImpl implements NextTracer { ...@@ -268,6 +293,30 @@ class NextTracerImpl implements NextTracer {
return entries return entries
} }
public getTraceContextHeaders(): TraceContextHeaders | undefined {
const activeContext = context.active()
if (
!trace.getSpanContext(activeContext) ||
!this.isOpenTelemetryEnabled()
) {
return undefined
}
const carrier: Record<string, string> = {}
propagation.inject(activeContext, carrier)
const { traceparent, tracestate } = carrier
if (!traceparent) {
return undefined
}
return { traceparent, tracestate }
}
public hasActiveSpanContext(): boolean {
const spanContext = trace.getSpanContext(context.active())
return Boolean(spanContext && trace.isSpanContextValid(spanContext))
}
public getActiveScopeSpan(): Span | undefined { public getActiveScopeSpan(): Span | undefined {
const localSpanRecorder = getLocalSpanRecorder() const localSpanRecorder = getLocalSpanRecorder()
const activeLocalSpan = localSpanRecorder?.getActiveLocalSpan() const activeLocalSpan = localSpanRecorder?.getActiveLocalSpan()
...@@ -285,19 +334,6 @@ class NextTracerImpl implements NextTracer { ...@@ -285,19 +334,6 @@ class NextTracerImpl implements NextTracer {
return activeLocalSpan return activeLocalSpan
} }
/**
* Run `fn` with the active span cleared, so spans created inside become new
* roots (or parent to incoming propagated context). Used for in-process
* Node.js middleware so its span is a sibling of the request span, matching
* edge middleware which runs in a detached sandbox.
*/
public runWithDetachedContext<T>(fn: () => T): T {
if (!NEXT_OTEL_PERFORMANCE_PREFIX && !this.isOpenTelemetryEnabled()) {
return fn()
}
return context.with(ROOT_CONTEXT, fn)
}
public withPropagatedContext<T, C>( public withPropagatedContext<T, C>(
carrier: C, carrier: C,
fn: () => T, fn: () => T,
......
...@@ -1741,24 +1741,21 @@ export default class NextNodeServer extends BaseServer< ...@@ -1741,24 +1741,21 @@ export default class NextNodeServer extends BaseServer<
try { try {
// Node.js middleware runs in-process, inside the active // Node.js middleware runs in-process, inside the active
// `handleRequest` span. Detach that span so the middleware span // `handleRequest` span, so the middleware span (and the trace context
// becomes a sibling root (or parents to an incoming traceparent), // it forwards to the render) stays in the request's trace.
// matching edge middleware which runs in a detached sandbox. result = await adapterFn({
result = await getTracer().runWithDetachedContext(() => handler:
adapterFn({ middlewareModule.proxy ||
handler: middlewareModule.middleware ||
middlewareModule.proxy || middlewareModule,
middlewareModule.middleware || request: {
middlewareModule, ...requestData,
request: { body: hasRequestBody
...requestData, ? requestData.body.cloneBodyStream()
body: hasRequestBody : undefined,
? requestData.body.cloneBodyStream() },
: undefined, page: 'middleware',
}, })
page: 'middleware',
})
)
} finally { } finally {
if (hasRequestBody) { if (hasRequestBody) {
await requestData.body.finalize() await requestData.body.finalize()
......
...@@ -223,6 +223,13 @@ export interface RequestMeta { ...@@ -223,6 +223,13 @@ export interface RequestMeta {
*/ */
middlewareInvoke?: boolean middlewareInvoke?: boolean
/**
* The W3C `traceparent` of the middleware invocation's `handleRequest` span,
* written onto the request headers so the middleware span and the render
* that follows are siblings under that span.
*/
middlewareInvokeTraceparent?: string
/** /**
* Whether the request should render the fallback shell or not. * Whether the request should render the fallback shell or not.
*/ */
......
This diff is collapsed.
import {
forwardTraceContextToRequest,
getSharedParentTraceContext,
} from './forward-trace-context'
import { NextResponse } from './spec-extension/response'
const TRACEPARENT = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
const TRACESTATE = 'vendor=value'
const RECEIVED_TRACEPARENT =
'00-11111111111111111111111111111111-2222222222222222-01'
function requestOverrides(headers: Headers) {
const list = headers.get('x-middleware-override-headers')
if (list === null) return undefined
return Object.fromEntries(
list
.split(',')
.filter(Boolean)
.map((key) => [key, headers.get(`x-middleware-request-${key}`)])
)
}
describe('getSharedParentTraceContext', () => {
it('uses the received trace headers verbatim when they are the active context', () => {
const received = new Headers({
traceparent: RECEIVED_TRACEPARENT,
// Not normalized by the propagator.
tracestate: 'a=1 ,b=2',
})
expect(
getSharedParentTraceContext(received, {
traceparent: RECEIVED_TRACEPARENT,
tracestate: 'a=1,b=2',
})
).toEqual({ traceparent: RECEIVED_TRACEPARENT, tracestate: 'a=1 ,b=2' })
})
it('keeps the tracestate key when the received trace headers have none', () => {
const received = new Headers({ traceparent: RECEIVED_TRACEPARENT })
expect(
getSharedParentTraceContext(received, {
traceparent: RECEIVED_TRACEPARENT,
tracestate: undefined,
})
).toStrictEqual({
traceparent: RECEIVED_TRACEPARENT,
tracestate: undefined,
})
})
it('uses the active context when the request carries none', () => {
expect(
getSharedParentTraceContext(new Headers(), {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
).toEqual({ traceparent: TRACEPARENT, tracestate: TRACESTATE })
})
})
describe('forwardTraceContextToRequest', () => {
const requestHeaders = () =>
new Headers({ accept: 'text/html', cookie: 'a=b', 'x-custom': 'custom' })
it('adds nothing when the request already carries the trace context', () => {
const received = requestHeaders()
received.set('traceparent', RECEIVED_TRACEPARENT)
received.set('tracestate', 'received=1')
const response = NextResponse.next()
forwardTraceContextToRequest(response.headers, received, {
traceparent: RECEIVED_TRACEPARENT,
tracestate: 'received=1',
})
expect([...response.headers.keys()]).toEqual(['x-middleware-next'])
})
it('lists every request header plus the trace context when the request carries none', () => {
const response = NextResponse.next()
forwardTraceContextToRequest(response.headers, requestHeaders(), {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
expect(requestOverrides(response.headers)).toEqual({
accept: 'text/html',
cookie: 'a=b',
'x-custom': 'custom',
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
})
it('appends the trace context to user overrides that omit it', () => {
const userHeaders = new Headers({ 'x-user': 'user' })
const response = NextResponse.next({ request: { headers: userHeaders } })
forwardTraceContextToRequest(response.headers, requestHeaders(), {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
expect(requestOverrides(response.headers)).toEqual({
'x-user': 'user',
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
})
it('drops a received tracestate when the trace context has none', () => {
const received = requestHeaders()
received.set('tracestate', 'received=1')
const response = NextResponse.next()
forwardTraceContextToRequest(response.headers, received, {
traceparent: TRACEPARENT,
})
expect(requestOverrides(response.headers)).toEqual({
accept: 'text/html',
cookie: 'a=b',
'x-custom': 'custom',
traceparent: TRACEPARENT,
})
})
it('drops a tracestate copied into user overrides when the trace context has none', () => {
const received = requestHeaders()
received.set('traceparent', RECEIVED_TRACEPARENT)
received.set('tracestate', 'received=1')
const response = NextResponse.next({
request: { headers: new Headers(received) },
})
forwardTraceContextToRequest(response.headers, received, {
traceparent: TRACEPARENT,
})
expect(requestOverrides(response.headers)).toEqual({
accept: 'text/html',
cookie: 'a=b',
'x-custom': 'custom',
traceparent: TRACEPARENT,
})
})
it('replaces a tracestate set by the user when the traceparent is forwarded', () => {
const response = NextResponse.next({
request: { headers: new Headers({ tracestate: 'user=1' }) },
})
forwardTraceContextToRequest(response.headers, requestHeaders(), {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
expect(requestOverrides(response.headers)).toEqual({
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
})
it('keeps a traceparent explicitly set by the user without a forwarded tracestate', () => {
const userTraceparent =
'00-33333333333333333333333333333333-4444444444444444-01'
const response = NextResponse.next({
request: { headers: new Headers({ traceparent: userTraceparent }) },
})
forwardTraceContextToRequest(response.headers, requestHeaders(), {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
expect(requestOverrides(response.headers)).toEqual({
traceparent: userTraceparent,
})
})
it('keeps the trace headers explicitly set by the user', () => {
const userTraceparent =
'00-33333333333333333333333333333333-4444444444444444-01'
const received = requestHeaders()
received.set('tracestate', 'received=1')
const response = NextResponse.next({
request: {
headers: new Headers({
traceparent: userTraceparent,
tracestate: 'user=1',
}),
},
})
forwardTraceContextToRequest(response.headers, received, {
traceparent: TRACEPARENT,
tracestate: TRACESTATE,
})
expect(requestOverrides(response.headers)).toEqual({
traceparent: userTraceparent,
tracestate: 'user=1',
})
})
})
import type { TraceContextHeaders } from '../lib/trace/tracer'
const OVERRIDE_HEADERS = 'x-middleware-override-headers'
const REQUEST_HEADER_PREFIX = 'x-middleware-request-'
// The trace ID and parent ID of a W3C `traceparent`
// (`version-traceid-parentid-flags`), lower-cased.
function getTraceparentIds(traceparent: string | null | undefined) {
const [, traceId, parentId] = traceparent?.toLowerCase().split('-') ?? []
return traceId && parentId ? `${traceId}-${parentId}` : undefined
}
/**
* The trace context of the span that the middleware span and the downstream
* request (the render) share as their parent, given the middleware's active
* context (before the middleware span starts).
*
* When the active context is the one the request carries (an incoming
* `traceparent`, or the one next-server's middleware-invoke pass wrote onto
* the request), the received `traceparent` / `tracestate` are returned
* verbatim, so the middleware never changes them. Otherwise (an active host
* span, or a root span inserted by the middleware adapter) the active
* context is returned.
*/
export function getSharedParentTraceContext(
requestHeaders: Headers,
activeTraceContext: TraceContextHeaders | undefined
): TraceContextHeaders | undefined {
if (!activeTraceContext) {
return undefined
}
const receivedTraceparent = requestHeaders.get('traceparent')
const receivedIds = getTraceparentIds(receivedTraceparent)
if (
receivedTraceparent &&
receivedIds &&
receivedIds === getTraceparentIds(activeTraceContext.traceparent)
) {
const receivedTracestate = requestHeaders.get('tracestate')
return receivedTracestate
? { traceparent: receivedTraceparent, tracestate: receivedTracestate }
: { traceparent: receivedTraceparent, tracestate: undefined }
}
return activeTraceContext
}
/**
* Makes sure the downstream request of a middleware response that continues
* the request (`NextResponse.next()` or a rewrite) carries the trace context
* of the middleware span's parent, so the render is a sibling of the
* middleware span in the same trace. It is passed as `traceparent` /
* `tracestate` request-header overrides, which every host applies to the
* downstream request: hosts that invoke middleware separately from the render
* (deployments, adapters, direct entrypoints) as well as next-server's router
* server.
*
* `traceparent` and `tracestate` are forwarded as a pair: the downstream
* request never carries one trace context's `traceparent` with another's
* `tracestate`. Request-header overrides replace the whole downstream request
* header set, so:
* - Without user overrides (or with an empty list, which hosts ignore):
* nothing is added when the request already carries that trace context.
* Otherwise every request header the middleware received is listed
* (unchanged) alongside the trace context, except a received `tracestate`
* when the trace context has none.
* - With user overrides, they are kept and the trace context headers are
* added. A `traceparent` the user explicitly set (to a value other than the
* one the middleware received) wins, together with whatever `tracestate`
* the user set (if any). Otherwise (`traceparent` copied unchanged from the
* request, e.g. via `new Headers(request.headers)`, or omitted) both are set
* to the trace context, dropping a user `tracestate` when it has none.
*/
export function forwardTraceContextToRequest(
responseHeaders: Headers,
requestHeaders: Headers,
traceContext: TraceContextHeaders | undefined
): void {
if (!traceContext) {
return
}
// Redirects and direct responses have no downstream request.
if (
!responseHeaders.has('x-middleware-next') &&
!responseHeaders.has('x-middleware-rewrite')
) {
return
}
const userOverrides = responseHeaders.get(OVERRIDE_HEADERS)
// An empty override list is ignored by hosts (no headers are replaced), so
// treat it like no overrides rather than turning it into "only the trace
// context headers".
if (!userOverrides) {
if (
requestHeaders.get('traceparent') === traceContext.traceparent &&
requestHeaders.get('tracestate') === (traceContext.tracestate ?? null)
) {
// The downstream request already carries the trace context.
return
}
const keys: string[] = []
for (const [key, value] of requestHeaders) {
if (!isTraceHeader(key)) {
responseHeaders.set(REQUEST_HEADER_PREFIX + key, value)
keys.push(key)
}
}
setTraceContextOverrides(responseHeaders, keys, traceContext)
return
}
const keys = userOverrides
.split(',')
.map((key) => key.trim())
.filter(Boolean)
if (
keys.includes('traceparent') &&
responseHeaders.get(REQUEST_HEADER_PREFIX + 'traceparent') !==
requestHeaders.get('traceparent')
) {
// The user explicitly set the `traceparent`: keep both trace headers as
// the user set them.
return
}
setTraceContextOverrides(
responseHeaders,
keys.filter((key) => !isTraceHeader(key)),
traceContext
)
}
function isTraceHeader(key: string) {
return key === 'traceparent' || key === 'tracestate'
}
// Lists the trace context's `traceparent` and `tracestate` (or no
// `tracestate`, if it has none) as request-header overrides, after `keys`
// (the other overridden headers).
function setTraceContextOverrides(
responseHeaders: Headers,
keys: string[],
traceContext: TraceContextHeaders
) {
responseHeaders.set(
REQUEST_HEADER_PREFIX + 'traceparent',
traceContext.traceparent
)
keys.push('traceparent')
if (traceContext.tracestate) {
responseHeaders.set(
REQUEST_HEADER_PREFIX + 'tracestate',
traceContext.tracestate
)
keys.push('tracestate')
} else {
responseHeaders.delete(REQUEST_HEADER_PREFIX + 'tracestate')
}
responseHeaders.set(OVERRIDE_HEADERS, keys.join(','))
}
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