how_to_collect details

// Input
{ "scenario": "next-server" } // or "script"; defaults to "next-server"

// Output
{
  "scenario": "next-server",
  "summary": "Profile a production Next.js server while it handles a single request. ...",
  "command": "node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start",
  "steps": [ "...", "load_profile({ filePath: \"./.perf-profiles/<file>.cpuprofile\" })" ],
  "outputDir": "./.perf-profiles",
  "nextStep": "After stopping the server, call load_profile with the .cpuprofile ..."
}

next-server profiles a production Next.js server while it serves a single request. If next start says standalone output is unsupported, use the script scenario with .next/standalone/server.js. script profiles that standalone server (or another Node entry). Keep the scenario to one route and one hit. Node writes one .cpuprofile per process/worker thread into the output directory. The Next server command uses Node CLI flags (not NODE_OPTIONS) so it is the same on Unix and Windows.

read_source_context details

// Input
{ "profileId": "<id>", "functionName": "myFn", "contextLines": 10 }

// Output (per line)
{
  "lineNumber": 42,
  "content": "  for (let i = 0; i < items.length; i++) {",
  "ticks": 18,      // V8 samples that landed on this line
  "isHot": true     // true when ticks >= 50% of peak ticks for this function
}

The returned window is sized to cover the function's actual hot lines, not just a fixed radius around its declaration — a function's real bottleneck is often well past its function line. contextLines (default 10) sets the minimum padding around both the declaration and the hot lines; if any ticks still fall outside the returned window, the top-level result includes hiddenTicks (a count) and a warning telling you to retry with a larger contextLines. explain_function also accepts contextLines when called with includeSource: true.

Only files inside the current working directory can be read. file:// URLs and absolute paths are both handled; http://, node: builtins, and paths outside the project root are rejected.

suggest_optimizations details

// Input
{ "profileId": "<id>", "limit": 5 }

// Output (per function)
{
  "function": "processData",
  "file": "file:///app/src/processor.js",
  "line": 10,
  "selfPercent": "18.2%",
  "patterns": [
    {
      "pattern": "high-fan-in",
      "detail": "Called from 6 distinct call sites (e.g. renderRow, buildTree, …)",
      "suggestion": "This function is a shared hot path. Ensure it is well-optimised and monomorphic …"
    },
    {
      "pattern": "hot-caller",
      "detail": "84% of calls come from \"renderRow\"",
      "suggestion": "Focus optimisation effort on \"renderRow\" rather than this function …"
    }
  ],
  "topSuggestion": "This function is a shared hot path …"
}

Patterns detected (multiple can fire for the same function):

Functions that appear at multiple call sites are automatically merged before ranking so the same logical function is only reported once.

get_package_costs details

// Input
{ "profileId": "<id>", "limit": 10 }

// Output (per package)
{
  "rank": 1,
  "package": "lodash",
  "selfTime": "42.3ms",
  "selfPercent": "14.1%",
  "totalTimeIncludingCallbacks": "58.0ms",
  "totalPercentIncludingCallbacks": "19.3%",
  "topFunctions": [
    { "function": "chunk", "file": "lodash/chunk.js", "line": 41, "selfTime": "28.0ms", "selfPercent": "9.3%" }
  ]
}

selfTime is the time spent inside the package's own code. totalTimeIncludingCallbacks also counts everything the package called into — including your own callbacks handed back to it — so it can exceed what removing the package would actually save.

Scoped packages (@babel/core, @next/env, etc.) are handled correctly. User code and native builtins (no node_modules in the path) are excluded.

Generating a CPU Profile

Ask Copilot to call how_to_collect for a ready-to-run recipe, or generate one manually:

Next.js production server (profile a single request):

node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start
# hit the route once, then stop the process so it can exit and write the profile

If next start reports that standalone output is unsupported:

node --cpu-prof --cpu-prof-dir=./.perf-profiles .next/standalone/server.js

Chrome DevTools:

1. Open DevTools and go to the Performance tab.
2. Record the scenario you want to inspect.
3. Stop recording and save the result as a .cpuprofile export.