Unverified Commit 4a4590a3 authored by Jimmy Lai's avatar Jimmy Lai Committed by GitHub

request insights: add agent diagnosis access (4/5) (#93977)

## What

Adds `next experimental-diagnose` and an MCP `get_request_insights` tool
so agents and local users can inspect Request Insights without opening
the DevTools overlay.

Stack:

1. request insights: record local framework spans (1/5)
2. request insights: derive request history and fetch data (2/5)
3. request insights: expose dev snapshots to tools and HMR (3/5)
4. request insights: add agent diagnosis access (4/5) ← current
5. request insights: add DevTools request panel (5/5)

## Review Focus

- CLI error handling and raw JSON output.
- MCP gating when Request Insights is unavailable.
- Telemetry registration for the new MCP tool name.

## Proof In This PR

- `pnpm jest packages/next/src/telemetry/events/mcp-telemetry.test.ts
--runInBand`
- `pnpm --filter=next types`
- Stack-tip smoke verifies `next experimental-diagnose --url
http://localhost:3003 --json` against a real dev server.

## Deferred Coverage

- A more curated agent summary format is intentionally deferred until
the raw private snapshot contract settles.

<!-- NEXT_JS_LLM_PR -->

---------
Co-authored-by: 's avatarTim Neutkens <tim@timneutkens.nl>
parent 93249ee0
......@@ -33,6 +33,7 @@ import type { NextBuildOptions } from '../cli/next-build.js'
import type { NextTypegenOptions } from '../cli/next-typegen.js'
import type { NextPostBuildOptions } from '../cli/next-post-build.js'
import { ensureProfilesDir } from '../lib/profiles-dir'
import type { NextRequestInsightsOptions } from '../cli/next-request-insights.js'
/**
* Create `.next-profiles` (with its `.gitignore`) when profiling/tracing is
......@@ -608,6 +609,35 @@ program
)
.usage('[directory] [options]')
program
.command('experimental-request-insights')
.description(
'Inspect experimental Request Insights from a running Next.js dev server.'
)
.argument(
'[directory]',
`A directory containing the Next.js application. ${italic(
'If no directory is provided, the current directory will be used.'
)}`
)
.option(
'--url <url>',
'Override automatic discovery with the complete HTTP(S) URL of the running Next.js dev server.'
)
.option('--json', 'Print raw request insight JSON.')
.addOption(
new Option(
'--limit <count>',
'Maximum number of recent request summaries to print.'
).argParser(parseValidPositiveInteger)
)
.action((directory: string, options: NextRequestInsightsOptions) => {
return import('../cli/next-request-insights.js').then((mod) =>
mod.nextRequestInsights(options, directory)
)
})
.usage('[directory] [options]')
const internal = program
.command('internal')
.description(
......
import path from 'path'
import { readLockfileContent, parseDevServerInfo } from '../build/lockfile'
import { getProjectDir } from '../lib/get-project-dir'
import type {
RequestInsight,
RequestInsightsSnapshot,
} from '../next-devtools/shared/request-insights'
import loadConfig from '../server/config'
import { printAndExit } from '../server/lib/utils'
import {
PHASE_DEVELOPMENT_SERVER,
REQUEST_INSIGHTS_DEV_ENDPOINT,
} from '../shared/lib/constants'
const DEFAULT_REQUEST_LIMIT = 20
const DEFAULT_FETCH_LIMIT = 5
const DEV_SERVER_DISCOVERY_TIMEOUT_MS = 1000
const DEV_SERVER_DISCOVERY_RETRY_MS = 50
export type NextRequestInsightsOptions = {
url?: string
json?: boolean
limit?: number
}
export async function nextRequestInsights(
options: NextRequestInsightsOptions,
directory?: string
) {
const devServerUrl = options.url
? parseDevServerUrl(options.url)
: await discoverDevServerUrl(directory)
const endpoint = new URL(REQUEST_INSIGHTS_DEV_ENDPOINT, devServerUrl)
const response = await fetch(endpoint).catch((error) => {
printAndExit(
`Failed to reach ${endpoint.toString()}: ${error instanceof Error ? error.message : String(error)}`,
1
)
throw error
})
const text = await response.text()
let data: unknown
try {
data = JSON.parse(text)
} catch {
printAndExit(`Invalid response from ${endpoint.toString()}: ${text}`, 1)
}
if (!response.ok) {
printAndExit(getResponseError(data, response.status), 1)
}
if (!isRequestInsightsSnapshot(data)) {
exitWithError(
`Invalid response from ${endpoint.toString()}: expected requests and fetches to be arrays.`
)
}
if (options.json) {
console.log(JSON.stringify(data, null, 2))
return
}
const requests = data.requests
if (requests.length === 0) {
console.log('No request insights captured yet.')
return
}
const limit = options.limit ?? DEFAULT_REQUEST_LIMIT
const visibleRequests = requests.slice(-limit).reverse()
console.log(
`Showing ${visibleRequests.length} of ${requests.length} retained requests (newest first).`
)
for (const request of visibleRequests) {
const route = request.route ?? request.url ?? request.requestId
const duration = formatDuration(request.durationMs)
console.log(`${route} ${duration} ${request.status ?? 'pending'}`)
console.log(
` request ${shortId(request.requestId)} page ${shortId(request.htmlRequestId)}`
)
const visibleFetches = request.fetches.slice(0, DEFAULT_FETCH_LIMIT)
if (visibleFetches.length < request.fetches.length) {
console.log(
` showing first ${visibleFetches.length} of ${request.fetches.length} fetches`
)
}
for (const fetch of visibleFetches) {
console.log(
` fetch ${formatDuration(fetch.durationMs)} ${fetch.statusCode ?? '-'} ${fetch.cacheStatus ?? 'unknown'} ${fetch.method ?? 'GET'} ${fetch.url ?? ''}`
)
}
}
}
async function discoverDevServerUrl(directory?: string): Promise<URL> {
const projectDir = getProjectDir(directory)
const config = await loadConfig(PHASE_DEVELOPMENT_SERVER, projectDir)
const lockfilePath = path.join(projectDir, config.distDir, 'lock')
const deadline = Date.now() + DEV_SERVER_DISCOVERY_TIMEOUT_MS
while (Date.now() < deadline) {
const lockfileContent = readLockfileContent(lockfilePath)
const serverInfo = lockfileContent
? parseDevServerInfo(lockfileContent)
: undefined
if (serverInfo && typeof serverInfo.appUrl === 'string') {
return parseDevServerUrl(serverInfo.appUrl)
}
await new Promise((resolve) =>
setTimeout(resolve, DEV_SERVER_DISCOVERY_RETRY_MS)
)
}
return exitWithError(
`Unable to discover a running Next.js dev server from ${lockfilePath}. Start next dev or pass --url.`
)
}
function exitWithError(message: string): never {
return printAndExit(message, 1) as never
}
function getResponseError(data: unknown, status: number): string {
if (
typeof data === 'object' &&
data !== null &&
'error' in data &&
typeof data.error === 'string'
) {
return data.error
}
return `Request failed with ${status}`
}
function isRequestInsightsSnapshot(
data: unknown
): data is RequestInsightsSnapshot {
return (
typeof data === 'object' &&
data !== null &&
'requests' in data &&
Array.isArray(data.requests) &&
data.requests.every(isRequestInsight)
)
}
function isRequestInsight(request: unknown): request is RequestInsight {
return (
typeof request === 'object' &&
request !== null &&
'fetches' in request &&
Array.isArray(request.fetches)
)
}
function parseDevServerUrl(value: string): URL {
let url: URL
try {
url = new URL(value)
} catch {
return exitWithError(
`Invalid dev server URL "${value}". Pass a valid HTTP or HTTPS URL.`
)
}
if (url.protocol !== 'http:' && url.protocol !== 'https:') {
return exitWithError(
`Invalid dev server URL "${value}". Pass a valid HTTP or HTTPS URL.`
)
}
return url
}
function formatDuration(durationMs: number | undefined): string {
if (typeof durationMs !== 'number') {
return '-'
}
return durationMs < 1000
? `${Math.round(durationMs)}ms`
: `${(durationMs / 1000).toFixed(2)}s`
}
function shortId(id: string | undefined): string {
if (!id) {
return '-'
}
return id.length > 8 ? id.slice(0, 8) : id
}
......@@ -31,6 +31,7 @@ import { parseUrl as parseUrlUtil } from '../../shared/lib/router/utils/parse-ur
import {
PHASE_PRODUCTION_SERVER,
PHASE_DEVELOPMENT_SERVER,
REQUEST_INSIGHTS_DEV_ENDPOINT,
UNDERSCORE_NOT_FOUND_ROUTE,
} from '../../shared/lib/constants'
import { RedirectStatusCode } from '../../client/components/redirect-status-code'
......@@ -251,7 +252,7 @@ export async function initialize(opts: {
const urlParts = req.url.split('?', 1)
const pathname = removePathPrefix(urlParts[0] || '', config.basePath)
if (pathname === '/__nextjs_request_insights') {
if (pathname === REQUEST_INSIGHTS_DEV_ENDPOINT) {
if (
development &&
blockCrossSiteDEV(
......
......@@ -201,11 +201,12 @@ async function startWatcher(
// Create server info to store in the lockfile itself
// This allows other processes to discover the running server
const appUrl = `http://localhost:${opts.port}`
const appUrl =
process.env.__NEXT_PRIVATE_ORIGIN ?? `http://localhost:${opts.port}`
const serverInfo: DevServerInfo = {
pid: process.pid,
port: opts.port,
hostname: 'localhost',
hostname: new URL(appUrl).hostname,
appUrl,
startedAt: Date.now(),
}
......
......@@ -7,6 +7,7 @@ import { registerGetActionByIdTool } from './tools/get-server-action-by-id'
import { registerGetRoutesTool } from './tools/get-routes'
import { registerGetCompilationIssuesTool } from './tools/get-compilation-issues'
import { registerCompileRouteTool } from './tools/compile-route'
import { registerGetRequestInsightsTool } from './tools/get-request-insights'
import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
import type { NextConfigComplete } from '../config-shared'
import type { Project } from '../../build/swc/types'
......@@ -63,6 +64,7 @@ export const getOrCreateMcpServer = (options: McpServerOptions) => {
pagesDir: options.pagesDir,
appDir: options.appDir,
})
registerGetRequestInsightsTool(mcpServer)
if (options.getTurbopackProject) {
registerGetCompilationIssuesTool(mcpServer, options.getTurbopackProject)
......
import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
import z from 'next/dist/compiled/zod'
import {
getRequestInsightsSnapshot,
isRequestInsightsEnabled,
} from '../../lib/trace/request-insights'
import { mcpTelemetryTracker } from '../mcp-telemetry-tracker'
export function registerGetRequestInsightsTool(server: McpServer) {
server.registerTool(
'get_request_insights',
{
description:
'Get recent App Router request insights captured by the local Next.js span recorder. Useful for debugging slow renders, server fetches, cache behavior, and request timelines without an external OTEL collector. Requires experimental.requestInsights.',
inputSchema: {
requestId: z.string().optional(),
htmlRequestId: z.string().optional(),
},
},
async (request) => {
mcpTelemetryTracker.recordToolCall('mcp/get_request_insights')
if (!isRequestInsightsEnabled()) {
return {
content: [
{
type: 'text',
text: JSON.stringify({
error:
'Request Insights is not enabled. Set experimental.requestInsights = true in next.config.js and restart next dev.',
}),
},
],
}
}
const snapshot = getRequestInsightsSnapshot()
const requests = snapshot.requests.filter((insight) => {
return (
(request.requestId === undefined ||
insight.requestId === request.requestId) &&
(request.htmlRequestId === undefined ||
insight.htmlRequestId === request.htmlRequestId)
)
})
return {
content: [
{
type: 'text',
text: JSON.stringify({ requests }, null, 2),
},
],
}
}
)
}
......@@ -99,6 +99,8 @@ export const ROUTES_MANIFEST = 'routes-manifest.json'
export const IMAGES_MANIFEST = 'images-manifest.json'
export const SERVER_FILES_MANIFEST = 'required-server-files'
export const DEV_CLIENT_PAGES_MANIFEST = '_devPagesManifest.json'
export const REQUEST_INSIGHTS_DEV_ENDPOINT =
'/_next/development/request-insights'
export const MIDDLEWARE_MANIFEST = 'middleware-manifest.json'
export const TURBOPACK_CLIENT_MIDDLEWARE_MANIFEST =
'_clientMiddlewareManifest.js'
......
......@@ -279,6 +279,7 @@ export type McpToolName =
| 'mcp/get_page_metadata'
| 'mcp/get_project_metadata'
| 'mcp/get_routes'
| 'mcp/get_request_insights'
| 'mcp/get_server_action_by_id'
| 'mcp/get_compilation_issues'
| 'mcp/compile_route'
......
......@@ -77,7 +77,11 @@ describe('MCP Telemetry Events', () => {
'mcp/get_logs',
'mcp/get_page_metadata',
'mcp/get_project_metadata',
'mcp/get_routes',
'mcp/get_request_insights',
'mcp/get_server_action_by_id',
'mcp/get_compilation_issues',
'mcp/compile_route',
]
const usages = allTools.map((tool, index) => ({
......@@ -87,7 +91,7 @@ describe('MCP Telemetry Events', () => {
const events = eventMcpToolUsage(usages)
expect(events).toHaveLength(5)
expect(events).toHaveLength(9)
events.forEach((event, index) => {
expect(event.eventName).toBe(EVENT_MCP_TOOL_USAGE)
......
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <p>hello world</p>
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
distDir: 'build',
experimental: {
requestInsights: true,
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { createServer } from 'http'
import type { AddressInfo } from 'net'
type RequestInsight = {
requestId: string
htmlRequestId: string
route: string
startTime: number
status: 'ok'
spans: []
fetches: Array<{
durationMs: number
statusCode: number
cacheStatus: string
method: string
url: string
}>
}
describe('request insights', () => {
const { next } = nextTestSetup({
files: __dirname,
})
function createRequest(index: number, fetchCount = 0): RequestInsight {
return {
requestId: `request-${index}`,
htmlRequestId: `page-${index}`,
route: `/route-${index}`,
startTime: index,
status: 'ok',
spans: [],
fetches: Array.from({ length: fetchCount }, (_, fetchIndex) => ({
durationMs: fetchIndex + 1,
statusCode: 200,
cacheStatus: 'miss',
method: 'GET',
url: `https://example.com/fetch-${fetchIndex}`,
})),
}
}
async function runWithResponse(body: unknown, args: string[] = []) {
const requestedPaths: string[] = []
const server = createServer((req, res) => {
requestedPaths.push(req.url ?? '')
res.setHeader('Content-Type', 'application/json')
res.end(JSON.stringify(body))
})
await new Promise<void>((resolve) => {
server.listen(0, '127.0.0.1', resolve)
})
try {
const address = server.address() as AddressInfo
const result = await next.runCommand([
'experimental-request-insights',
'--url',
`http://127.0.0.1:${address.port}`,
...args,
])
return { result, requestedPaths }
} finally {
await new Promise<void>((resolve, reject) => {
server.close((error) => (error ? reject(error) : resolve()))
})
}
}
it('discovers the running dev server from the project lockfile', async () => {
const result = await next.runCommand(['experimental-request-insights'])
if (result.code !== 0) {
throw new Error(result.cliOutput)
}
expect(result.cliOutput).toMatch(
/No request insights captured yet|retained requests \(newest first\)/
)
})
it('uses the development endpoint and reports truncated output', async () => {
const { result, requestedPaths } = await runWithResponse(
{
requests: [createRequest(1), createRequest(2), createRequest(3, 7)],
},
['--limit', '1']
)
expect(result.code).toBe(0)
expect(requestedPaths).toEqual(['/_next/development/request-insights'])
expect(result.stdout).toContain(
'Showing 1 of 3 retained requests (newest first).'
)
expect(result.stdout).toContain('/route-3')
expect(result.stdout).not.toContain('/route-2')
expect(result.stdout).toContain('showing first 5 of 7 fetches')
expect(result.stdout).toContain('https://example.com/fetch-4')
expect(result.stdout).not.toContain('https://example.com/fetch-5')
})
it.each(['localhost:3000', 'https://[', 'ftp://localhost:3000'])(
'rejects invalid dev server URL %s',
async (url) => {
const result = await next.runCommand([
'experimental-request-insights',
'--url',
url,
])
expect(result.code).toBe(1)
expect(result.stderr).toContain(
`Invalid dev server URL "${url}". Pass a valid HTTP or HTTPS URL.`
)
}
)
it.each([
{ body: { requests: null }, args: ['--json'] },
{ body: { requests: [{ fetches: null }] }, args: [] },
])('rejects malformed responses', async ({ body, args }) => {
const { result } = await runWithResponse(body, args)
expect(result.code).toBe(1)
expect(result.stderr).toContain(
'expected requests and fetches to be arrays'
)
})
})
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