ZH

The IDE's profiler

Français

Where does a program spend its CPU time and its memory? The IDE's Profiler runs a run configuration (a game, a graphic / CLI / desktop app, the project's tests, a screenshot) under Xdebug 3's profiler and shows the answer: pictures first, numbers when you ask.

Use it

  • Run > Profile… (Alt+Shift+P), the Profiler window on the right stripe (Alt+P), or Profile… at the end of the run configurations list.
  • Choose what (CPU time, memory, or both), which program (the selected run configuration), and until when: the program quits, N seconds, or N frames (a game: 60 frames = 1 second; JUMPHP_MAX_FRAMES). A headless run (shot, test) with N frames is the quickest way to profile a game; a windowed run waits until you close it.
  • The first profile builds the Docker image with Xdebug once (about a minute; the IDE says so). Everything runs in Docker through bin/jumphp, like Debug.

What you see

  1. A summary: CPU time, peak memory, memory allocated, calls, and where the own time goes (your code, the JumPHP engine, libraries, PHP itself).
  2. A flame graph: click a box to zoom, double click to open the code, search box, Icicle to flip it, Size: time / memory. Colours follow the namespace. A CPU-only run draws it from the call graph (Xdebug's profile keeps who calls whom, not each call in order); with the memory trace it is the real merged call tree.
  3. Memory over time (when the trace was on): drag over the chart to select a part of the run: the hot spots below follow the range.
  4. Hot spots: the 10 functions with the most own CPU time, the most memory allocated, the most calls. Click a row: the code opens at that line. With the profile loaded, the editors' gutter shows the cost of the lines (a faint red band; the toggle is in the toolbar).
  5. A frame of the game (JumPHP games): time per frame split engine / update / render, the 60 FPS budget, frames per second, the slowest frames, what your scenes spend in update and render.
  6. Details (toolbar): the call tree (expand, sort by calls, own, with calls, memory), callers and callees of the selected function, per-file and per-class totals, the raw numbers.
  7. Compare: the clock menu keeps the last 20 runs of each program (var/profiles/); pick two to see what got slower / faster, heavier / lighter (green is better, red is worse).
  8. Export: Export for speedscope writes var/profiles/<id>/profile.speedscope.json (open it at speedscope.app); Copy a summary for an AI puts a compact Markdown of the hot spots (with file:line) on the clipboard.

For Claude (MCP tools of the IDE)

profile_run {config, mode?, frames?, seconds?} profiles and returns the profile id and a Markdown summary; profile_summary {id?, top?, format?} reads it again; profile_compare {a, b} compares two runs. An AI can profile, read, optimise and profile again. They are asked for through the IDE's permission flow like any tool that runs a program.

How it works

  • bin/jumphp with JUMPHP_PROFILE=<folder under var/> (and JUMPHP_PROFILE_MODE=profile or profile,trace) runs the PHP in the Xdebug image with an ini file in that folder: xdebug.mode=profile[,trace], no debugger connection, trace_format=1 (computer-readable, with memory). JUMPHP_XDEBUG (the debugger) is a different thing and wins when both are set.
  • ide/src/Profile/ reads the files as a stream, in slices of the IDE's frame (it never blocks): CachegrindParser (own and inclusive time per function, calls, per-line cost, caller / callee edges, memory), TraceParser (merged call tree, memory over time, per-slice own time and memory for the range selection, per-call time of the game's frame function). Files are capped (400 MB of profile, 300 MB of trace; functions, edges, lines, tree nodes too): when something is cut the profile says so. The raw files are deleted once read; the result (profile.json, a few hundred KB) stays.
  • The memory trace slows the program down a lot (tens of times) and is bigger to read: CPU time alone has the least overhead. Times of a run with the trace include its cost, so compare runs measured the same way.
  • Several programs write one file each (tests start several): the CPU profile adds them all, the memory chart follows the longest trace.

Engines

The profiler is built on an interface (ProfilerEngine): an engine says what it can measure and how bin/jumphp starts the program. Xdebug is the only one that measures. PHP Debugger (php-debugger.dev) is a step debugger: in the project's image its extension reports a single feature, "Step Debugger", mode debug only (checked with php --ri php_debugger, version 0.4.1), so it cannot profile; it stays listed with that reason.

Tests

bin/jumphp php ide vendor/bin/phpunit (parsers, aggregation, MCP tools; fixtures made with ide/tests/fixtures/profile/workload.php under Xdebug), JUMPHP_E2E=1 ... ProfilerEndToEndTest (the real hello-world, 120 frames), node --test ide/ui/js/flame.test.mjs (layout, ranges), games/ide/tools/ui-profiler-check.sh (the real IDE: flame, hot spots, memory range, details, compare, gutter; screenshots).