v8: add heap profile API

PR-URL: #62273
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: IlyasShabi

doc/api/v8.md

@@ -1617,6 +1617,32 @@ added:
 
 Stopping collecting the profile and the profile will be discarded.
 
+## Class: `SyncHeapProfileHandle`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+### `syncHeapProfileHandle.stop()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string}
+
+Stopping collecting the profile and return the profile data.
+
+### `syncHeapProfileHandle[Symbol.dispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Stopping collecting the profile and the profile will be discarded.
+
 ## Class: `CPUProfileHandle`
 
 <!-- YAML
@@ -1764,6 +1790,72 @@ const profile = handle.stop();
 console.log(profile);
 ```
 
+## `v8.startHeapProfile([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options` {Object}
+  * `sampleInterval` {number} The average sampling interval in bytes.
+    **Default:** `524288` (512 KiB).
+  * `stackDepth` {integer} The maximum stack depth for samples.
+    **Default:** `16`.
+  * `forceGC` {boolean} Force garbage collection before taking the profile.
+    **Default:** `false`.
+  * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected
+    by major GC. **Default:** `false`.
+  * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected
+    by minor GC. **Default:** `false`.
+* 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 handle = v8.startHeapProfile({
+  sampleInterval: 1024,
+  stackDepth: 8,
+  forceGC: true,
+  includeObjectsCollectedByMajorGC: true,
+});
+const profile = handle.stop();
+console.log(profile);
+```
+
+```mjs
+import v8 from 'node:v8';
+
+const handle = v8.startHeapProfile({
+  sampleInterval: 1024,
+  stackDepth: 8,
+  forceGC: true,
+  includeObjectsCollectedByMajorGC: true,
+});
+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

doc/api/worker_threads.md

@@ -2005,14 +2005,25 @@ w.on('online', async () => {
 });
 ```
 
-### `worker.startHeapProfile()`
+### `worker.startHeapProfile([options])`
 
 <!-- YAML
 added:
   - v24.9.0
   - v22.20.0
 -->
 
+* `options` {Object}
+  * `sampleInterval` {number} The average sampling interval in bytes.
+    **Default:** `524288` (512 KiB).
+  * `stackDepth` {integer} The maximum stack depth for samples.
+    **Default:** `16`.
+  * `forceGC` {boolean} Force garbage collection before taking the profile.
+    **Default:** `false`.
+  * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected
+    by major GC. **Default:** `false`.
+  * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected
+    by minor GC. **Default:** `false`.
 * Returns: {Promise}
 
 Starting a Heap profile then return a Promise that fulfills with an error
@@ -2034,6 +2045,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 +2077,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

lib/internal/v8/heap_profile.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const {
+  validateBoolean,
+  validateInteger,
+  validateInt32,
+  validateObject,
+} = require('internal/validators');
+
+const {
+  kSamplingNoFlags,
+  kSamplingForceGC,
+  kSamplingIncludeObjectsCollectedByMajorGC,
+  kSamplingIncludeObjectsCollectedByMinorGC,
+} = internalBinding('v8');
+
+function normalizeHeapProfileOptions(options = {}) {
+  validateObject(options, 'options');
+  const {
+    sampleInterval = 512 * 1024,
+    stackDepth = 16,
+    forceGC = false,
+    includeObjectsCollectedByMajorGC = false,
+    includeObjectsCollectedByMinorGC = false,
+  } = options;
+
+  validateInteger(sampleInterval, 'options.sampleInterval', 1);
+  validateInt32(stackDepth, 'options.stackDepth', 0);
+  validateBoolean(forceGC, 'options.forceGC');
+  validateBoolean(includeObjectsCollectedByMajorGC,
+                  'options.includeObjectsCollectedByMajorGC');
+  validateBoolean(includeObjectsCollectedByMinorGC,
+                  'options.includeObjectsCollectedByMinorGC');
+
+  let flags = kSamplingNoFlags;
+  if (forceGC) flags |= kSamplingForceGC;
+  if (includeObjectsCollectedByMajorGC) {
+    flags |= kSamplingIncludeObjectsCollectedByMajorGC;
+  }
+  if (includeObjectsCollectedByMinorGC) {
+    flags |= kSamplingIncludeObjectsCollectedByMinorGC;
+  }
+
+  return { sampleInterval, stackDepth, flags };
+}
+
+module.exports = {
+  normalizeHeapProfileOptions,
+};

lib/internal/worker.js

@@ -65,7 +65,13 @@ const {
   constructSharedArrayBuffer,
   kEmptyObject,
 } = require('internal/util');
-const { validateArray, validateString, validateObject, validateNumber } = require('internal/validators');
+const {
+  validateArray,
+  validateString,
+  validateObject,
+  validateNumber,
+} = require('internal/validators');
+let normalizeHeapProfileOptions;
 const {
   throwIfBuildingSnapshot,
 } = require('internal/v8/startup_snapshot');
@@ -582,8 +588,22 @@ class Worker extends EventEmitter {
     });
   }
 
