support heap sampling params

Author: IlyasShabi

doc/api/v8.md

@@ -1788,23 +1788,92 @@ const profile = handle.stop();
 console.log(profile);
 ```
 
-## `v8.startHeapProfile()`
+## `v8.heapProfilerConstants`
 
 <!-- YAML
 added: REPLACEME
 -->
 
+* {Object}
+
+A frozen object containing constants used with [`v8.startHeapProfile()`][].
+
+The following constants are available:
+
+| Constant                                         | Description                                         |
+| ------------------------------------------------ | --------------------------------------------------- |
+| `SAMPLING_NO_FLAGS`                              | No flags.                                           |
+| `SAMPLING_FORCE_GC`                              | Force garbage collection before taking the profile. |
+| `SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC` | Include objects collected by major GC.              |
+| `SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC` | Include objects collected by minor GC.              |
+
+These constants can be combined using bitwise OR to pass as the `flags`
+parameter.
+
+## `v8.startHeapProfile([sampleInterval[, stackDepth[, flags]]])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sampleInterval` {number} The average sampling interval in bytes.
+  **Default:** `524288` (512 KiB).
+* `stackDepth` {integer} The maximum stack depth for samples.
+  **Default:** `16`.
+* `flags` {integer} Flags to control sampling behavior. Use constants from
+  [`v8.heapProfilerConstants`][]. Multiple flags can be combined with bitwise
+  OR. **Default:** `v8.heapProfilerConstants.SAMPLING_NO_FLAGS`.
 * Returns: {SyncHeapProfileHandle}
 
 Starting a heap profile then return a `SyncHeapProfileHandle` object.
 This API supports `using` syntax.
 
 ```cjs
+const v8 = require('node:v8');
+
 const handle = v8.startHeapProfile();
 const profile = handle.stop();
 console.log(profile);
 ```
 
+```mjs
+import v8 from 'node:v8';
+
+const handle = v8.startHeapProfile();
+const profile = handle.stop();
+console.log(profile);
+```
+
+With custom parameters:
+
+```cjs
+const v8 = require('node:v8');
+const { heapProfilerConstants } = v8;
+
+const handle = v8.startHeapProfile(
+  1024,
+  8,
+  heapProfilerConstants.SAMPLING_FORCE_GC |
+    heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC,
+);
+const profile = handle.stop();
+console.log(profile);
+```
+
+```mjs
+import v8 from 'node:v8';
+const { heapProfilerConstants } = v8;
+
+const handle = v8.startHeapProfile(
+  1024,
+  8,
+  heapProfilerConstants.SAMPLING_FORCE_GC |
+    heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC,
+);
+const profile = handle.stop();
+console.log(profile);
+```
+
 [CppHeap]: https://v8docs.nodesource.com/node-22.4/d9/dc4/classv8_1_1_cpp_heap.html
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 [Hook Callbacks]: #hook-callbacks
@@ -1839,6 +1908,8 @@ console.log(profile);
 [`serializer.transferArrayBuffer()`]: #serializertransferarraybufferid-arraybuffer
 [`serializer.writeRawBytes()`]: #serializerwriterawbytesbuffer
 [`settled` callback]: #settledpromise
+[`v8.heapProfilerConstants`]: #v8heapprofilerconstants
+[`v8.startHeapProfile()`]: #v8startheapprofilesampleinterval-stackdepth-flags
 [`v8.stopCoverage()`]: #v8stopcoverage
 [`v8.takeCoverage()`]: #v8takecoverage
 [`vm.Script`]: vm.md#new-vmscriptcode-options

doc/api/worker_threads.md

@@ -2005,14 +2005,21 @@ w.on('online', async () => {
 });
 ```
 
-### `worker.startHeapProfile()`
+### `worker.startHeapProfile([sampleInterval[, stackDepth[, flags]]])`
 
 <!-- YAML
 added:
   - v24.9.0
   - v22.20.0
 -->
 
+* `sampleInterval` {number} The average sampling interval in bytes.
+  **Default:** `524288` (512 KiB).
+* `stackDepth` {integer} The maximum stack depth for samples.
+  **Default:** `16`.
+* `flags` {integer} Flags to control sampling behavior. Use constants from
+  [`v8.heapProfilerConstants`][]. Multiple flags can be combined with bitwise
+  OR. **Default:** `v8.heapProfilerConstants.SAMPLING_NO_FLAGS`.
 * Returns: {Promise}
 
 Starting a Heap profile then return a Promise that fulfills with an error
