Investigate the spans emitted with `NEXT_OTEL_VERBOSE`

[logaretm]

This got brought up in our weekly syncs, the Next.js OTEL guide page says:

Next.js traces more spans than are emitted by default. To see more spans, you must set NEXT_OTEL_VERBOSE=1.

Which is a bit of a wonky wording but worth checking out to see what are the extra spans that are emitted and if they can be of any use to the user.

We can probably turn it on by manually by setting process.env.NEXT_OTEL_VERBOSE to 1 in the instrumentation init script.

I ran a preliminary scan of the Next.js repository for the NEXT_OTEL_VERBOSE flag and made a list of possible new spans that should be emitted with the env flag turned on, you can find those below.

Span Lists

Spans Normally Emitted (in NextVanillaSpanAllowlist):

Always Included (15 spans):

• Middleware.execute
• BaseServer.handleRequest
• Render.getServerSideProps
• Render.getStaticProps
• AppRender.fetch
• AppRender.getBodyResult
• Render.renderDocument
• Node.runHandler
• AppRouteRouteHandlers.runHandler
• ResolveMetadata.generateMetadata
• ResolveMetadata.generateViewport
• NextNodeServer.createComponentTree
• NextNodeServer.findPageComponents
• NextNodeServer.getLayoutOrPageModule
• NextNodeServer.startResponse
• NextNodeServer.clientComponentLoading

Additional Spans Only with Verbose Mode (48 more spans):

BaseServerSpan (11 additional):

• BaseServer.run
• BaseServer.pipe
• BaseServer.getStaticHTML
• BaseServer.render
• BaseServer.renderToResponseWithComponents
• BaseServer.renderToResponse
• BaseServer.renderToHTML
• BaseServer.renderError
• BaseServer.renderErrorToResponse
• BaseServer.renderErrorToHTML
• BaseServer.render404

LoadComponentsSpan (2):

• LoadComponents.loadDefaultErrorComponents
• LoadComponents.loadComponents

NextServerSpan (5):

• NextServer.getRequestHandler
• NextServer.getRequestHandlerWithMetadata
• NextServer.getServer
• NextServer.getServerRequestHandler
• createServer. createServer

NextNodeServerSpan (19 additional):

• NextNodeServer.compression
• NextNodeServer.getBuildId
• NextNodeServer.generateStaticRoutes
• NextNodeServer.generateFsStaticRoutes
• NextNodeServer.generatePublicRoutes
• NextNodeServer.generateImageRoutes. route
• NextNodeServer.sendRenderResult
• NextNodeServer.proxyRequest
• NextNodeServer.runApi
• NextNodeServer.render
• NextNodeServer.renderHTML
• NextNodeServer.imageOptimizer
• NextNodeServer.getPagePath
• NextNodeServer.getRoutesManifest
• NextNodeServer.getFontManifest
• NextNodeServer.getServerComponentManifest
• NextNodeServer.getRequestHandler
• NextNodeServer.renderToHTML
• NextNodeServer.renderError
• NextNodeServer.renderErrorToHTML
• NextNodeServer.render404
• route
• onProxyReq
• apiResolver
• internalFetch

StartServerSpan (1):

• startServer.startServer

RenderSpan (2 additional):

• Render.renderToString
• Render.createBodyResult

AppRenderSpan (2 additional):

• AppRender.renderToString
• AppRender.renderToReadableStream

RouterSpan (1):

• Router.executeRoute

[linear]

JS-1318

[logaretm]

Ran a few tests and got some results.

On server start

We didn't have any spans created then before, but with NEXT_OTEL_VERBOSE on, it emits LoadComponents.loadComponentsspans excessively, seems to grow with the app size when the server starts, doesn't seem useful to users IMO.

I suppose if we turn it on then we should drop these spans specifically.

API Routes

Scenario: Simple API route with a fetch call to an external service.

Current Behavior

trace

5 Spans, basically what we expect today.

With Verbose

trace

We get 12 Spans, nested under a NextServer.getRequestHandler span that we filter out with the low quality filter, for testing purposes I removed the low quality rule for this one since it wraps the whole transaction now and it would drop the whole thing if we didn't.

Note that I ran the same test for the current behavior with the same low quality rule exception, so the extra spans are not a result of the low quality filter.

New spans observed: LoadComponents.loadComponents, BaseServer.render, BaseServer.pipe, rendering page, BaseServer.renderToResponseWithComponents, NextServer.getRequestHandler and NextServer.getServerRequestHandler

Server Page

Scenario: A server page component with several server components loading in, all dynamic, no cache.

Current Behavior

trace

Around 44 spans on average

With Verbose

trace

Around 50 spans on average, similar extra spans to the API routes

Middleware

Scenario: Simple middleware that logs requests, matched against the root page.

Current Behavior

trace

2 spans

With Verbose

trace

4 spans with NextServer.getServerRequestHandler and http.server extra span

---

There are still several spans in the list, I will try to see how we can trigger them and if they hold any value.