The IDE's profiler
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 windowedrunwaits 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
- A summary: CPU time, peak memory, memory allocated, calls, and where the own time goes (your code, the JumPHP engine, libraries, PHP itself).
- 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.
- 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.
- 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).
- 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
updateandrender. - 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.
- 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). - 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 (withfile: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/jumphpwithJUMPHP_PROFILE=<folder under var/>(andJUMPHP_PROFILE_MODE=profileorprofile,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).