Skip to content

v8: add heap profile API#62273

Open
IlyasShabi wants to merge 2 commits intonodejs:mainfrom
IlyasShabi:ishabi/v8_heap_profile
Open

v8: add heap profile API#62273
IlyasShabi wants to merge 2 commits intonodejs:mainfrom
IlyasShabi:ishabi/v8_heap_profile

Conversation

@IlyasShabi
Copy link
Member

This PR succeeds #60231 by @theanarkh and adds parameter support for heap sampling on both the main thread and workers.

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 16, 2026
@IlyasShabi IlyasShabi force-pushed the ishabi/v8_heap_profile branch from 44720ea to 0221ebd Compare March 16, 2026 09:51
@IlyasShabi IlyasShabi marked this pull request as ready for review March 16, 2026 09:52
@IlyasShabi IlyasShabi force-pushed the ishabi/v8_heap_profile branch from 0221ebd to 5861bc1 Compare March 16, 2026 10:05
@Qard
Copy link
Member

Qard commented Mar 16, 2026

cc @nodejs/diagnostics

console.log(profile);
```
## `v8.heapProfilerConstants`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We very rarely expose bitfields and instead generally just let users pass us e.g. arrays of flags or options that we then translate in the JS wrapper. I could see exceptions made for highly performance-sensitive APIs, but I don't think this is an example of that

return v8::Just(mode);
}

static void buildHeapProfileNode(Isolate* isolate,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
static void buildHeapProfileNode(Isolate* isolate,
static void BuildHeapProfileNode(Isolate* isolate,

writer.json_arrayend();

writer.json_objectstart("head");
buildHeapProfileNode(isolate, profile->GetRootNode(), &writer);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
buildHeapProfileNode(isolate, profile->GetRootNode(), &writer);
BuildHeapProfileNode(isolate, profile->GetRootNode(), &writer);

Copy link
Member

@Qard Qard left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some DX and future-looking recommendations, but otherwise LGTM.

These constants can be combined using bitwise OR to pass as the `flags`
parameter.
## `v8.startHeapProfile([sampleInterval[, stackDepth[, flags]]])`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be better to take an object given that there's no particular dependency between any of these parameters--one could want to set any of them independently of the others.

added: REPLACEME
-->
* Returns: {string}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be better to return a Buffer instead. It'd give us more flexibility to add binary formats in the future. I'd like to add support at some point in the future for the pprof-derived format being defined in OpenTelemetry at the moment, which is a binary format.

@codecov
Copy link

codecov bot commented Mar 16, 2026

Codecov Report

❌ Patch coverage is 93.96552% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.70%. Comparing base (4579957) to head (5861bc1).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
src/util.cc 85.71% 1 Missing and 8 partials ⚠️
src/node_v8.cc 94.00% 1 Missing and 2 partials ⚠️
lib/v8.js 95.65% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #62273      +/-   ##
==========================================
+ Coverage   89.67%   89.70%   +0.02%     
==========================================
  Files         676      677       +1     
  Lines      206555   206734     +179     
  Branches    39554    39571      +17     
==========================================
+ Hits       185230   185449     +219     
+ Misses      13461    13424      -37     
+ Partials     7864     7861       -3     
Files with missing lines Coverage Δ
lib/internal/v8/heap_profile.js 100.00% <100.00%> (ø)
lib/internal/worker.js 96.57% <100.00%> (+0.05%) ⬆️
src/node_worker.cc 82.12% <100.00%> (+0.51%) ⬆️
src/node_worker.h 91.66% <ø> (ø)
src/util.h 91.20% <100.00%> (+0.29%) ⬆️
lib/v8.js 98.76% <95.65%> (-0.28%) ⬇️
src/node_v8.cc 82.82% <94.00%> (+1.11%) ⬆️
src/util.cc 87.22% <85.71%> (-0.23%) ⬇️

... and 40 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants