Unverified Commit 2966db44 authored by David Alexandru Ilie's avatar David Alexandru Ilie Committed by GitHub

Trace development route preparation (#96453)

## Summary

This PR introduces the first bounded route-preparation phases used by
Request Insights. It instruments existing matcher and bundler boundaries
without changing their behavior or making the spans default-public
OpenTelemetry data.

- trace development route matching and route preparation while a route
is ensured
- keep production matcher reload as a separate sibling phase so reload
work is not charged to matching
- surface the internal phases as `match route`, `prepare route`, and
`reload route matchers` in Request Insights
- cover cold and warm page, App Route/API, and dynamic-route behavior in
both development bundlers
- preserve the existing matcher results, errors, and public OTel
allowlist

## Verification

- `pnpm test-dev-turbo
test/development/app-dir/request-insights-route-preparation/request-insights-route-preparation.test.ts`
- `pnpm test-dev-webpack
test/development/app-dir/request-insights-route-preparation/request-insights-route-preparation.test.ts`
- `pnpm --filter=next types`
parent 5f23fb6a
...@@ -272,7 +272,7 @@ describe('request insights trace viewer', () => { ...@@ -272,7 +272,7 @@ describe('request insights trace viewer', () => {
attributes: { 'next.span_type': 'NextNodeServer.matchRoute' }, attributes: { 'next.span_type': 'NextNodeServer.matchRoute' },
}, },
{ {
name: 'compile and prepare route', name: 'prepare route',
spanId: 'ensure', spanId: 'ensure',
parentSpanId: 'match', parentSpanId: 'match',
startTime: 107, startTime: 107,
...@@ -291,6 +291,16 @@ describe('request insights trace viewer', () => { ...@@ -291,6 +291,16 @@ describe('request insights trace viewer', () => {
'next.span_type': 'DevBundlerService.ensurePage', 'next.span_type': 'DevBundlerService.ensurePage',
}, },
}, },
{
name: 'reload route matchers',
spanId: 'reload-matchers',
parentSpanId: 'match',
startTime: 109,
durationMs: 1,
attributes: {
'next.span_type': 'DevRouteMatcherManager.reloadMatchers',
},
},
{ {
name: 'render', name: 'render',
spanId: 'base-render', spanId: 'base-render',
...@@ -392,7 +402,8 @@ describe('request insights trace viewer', () => { ...@@ -392,7 +402,8 @@ describe('request insights trace viewer', () => {
).toEqual([ ).toEqual([
{ label: 'GET', depth: 0 }, { label: 'GET', depth: 0 },
{ label: 'match route', depth: 1 }, { label: 'match route', depth: 1 },
{ label: 'compile and prepare route', depth: 2 }, { label: 'prepare route', depth: 2 },
{ label: 'reload route matchers', depth: 2 },
{ label: 'render', depth: 2 }, { label: 'render', depth: 2 },
{ label: 'load components', depth: 3 }, { label: 'load components', depth: 3 },
{ label: 'prepare app page response', depth: 3 }, { label: 'prepare app page response', depth: 3 },
...@@ -407,8 +418,9 @@ describe('request insights trace viewer', () => { ...@@ -407,8 +418,9 @@ describe('request insights trace viewer', () => {
'GET', 'GET',
'prepare request', 'prepare request',
'match route', 'match route',
'compile and prepare route', 'prepare route',
'compile route', 'compile route',
'reload route matchers',
'render', 'render',
'resolve page components', 'resolve page components',
'load components', 'load components',
......
...@@ -31,6 +31,7 @@ const DEFAULT_VISIBLE_SPAN_TYPES = new Set([ ...@@ -31,6 +31,7 @@ const DEFAULT_VISIBLE_SPAN_TYPES = new Set([
'Middleware.execute', 'Middleware.execute',
'NextNodeServer.matchRoute', 'NextNodeServer.matchRoute',
'DevRouteMatcherManager.ensureRoute', 'DevRouteMatcherManager.ensureRoute',
'DevRouteMatcherManager.reloadMatchers',
'BaseServer.render', 'BaseServer.render',
'LoadComponents.loadComponents', 'LoadComponents.loadComponents',
'AppRender.prepareAppPageResponse', 'AppRender.prepareAppPageResponse',
......
...@@ -94,6 +94,11 @@ enum AppRenderSpan { ...@@ -94,6 +94,11 @@ enum AppRenderSpan {
instantInsightsRunValidation = 'AppRender.instantInsights.runValidation', instantInsightsRunValidation = 'AppRender.instantInsights.runValidation',
} }
enum DevRouteMatcherManagerSpan {
ensureRoute = 'DevRouteMatcherManager.ensureRoute',
reloadMatchers = 'DevRouteMatcherManager.reloadMatchers',
}
enum RouterSpan { enum RouterSpan {
executeRoute = 'Router.executeRoute', executeRoute = 'Router.executeRoute',
} }
...@@ -124,6 +129,7 @@ type SpanTypes = ...@@ -124,6 +129,7 @@ type SpanTypes =
| `${RenderSpan}` | `${RenderSpan}`
| `${RouterSpan}` | `${RouterSpan}`
| `${AppRenderSpan}` | `${AppRenderSpan}`
| `${DevRouteMatcherManagerSpan}`
| `${NodeSpan}` | `${NodeSpan}`
| `${AppRouteRouteHandlersSpan}` | `${AppRouteRouteHandlersSpan}`
| `${ResolveMetadataSpan}` | `${ResolveMetadataSpan}`
...@@ -166,6 +172,7 @@ export { ...@@ -166,6 +172,7 @@ export {
RenderSpan, RenderSpan,
RouterSpan, RouterSpan,
AppRenderSpan, AppRenderSpan,
DevRouteMatcherManagerSpan,
NodeSpan, NodeSpan,
AppRouteRouteHandlersSpan, AppRouteRouteHandlersSpan,
ResolveMetadataSpan, ResolveMetadataSpan,
......
...@@ -7,6 +7,8 @@ import path from '../../shared/lib/isomorphic/path' ...@@ -7,6 +7,8 @@ import path from '../../shared/lib/isomorphic/path'
import * as Log from '../../build/output/log' import * as Log from '../../build/output/log'
import { cyan } from '../../lib/picocolors' import { cyan } from '../../lib/picocolors'
import type { RouteMatcher } from '../route-matchers/route-matcher' import type { RouteMatcher } from '../route-matchers/route-matcher'
import { DevRouteMatcherManagerSpan } from '../lib/trace/constants'
import { getTracer } from '../lib/trace/tracer'
export interface RouteEnsurer { export interface RouteEnsurer {
ensure(match: RouteMatch, pathname: string): Promise<void> ensure(match: RouteMatch, pathname: string): Promise<void>
...@@ -70,8 +72,20 @@ export class DevRouteMatcherManager extends DefaultRouteMatcherManager { ...@@ -70,8 +72,20 @@ export class DevRouteMatcherManager extends DefaultRouteMatcherManager {
for await (const developmentMatch of super.matchAll(pathname, options)) { for await (const developmentMatch of super.matchAll(pathname, options)) {
// We're here, which means that we haven't seen this match yet, so we // We're here, which means that we haven't seen this match yet, so we
// should try to ensure it and recompile the production matcher. // should try to ensure it and recompile the production matcher.
await this.ensurer.ensure(developmentMatch, pathname) await getTracer().trace(
await this.production.reload() DevRouteMatcherManagerSpan.ensureRoute,
{
spanName: 'prepare route',
},
() => this.ensurer.ensure(developmentMatch, pathname)
)
await getTracer().trace(
DevRouteMatcherManagerSpan.reloadMatchers,
{
spanName: 'reload route matchers',
},
() => this.production.reload()
)
// Iterate over the production matches again, this time we should be able // Iterate over the production matches again, this time we should be able
// to match it against the production matcher unless there's an error. // to match it against the production matcher unless there's an error.
......
export function GET() {
return Response.json({ route: 'prepared' })
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <p>route preparation page</p>
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
experimental: {
requestInsights: true,
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils'
describe('request-insights-route-preparation', () => {
const { next } = nextTestSetup({
files: __dirname,
})
type RequestInsightSpan = {
name: string
durationMs?: number
status?: 'ok' | 'error'
traceId?: string
spanId?: string
parentSpanId?: string
attributes?: Record<string, string | number | boolean>
}
type RequestInsight = {
requestId: string
route?: string
status: 'ok' | 'error' | 'pending'
spans: RequestInsightSpan[]
}
const routePreparationSpanType = 'DevRouteMatcherManager.ensureRoute'
const matcherReloadSpanType = 'DevRouteMatcherManager.reloadMatchers'
async function getRequestInsights() {
return (await next
.fetch('/_next/development/request-insights')
.then((response) => response.json())) as {
requests: RequestInsight[]
}
}
async function captureRequest(
route: string,
request: () => Promise<unknown>
) {
const existingRequestIds = new Set(
(await getRequestInsights()).requests
.filter((insight) => insight.route === route)
.map((insight) => insight.requestId)
)
await request()
let capturedRequest: RequestInsight | undefined
await retry(async () => {
capturedRequest = (await getRequestInsights()).requests.find(
(insight) =>
insight.route === route &&
insight.status === 'ok' &&
!existingRequestIds.has(insight.requestId) &&
insight.spans.some(
(span) =>
span.attributes?.['next.span_type'] ===
'BaseServer.handleRequest' &&
span.status === 'ok' &&
typeof span.durationMs === 'number'
) &&
insight.spans.some(
(span) =>
span.attributes?.['next.span_type'] === routePreparationSpanType
) &&
insight.spans.some(
(span) =>
span.attributes?.['next.span_type'] === matcherReloadSpanType
)
)
expect(capturedRequest).toBeDefined()
}, 10_000)
return capturedRequest!
}
function expectRoutePreparationSpans(request: RequestInsight) {
const spanById = new Map(
request.spans.flatMap((span) =>
span.spanId ? [[span.spanId, span] as const] : []
)
)
const rootSpan = request.spans.find(
(span) =>
span.attributes?.['next.span_type'] === 'BaseServer.handleRequest'
)
const routePreparationSpans = request.spans.filter(
(span) => span.attributes?.['next.span_type'] === routePreparationSpanType
)
const matcherReloadSpans = request.spans.filter(
(span) => span.attributes?.['next.span_type'] === matcherReloadSpanType
)
expect(rootSpan?.spanId).toBeDefined()
expect(rootSpan?.traceId).toBeDefined()
expect(routePreparationSpans).toHaveLength(1)
expect(matcherReloadSpans).toHaveLength(1)
expect(routePreparationSpans[0].spanId).toBeDefined()
expect(matcherReloadSpans[0].spanId).toBeDefined()
expect(matcherReloadSpans[0].spanId).not.toBe(
routePreparationSpans[0].spanId
)
expect(matcherReloadSpans[0].parentSpanId).toBe(
routePreparationSpans[0].parentSpanId
)
for (const [span, name, type] of [
[routePreparationSpans[0], 'prepare route', routePreparationSpanType],
[matcherReloadSpans[0], 'reload route matchers', matcherReloadSpanType],
] as const) {
expect(span).toEqual(
expect.objectContaining({
name,
durationMs: expect.any(Number),
status: 'ok',
attributes: {
'next.span_category': 'nextjs',
'next.span_name': name,
'next.span_type': type,
},
})
)
expect(Number.isFinite(span.durationMs)).toBe(true)
expect(span.durationMs).toBeGreaterThanOrEqual(0)
expect(span.traceId).toBe(rootSpan?.traceId)
let ancestor = span.parentSpanId
? spanById.get(span.parentSpanId)
: undefined
const visited = new Set<string>()
while (
ancestor?.spanId !== rootSpan?.spanId &&
ancestor?.parentSpanId &&
!visited.has(ancestor.parentSpanId)
) {
visited.add(ancestor.parentSpanId)
ancestor = spanById.get(ancestor.parentSpanId)
}
expect(ancestor?.spanId).toBe(rootSpan?.spanId)
}
}
it('records route preparation for first and subsequent App Page requests', async () => {
const coldRequest = await captureRequest('/', async () => {
const response = await next.fetch('/')
expect(response.status).toBe(200)
expect(await response.text()).toContain('route preparation page')
})
const warmRequest = await captureRequest('/', async () => {
const response = await next.fetch('/')
expect(response.status).toBe(200)
await response.text()
})
expectRoutePreparationSpans(coldRequest)
expectRoutePreparationSpans(warmRequest)
})
it('records route preparation for first and subsequent App Route requests', async () => {
const route = '/api/route-preparation'
const coldRequest = await captureRequest(route, async () => {
const response = await next.fetch(route)
expect(response.status).toBe(200)
expect(await response.json()).toEqual({ route: 'prepared' })
})
const warmRequest = await captureRequest(route, async () => {
const response = await next.fetch(route)
expect(response.status).toBe(200)
await response.text()
})
expectRoutePreparationSpans(coldRequest)
expectRoutePreparationSpans(warmRequest)
})
})
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