Perfonext Profiler

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_OPTIONS='--cpu-prof --cpu-prof-dir=./.perf-profiles' 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; script profiles a standalone Node.js script. Node writes one .cpuprofile per process/worker thread into the output directory. The command uses bash/zsh env-var syntax (NODE_OPTIONS='...' next start); on Windows PowerShell, set $env:NODE_OPTIONS first.

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%",
  "totalTime": "58.0ms",
  "totalPercent": "19.3%",
  "topFunctions": [
    { "function": "chunk", "selfTime": "28.0ms", "selfPercent": "9.3%" }
  ]
}

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_OPTIONS='--cpu-prof --cpu-prof-dir=./.perf-profiles' next start
# hit the route once, then Ctrl-C to flush the profile

Standalone Node.js script:

node --cpu-prof --cpu-prof-dir=./.perf-profiles your-script.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.