@@ -2034,6 +2041,22 @@ worker.on('online', async () => {
 });
 ```
 
+```mjs
+import { Worker } from 'node:worker_threads';
+
+const worker = new Worker(`
+  const { parentPort } = require('node:worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+worker.on('online', async () => {
+  const handle = await worker.startHeapProfile();
+  const profile = await handle.stop();
+  console.log(profile);
+  worker.terminate();
+});
+```
+
 `await using` example.
 
 ```cjs
@@ -2050,6 +2073,20 @@ w.on('online', async () => {
 });
 ```
 
+```mjs
+import { Worker } from 'node:worker_threads';
+
+const w = new Worker(`
+  const { parentPort } = require('node:worker_threads');
+  parentPort.on('message', () => {});
+  `, { eval: true });
+
+w.on('online', async () => {
+  // Stop profile automatically when return and profile will be discarded
+  await using handle = await w.startHeapProfile();
+});
+```
+
 ### `worker.stderr`
 
 <!-- YAML
@@ -2266,6 +2303,7 @@ thread spawned will spawn another until the application crashes.
 [`trace_events`]: tracing.md
 [`v8.getHeapSnapshot()`]: v8.md#v8getheapsnapshotoptions
 [`v8.getHeapStatistics()`]: v8.md#v8getheapstatistics
+[`v8.heapProfilerConstants`]: v8.md#v8heapprofilerconstants
 [`vm`]: vm.md
 [`worker.SHARE_ENV`]: #worker_threadsshare_env
 [`worker.on('message')`]: #event-message_1

lib/internal/v8/heap_profile.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const {
+  ObjectFreeze,
+} = primordials;
+
+const {
+  validateInteger,
+  validateInt32,
+} = require('internal/validators');
+
+const {
+  kSamplingNoFlags,
+  kSamplingForceGC,
+  kSamplingIncludeObjectsCollectedByMajorGC,
+  kSamplingIncludeObjectsCollectedByMinorGC,
+} = internalBinding('v8');
+
+const heapProfilerConstants = {
+  __proto__: null,
+  SAMPLING_NO_FLAGS: kSamplingNoFlags,
+  SAMPLING_FORCE_GC: kSamplingForceGC,
+  SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC:
+    kSamplingIncludeObjectsCollectedByMajorGC,
+  SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC:
+    kSamplingIncludeObjectsCollectedByMinorGC,
+};
+ObjectFreeze(heapProfilerConstants);
+
+const kMaxSamplingFlags =
+  heapProfilerConstants.SAMPLING_FORCE_GC |
+  heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC |
+  heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC;
+
+function normalizeHeapProfileOptions(
+  sampleInterval = 512 * 1024,
+  stackDepth = 16,
+  flags = heapProfilerConstants.SAMPLING_NO_FLAGS,
+) {
+  validateInteger(sampleInterval, 'sampleInterval', 1);
+  validateInt32(stackDepth, 'stackDepth', 0);
+  validateInt32(flags, 'flags', 0, kMaxSamplingFlags);
+  return { sampleInterval, stackDepth, flags };
+}
+
+module.exports = {
+  heapProfilerConstants,
+  normalizeHeapProfileOptions,
+};

lib/internal/worker.js

@@ -65,7 +65,15 @@ const {
   constructSharedArrayBuffer,
   kEmptyObject,
 } = require('internal/util');
-const { validateArray, validateString, validateObject, validateNumber } = require('internal/validators');
+const {
+  validateArray,
+  validateString,
+  validateObject,
+  validateNumber,
+} = require('internal/validators');
+const {
+  normalizeHeapProfileOptions,
+} = require('internal/v8/heap_profile');
 const {
   throwIfBuildingSnapshot,
 } = require('internal/v8/startup_snapshot');
@@ -582,8 +590,11 @@ class Worker extends EventEmitter {
     });
   }
 
