Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_018nX3d1jqkxbS2Bhas8tTzM
68 lines
5.2 KiB
Markdown
68 lines
5.2 KiB
Markdown
# The IDE's profiler
|
|
|
|
[Français](ide-profiler.fr.md)
|
|
|
|
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).
|