docs(book): rewrite the profiling chapter around perf and --cpu-prof - #1640
Conversation
The chapter now documents three lenses with an up-front comparison of what each can and cannot see: - Rust-only: cargo flamegraph over a recorded scenario (fixed the stale crates/tools path — scenarios live in js/benchmark/scenarios/ and the replay bin is edr_tool_cli). - Cross-language sampling: Linux perf over the whole process tree, with the build:perf-js artifact injected via NAPI_RS_NATIVE_LIBRARY_PATH (or Verdaccio) and V8 perf maps for JS frame names. Rendering via inferno or speedscope. - JS-level attribution: node --cpu-prof, including interval trade-offs, NODE_OPTIONS propagation, the graceful-exit flush caveat, and bun's equivalent flags. The 0x section is removed: --kernel-tracing wraps the same perf data source (the old text claiming it runs the V8 tick profiler and perf simultaneously was incorrect) with less control and no reusable output. A permissions appendix covers perf_event_paranoid and containers, preferring a seccomp profile that allows unprivileged perf_event_open (no added capabilities; own-process sampling only) over capabilities, with CAP_PERFMON as the fallback — SYS_ADMIN is obsolete for this, so the devcontainer suggestion now names PERFMON. build:perf-js now sets CARGO_PROFILE_NAPI_PUBLISH_DEBUG=line-tables-only itself: a profiling build should always carry symbol names (the .node artifact grows to ~160 MB, acceptable for this purpose-built profile).
|
There was a problem hiding this comment.
Pull request overview
Rewrites profiling guidance around Rust, cross-language, and JavaScript profiling methods.
Changes:
- Adds
perfand--cpu-profworkflows. - Enables debug symbols in performance builds.
- Updates devcontainer profiling capability guidance.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
crates/edr_napi/package.json |
Adds symbols to profiling builds. |
book/src/01_getting_started/06_profiling.md |
Reworks profiling documentation. |
.devcontainer/devcontainer.json |
Replaces SYS_ADMIN guidance with PERFMON. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1640 +/- ##
===========================================
- Coverage 80.01% 47.06% -32.96%
===========================================
Files 464 439 -25
Lines 80392 69186 -11206
Branches 80392 69186 -11206
===========================================
- Hits 64329 32565 -31764
- Misses 13856 35324 +21468
+ Partials 2207 1297 -910 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
popescuoctavian
left a comment
popescuoctavian
left a comment
There was a problem hiding this comment.
LGTM, thanks for updating the docs! Just one nit (as a mac user 😄 )
|
Tests are failing as this is a PR originating from my fork, which is lacking an |
617568b
This change in documentation pairs with NomicFoundation/hardhat#8546
The chapter now documents three lenses with an up-front comparison of what each can and cannot see:
The 0x section is removed: --kernel-tracing wraps the same perf data source (the old text claiming it runs the V8 tick profiler and perf simultaneously was incorrect) with less control and no reusable output.
A permissions appendix covers perf_event_paranoid and containers, preferring a seccomp profile that allows unprivileged perf_event_open (no added capabilities; own-process sampling only) over capabilities, with CAP_PERFMON as the fallback — SYS_ADMIN is obsolete for this, so the devcontainer suggestion now names PERFMON.
build:perf-js now sets CARGO_PROFILE_NAPI_PUBLISH_DEBUG=line-tables-only itself: a profiling build should always carry symbol names (the .node artifact grows to ~160 MB, acceptable for this purpose-built profile).