-  startHeapProfile() {
-    const startTaker = this[kHandle]?.startHeapProfile();
+  startHeapProfile(sampleInterval, stackDepth, flags) {
+    ({ sampleInterval, stackDepth, flags } =
+      normalizeHeapProfileOptions(sampleInterval, stackDepth, flags));
+    const startTaker = this[kHandle]?.startHeapProfile(
+      sampleInterval, stackDepth, flags);
     return new Promise((resolve, reject) => {
       if (!startTaker) return reject(new ERR_WORKER_NOT_RUNNING());
       startTaker.ondone = (err) => {

lib/v8.js

@@ -26,6 +26,7 @@ const {
   Int32Array,
   Int8Array,
   JSONParse,
+  ObjectDefineProperty,
   ObjectPrototypeToString,
   SymbolDispose,
   Uint16Array,
@@ -40,8 +41,8 @@ const {
 const { Buffer } = require('buffer');
 const {
   validateString,
-  validateUint32,
   validateOneOf,
+  validateUint32,
 } = require('internal/validators');
 const {
   Serializer,
@@ -50,6 +51,10 @@ const {
 const {
   namespace: startupSnapshot,
 } = require('internal/v8/startup_snapshot');
+const {
+  heapProfilerConstants,
+  normalizeHeapProfileOptions,
+} = require('internal/v8/heap_profile');
 
 let profiler = {};
 if (internalBinding('config').hasInspector) {
@@ -220,10 +225,15 @@ function startCpuProfile() {
 
 /**
  * Starting Heap Profile.
+ * @param {number} [sampleInterval]
+ * @param {number} [stackDepth]
+ * @param {number} [flags]
  * @returns {SyncHeapProfileHandle}
  */
-function startHeapProfile() {
-  _startHeapProfile();
+function startHeapProfile(sampleInterval, stackDepth, flags) {
+  ({ sampleInterval, stackDepth, flags } =
+    normalizeHeapProfileOptions(sampleInterval, stackDepth, flags));
+  _startHeapProfile(sampleInterval, stackDepth, flags);
   return new SyncHeapProfileHandle();
 }
 
@@ -547,3 +557,10 @@ module.exports = {
   startCpuProfile,
   startHeapProfile,
 };
+
+ObjectDefineProperty(module.exports, 'heapProfilerConstants', {
+  __proto__: null,
+  configurable: false,
+  enumerable: true,
+  value: heapProfilerConstants,
+});

src/node_v8.cc

@@ -282,7 +282,10 @@ void StopCpuProfile(const FunctionCallbackInfo<Value>& args) {
 
 void StartHeapProfile(const FunctionCallbackInfo<Value>& args) {
   Isolate* isolate = args.GetIsolate();
-  if (isolate->GetHeapProfiler()->StartSamplingHeapProfiler()) {
+  auto options = ParseHeapProfileOptions(args);
+
+  if (isolate->GetHeapProfiler()->StartSamplingHeapProfiler(
+          options.sample_interval, options.stack_depth, options.flags)) {
     return;
   }
   THROW_ERR_HEAP_PROFILE_HAVE_BEEN_STARTED(isolate,
@@ -766,6 +769,42 @@ void Initialize(Local<Object> target,
   SetMethod(context, target, "stopCpuProfile", StopCpuProfile);
   SetMethod(context, target, "startHeapProfile", StartHeapProfile);
   SetMethod(context, target, "stopHeapProfile", StopHeapProfile);
+  target
+      ->Set(context,
+            FIXED_ONE_BYTE_STRING(env->isolate(), "kSamplingNoFlags"),
+            Uint32::NewFromUnsigned(
+                env->isolate(),
+                static_cast<uint32_t>(
+                    v8::HeapProfiler::SamplingFlags::kSamplingNoFlags)))
+      .Check();
+  target
+      ->Set(context,
+            FIXED_ONE_BYTE_STRING(env->isolate(), "kSamplingForceGC"),
+            Uint32::NewFromUnsigned(
+                env->isolate(),
+                static_cast<uint32_t>(
+                    v8::HeapProfiler::SamplingFlags::kSamplingForceGC)))
+      .Check();
+  target
+      ->Set(
+          context,
+          FIXED_ONE_BYTE_STRING(
+              env->isolate(), "kSamplingIncludeObjectsCollectedByMajorGC"),
+          Uint32::NewFromUnsigned(
+              env->isolate(),
+              static_cast<uint32_t>(v8::HeapProfiler::SamplingFlags::
+                                        kSamplingIncludeObjectsCollectedByMajorGC)))
+      .Check();
+  target
+      ->Set(
+          context,
+          FIXED_ONE_BYTE_STRING(
+              env->isolate(), "kSamplingIncludeObjectsCollectedByMinorGC"),
+          Uint32::NewFromUnsigned(
+              env->isolate(),
+              static_cast<uint32_t>(v8::HeapProfiler::SamplingFlags::
+                                        kSamplingIncludeObjectsCollectedByMinorGC)))
+      .Check();
 
   // Export symbols used by v8.isStringOneByteRepresentation()
   SetFastMethodNoSideEffect(context,

src/node_worker.cc

@@ -1044,6 +1044,7 @@ void Worker::StartHeapProfile(const FunctionCallbackInfo<Value>& args) {
   Worker* w;
   ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
   Environment* env = w->env();
+  auto options = ParseHeapProfileOptions(args);
 
   AsyncHooks::DefaultTriggerAsyncIdScope trigger_id_scope(w);
   Local<Object> wrap;
@@ -1056,10 +1057,11 @@ void Worker::StartHeapProfile(const FunctionCallbackInfo<Value>& args) {
   BaseObjectPtr<WorkerHeapProfileTaker> taker =
       MakeDetachedBaseObject<WorkerHeapProfileTaker>(env, wrap);
 
-  bool scheduled = w->RequestInterrupt([taker = std::move(taker),
-                                        env](Environment* worker_env) mutable {
+  bool scheduled = w->RequestInterrupt([taker = std::move(taker), env, options](
+                                           Environment* worker_env) mutable {
     v8::HeapProfiler* profiler = worker_env->isolate()->GetHeapProfiler();
-    bool success = profiler->StartSamplingHeapProfiler();
+    bool success = profiler->StartSamplingHeapProfiler(
+        options.sample_interval, options.stack_depth, options.flags);
     env->SetImmediateThreadsafe(
         [taker = std::move(taker),
          success = success](Environment* env) mutable {