vercel/next.js PR #97439 — OpenTelemetry tracing for App Route lazy loading — PR #97439
vercel/next.js · pull request #97439 ·
Transcript
PlainEnglish
Let's walk through PR ninety-seven thousand four hundred thirty-nine for Next.js. This change adds OpenTelemetry tracing to App Route lazy loading. It touches five files with about eighty-seven additions.
PlainEnglish
This PR is pursuing one main goal: adding tracing to App Route module loading. The supporting work validates the span lifecycle, registers the new span type in the tracing system, and ensures test coverage for local span recording.
PlainEnglish
App Route handlers in Next.js load on demand using a lazy module pattern. Before this change, that loading happened during request handling but wasn't traced. Observability integrations couldn't see how long route handlers took to initialize. This PR wraps the load call in an OpenTelemetry span, making initialization time visible and enabling performance debugging for slow startups.
Architecture
The change touches five files across the tracing system and the app route module. The core instrumentation lives in module dot t-s, with the new span type defined in constants. Test coverage spans both unit tests and a new end-to-end validation.
Architecture
First, we register the new span type. The code defines an AppRouteRouteModuleSpan enum with a loadUserland entry, adds it to the SpanTypes union, and includes it in the NextVanillaSpanAllowlist. This ensures the span emits when tracing is enabled.
Architecture
Here's the core change. The module loader wraps the loadUserland call with getTracer dot trace. The span captures the route pathname as an attribute and times the entire module initialization. The wrapper preserves the existing LazyModule pattern, so subsequent requests reuse the cached module without re-tracing.
Architecture
The PR includes a comprehensive end-to-end test. It validates the span is emitted on cold load with the right name and route attribute, confirms it's a child of the request-handling span, and ensures the span is only emitted once. Subsequent requests hit the cached module without triggering a new span.
Architecture
The tracer unit tests also cover the new span type. The test imports AppRouteRouteModuleSpan and validates it appears in recorded spans for both vanilla span recording mode and request insights mode.
PlainEnglish
After this PR lands, App Route handlers emit an OpenTelemetry span when their module is first loaded. The span includes the route pathname as an attribute and is a child of the request span. Observability integrations can now measure and analyze the time spent initializing app route handlers, supporting performance debugging and monitoring.
CodeQuality
One thing to keep an eye on. The test uses skipDeployment true at line sixteen eighteen. According to the test guidelines, this should only be allowed when the assertion is specific to self-hosted behavior. The rationale for skipping deployment-mode testing isn't documented. It's worth verifying whether App Route module loading tracing has different semantics in deployed Vercel environments that justify skipping deploy-mode validation.
PlainEnglish
This is a clean, focused observability improvement. The core instrumentation is straightforward, the test coverage is solid, and the span lifecycle is correctly scoped. I'd approve with one note: confirm the rationale for skipping deployment-mode testing and verify the span behavior is consistent in deployed environments. Nice work!
How this was made
Lenzon read vercel/next.js at pull request #97439 and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it