Skip to content

v8: add setHeapProfileNearHeapLimit#64676

Open
IlyasShabi wants to merge 2 commits into
nodejs:mainfrom
IlyasShabi:ishabi/near-heap-limit-profile
Open

v8: add setHeapProfileNearHeapLimit#64676
IlyasShabi wants to merge 2 commits into
nodejs:mainfrom
IlyasShabi:ishabi/near-heap-limit-profile

Conversation

@IlyasShabi

Copy link
Copy Markdown
Member

Adds v8.setHeapProfileNearHeapLimit(onProfile, options) API that captures the active sampling heap profile when V8 is near the heap limit and delivers it to a JS callback. This is complements v8.setHeapSnapshotNearHeapLimit for observability use cases that want the sampled allocation profile rather than a full heap snapshot at OOM time.

This new API requires v8.startHeapProfile() to have been called before.

Both setHeapProfileNearHeapLimit and setHeapSnapshotNearHeapLimit can be active on the same isolate.

Signed-off-by: ishabi <ilyasshabi94@gmail.com>
@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 Jul 22, 2026
@IlyasShabi
IlyasShabi marked this pull request as ready for review July 22, 2026 14:03
Comment thread src/env.cc Outdated
env,
});
console.log(child.stdout.toString());
console.log(child.stderr.toString());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Are the console.log(...) log statements necessary for the test? If not, can we remove them? If they are, can you add a comment?

Comment thread doc/api/v8.md
@joyeecheung

joyeecheung commented Jul 22, 2026

Copy link
Copy Markdown
Member

I struggle to see how this API can ever stabilize - what one can do when the heap is near the heap limit is very limited, and in particular if you do too much in the callback to incur another allocation, the program would be in a very unstable state. Our current callbacks only do very limited things within the C++, allowing users to do arbitrary things in JS sounds like an API that invites bugs...I think a safer option would be to only write a profile when it reaches the limit, though even then I am not sure how well the profiler works when the heap is about to reach the limit...

@legendecas

Copy link
Copy Markdown
Member

I'm also wary on adding a JS callback to be invoked at new heap limit. This callback also takes a heap profile parameter which is taken on a big heap, sounds like exacerbating the problem it wants to fix.

Comment thread doc/api/v8.md

v8.startHeapProfile();
v8.setHeapProfileNearHeapLimit((profile) => {
console.log(JSON.parse(profile));

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This example asks users to exacerbating the heap usages when the heap is near limit...

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