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', () => {
attributes: { 'next.span_type': 'NextNodeServer.matchRoute' },
},
{
name: 'compile and prepare route',
name: 'prepare route',
spanId: 'ensure',
parentSpanId: 'match',
startTime: 107,
......@@ -291,6 +291,16 @@ describe('request insights trace viewer', () => {
'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',
spanId: 'base-render',
......@@ -392,7 +402,8 @@ describe('request insights trace viewer', () => {
).toEqual([
{ label: 'GET', depth: 0 },
{ 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: 'load components', depth: 3 },
{ label: 'prepare app page response', depth: 3 },
......@@ -407,8 +418,9 @@ describe('request insights trace viewer', () => {
'GET',
'prepare request',
'match route',
'compile and prepare route',
'prepare route',
'compile route',
'reload route matchers',
'render',
'resolve page components',
'load components',
......
......@@ -31,6 +31,7 @@ const DEFAULT_VISIBLE_SPAN_TYPES = new Set([
'Middleware.execute',
'NextNodeServer.matchRoute',
'DevRouteMatcherManager.ensureRoute',
'DevRouteMatcherManager.reloadMatchers',
'BaseServer.render',
'LoadComponents.loadComponents',
'AppRender.prepareAppPageResponse',
......
......@@ -94,6 +94,11 @@ enum AppRenderSpan {
instantInsightsRunValidation = 'AppRender.instantInsights.runValidation',
}
enum DevRouteMatcherManagerSpan {
ensureRoute = 'DevRouteMatcherManager.ensureRoute',
reloadMatchers = 'DevRouteMatcherManager.reloadMatchers',
}
enum RouterSpan {
executeRoute = 'Router.executeRoute',
}
......@@ -124,6 +129,7 @@ type SpanTypes =
| `${RenderSpan}`
| `${RouterSpan}`
| `${AppRenderSpan}`
| `${DevRouteMatcherManagerSpan}`
| `${NodeSpan}`
| `${AppRouteRouteHandlersSpan}`
| `${ResolveMetadataSpan}`
......@@ -166,6 +172,7 @@ export {
RenderSpan,
RouterSpan,
AppRenderSpan,
DevRouteMatcherManagerSpan,
NodeSpan,
AppRouteRouteHandlersSpan,
ResolveMetadataSpan,
......
......@@ -7,6 +7,8 @@ import path from '../../shared/lib/isomorphic/path'
import * as Log from '../../build/output/log'
import { cyan } from '../../lib/picocolors'
import type { RouteMatcher } from '../route-matchers/route-matcher'
import { DevRouteMatcherManagerSpan } from '../lib/trace/constants'
import { getTracer } from '../lib/trace/tracer'
export interface RouteEnsurer {
ensure(match: RouteMatch, pathname: string): Promise<void>
......@@ -70,8 +72,20 @@ export class DevRouteMatcherManager extends DefaultRouteMatcherManager {
for await (const developmentMatch of super.matchAll(pathname, options)) {
// 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.
await this.ensurer.ensure(developmentMatch, pathname)
await this.production.reload()
await getTracer().trace(
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
// 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