-  startHeapProfile() {
-    const startTaker = this[kHandle]?.startHeapProfile();
+  /**
+   * @param {object} [options]
+   * @param {number} [options.sampleInterval]
+   * @param {number} [options.stackDepth]
+   * @param {boolean} [options.forceGC]
+   * @param {boolean} [options.includeObjectsCollectedByMajorGC]
+   * @param {boolean} [options.includeObjectsCollectedByMinorGC]
+   * @returns {Promise}
+   */
+  startHeapProfile(options) {
+    normalizeHeapProfileOptions ??=
+      require('internal/v8/heap_profile').normalizeHeapProfileOptions;
+    const { sampleInterval, stackDepth, flags } =
+      normalizeHeapProfileOptions(options);
+    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

@@ -40,8 +40,8 @@ const {
 const { Buffer } = require('buffer');
 const {
   validateString,
-  validateUint32,
   validateOneOf,
+  validateUint32,
 } = require('internal/validators');
 const {
   Serializer,
@@ -50,6 +50,9 @@ const {
 const {
   namespace: startupSnapshot,
 } = require('internal/v8/startup_snapshot');
+const {
+  normalizeHeapProfileOptions,
+} = require('internal/v8/heap_profile');
 
 let profiler = {};
 if (internalBinding('config').hasInspector) {
@@ -115,6 +118,8 @@ const {
   setFlagsFromString: _setFlagsFromString,
   startCpuProfile: _startCpuProfile,
   stopCpuProfile: _stopCpuProfile,
+  startHeapProfile: _startHeapProfile,
+  stopHeapProfile: _stopHeapProfile,
   isStringOneByteRepresentation: _isStringOneByteRepresentation,
   updateHeapStatisticsBuffer,
   updateHeapSpaceStatisticsBuffer,
@@ -191,6 +196,22 @@ class SyncCPUProfileHandle {
   }
 }
 
+class SyncHeapProfileHandle {
+  #stopped = false;
+
+  stop() {
+    if (this.#stopped) {
+      return;
+    }
+    this.#stopped = true;
+    return _stopHeapProfile();
+  };
+
+  [SymbolDispose]() {
+    this.stop();
+  }
+}
+
 /**
  * Starting CPU Profile.
  * @returns {SyncCPUProfileHandle}
@@ -200,6 +221,23 @@ function startCpuProfile() {
   return new SyncCPUProfileHandle(id);
 }
 
+/**
+ * Starting Heap Profile.
+ * @param {object} [options]
+ * @param {number} [options.sampleInterval]
+ * @param {number} [options.stackDepth]
+ * @param {boolean} [options.forceGC]
+ * @param {boolean} [options.includeObjectsCollectedByMajorGC]
+ * @param {boolean} [options.includeObjectsCollectedByMinorGC]
+ * @returns {SyncHeapProfileHandle}
+ */
+function startHeapProfile(options) {
+  const { sampleInterval, stackDepth, flags } =
+    normalizeHeapProfileOptions(options);
+  _startHeapProfile(sampleInterval, stackDepth, flags);
+  return new SyncHeapProfileHandle();
+}
+
 /**
  * Return whether this string uses one byte as underlying representation or not.
  * @param {string} content
@@ -518,4 +556,5 @@ module.exports = {
   GCProfiler,
   isStringOneByteRepresentation,
   startCpuProfile,
+  startHeapProfile,
 };