Emit instrumentation lifecycle spans in the request that registered it (#100350)
## Summary
Stacked on #100324. Includes the commits from #100392, which were folded
into this PR.
Next.js emits two lifecycle spans for `instrumentation.ts` in the
Node.js runtime: `load instrumentation module` and `register
instrumentation`. They're backdated, because they're emitted after
`register()` returns (`register()` usually installs the tracer
provider). Until now they were always separate root traces.
Direct entrypoints (Vercel, adapters, standalone handlers) register
instrumentation lazily, in the first request. That split the first
request's work across extra traces. Now the spans join the trace of the
request that triggered registration:
```
route / page entrypoint:
[P →] GET /page (BaseServer.handleRequest, backdated to cover registration)
├─ load instrumentation module
├─ register instrumentation
└─ prepare route module → render …
Node.js middleware entrypoint, no parent:
GET (Next.request, backdated)
├─ middleware GET (backdated to cover registration)
│ ├─ load instrumentation module
│ └─ register instrumentation
└─ GET /page
Node.js middleware entrypoint with host span / incoming traceparent P:
P
├─ middleware GET (backdated to cover registration)
│ ├─ load instrumentation module
│ └─ register instrumentation
└─ GET /page
```
### How
- `ensureInstrumentationRegisteredWithDeferredSpans`: when this call
starts registration and registration succeeds, the lifecycle spans are
recorded instead of emitted. The function returns an idempotent emitter
to that caller only. Concurrent callers, later callers and startup
callers get nothing.
- `RouteModule.ensureInstrumentation(req, { deferSpans: true })` is
called by the templates before `traceRequest`. It records when the
request started and returns that time, together with the emitter, as
`instrumentation`. `traceRequest` takes it as an option, backdates the
request span to that time, and emits the lifecycle spans as the span's
first children.
- The Node.js middleware template passes the emitter and the start time
to the adapter. The adapter calls the emitter first thing inside the
`Middleware.execute` span and backdates that span to the request start.
- The shared parent (incoming `traceparent`, host span, or the backdated
inserted `Next.request` root) is still captured before entering the
middleware span. The middleware and the render stay siblings, and
`traceparent` handling and forwarding are unchanged.
- Unchanged:
- `next start` / `next dev` startup registration (separate roots).
- Registration errors: emitted immediately with the same statuses,
including non-`Error` throws.
- Edge (no lifecycle spans).
- No `instrumentation.ts`, or no `register` export.
- User-created spans in `instrumentation.ts` are out of scope (see
#100324).
## Verification
- Collector suite, cold direct entrypoints:
- Route/page requests, with and without an incoming `traceparent`, and
with a host span.
- Node.js middleware requests: no parent, incoming `traceparent`, host
span.
- Each test asserts exactly one load span and one register span in the
request's trace, parented as shown above and covered by the backdated
parent. For middleware, the parent is the middleware span, and it starts
no later than the lifecycle spans and no earlier than its own parent.
- Direct-entrypoint single-trace assertions no longer exclude lifecycle
spans as startup work. Under `next start`, startup spans stay roots.
Fail-first verified.
- Deploy-capable `test/e2e/app-dir/otel-middleware-trace`: span tree
snapshots of the lifecycle spans with their ancestors, plus the first
request's tree including them.
- Deployed: children of the request span that triggered registration, or
of `middleware GET` for Node.js middleware.
- `next dev` / `next start`: startup roots.
- No deploy gate.
- Unit tests for the deferral helper: once-only, concurrency, startup
ownership, no `register`, `register()` errors (including `throw
undefined`), and module-load failure.
<!-- NEXT_JS_LLM -->
<!-- fleet ce0ecb23-b14c-4679-92a9-e676130f618e -->
---------
Co-authored-by:
vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by:
Tobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by:
Luke Sandberg <210140+lukesandberg@users.noreply.github.com>
Co-authored-by:
Niklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
Showing
Please
register
or
sign in
to comment