docs(hr-benchmarking): add profile viewing and off-CPU guidance

Merged
BO
15h ago
+49-1

Adds commands and interpretation limits for local profile viewing, mixed native/JavaScript CPU attribution, allocation tracing and off-CPU analysis to the existing benchmarking tool reference. The additions come from a completed diagnostic trial; no benchmark improvement is claimed.

The reference now names speedscope, preserves default perf-script formatting for import, describes perf report --no-inline, explains heaptrack overhead, and pairs oha latency correction with its required rate limit. No tool becomes a benchmark prerequisite.

Validation on 5e97936: Node suite 151 pass / 7 skip; Bun suite 488 pass / 8 skip; skill scripts 338 pass; npm package check passed (235 files); pinned formatter passed. Pinned oxlint exited 0 with the existing no-control-regex warning in test/install-ps1.test.mjs. A real local speedscope import and scheduler-tracing smoke run also passed.

Review correction: the profileURL hash value is now encoded with encodeURIComponent, preserving nested query parameters. Confirmed in the packaged parser and a browser import with two query parameters. Focused formatting, privacy and local-link checks passed after the wording correction; no manual follow-up review was requested.

Summary by CodeRabbit

  • Documentation
    • Updated benchmarking guidance for viewing Node.js and native CPU profiles in speedscope, retaining native symbols, and limiting inline frames in perf.
    • Added notes on heaptrack overhead and the limits of off-CPU tracing, including scheduler traces for measuring off-CPU time.
    • Clarified that oha latency correction requires fixed-rate mode (-q) to take effect.