[sokra]

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 docs: note that instrumentation-time spans don't join request traces #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.

[github-actions]

Tests Passed

Commit: c8bff0e

[sokra]

Reviewed 9df28d3