performance:profile

Profile

Goal: a ranked, readable list of where the program's time goes on the scenario the user cares about, with each entry's share of the total. Every optimization decision rests on that list, so it must come from a measurement of the real scenario.

Tools

• samply: !samply --version 2>/dev/null || echo "not found. Required for native and whole-process profiles."
• hyperfine: !hyperfine --version 2>/dev/null || echo "not found. Needed for the wall/CPU split."
• bun: !bun --version 2>/dev/null || echo "not found."
• node: !node --version 2>/dev/null || echo "not found."
• agent-browser: !agent-browser --version 2>/dev/null || echo "not found. Required for web apps."
• py-spy: !py-spy --version 2>/dev/null || echo "not found. Needed only for Python."

When a required tool is missing and the project's own tooling does not cover its job, tell the user which one, then stop.

Existing Tooling

Look for the project's own profiling setup before recording one: profiling scripts, an environment variable that turns on a profiler, a formatter for profiler output. Use it when it meets the requirements the references below are built to meet:

• Scenario. It profiles the scenario and build the user runs.
• Ranking. It ranks entries by self and inclusive time with each one's share, or writes a file that a summarizer or viewer ranks.
• Coverage. It covers every process the scenario spawns, and time spent waiting when wall time exceeds CPU.

When it misses some, use it for what it covers and add a profiler from the references for the rest.

Split Wall From CPU

Run the scenario once under hyperfine --runs 3 and compare wall time with user plus system CPU.

• CPU-bound (CPU near wall): a sampling profiler finds the hot functions.
• Waiting (wall well above CPU): the time goes to network, disk, child processes, locks, or sleeps. Find what it waits on: which child process runs longest, which request is slow. A CPU profile of a waiting program ranks the wrong things.