From 8d819d62c76a71780ebe1b0c6f404d72a94948b4 Mon Sep 17 00:00:00 2001 From: ishabi Date: Thu, 19 Nov 2026 20:57:36 +0100 Subject: [PATCH 1/2] v8: add heap profiling setSampleInterval Signed-off-by: ishabi --- doc/api/errors.md | 7 ++ doc/api/v8.md | 95 +++++++++++++++- lib/internal/errors.js | 1 + lib/internal/worker.js | 32 ++++++ lib/v8.js | 19 ++++ src/node_profiling.cc | 40 ++++++- src/node_profiling.h | 6 + src/node_v8.cc | 27 +++++ src/node_worker.cc | 84 ++++++++++++++ src/node_worker.h | 4 + test/parallel/test-v8-heap-profile-samples.js | 104 ++++++++++++++++++ .../test-worker-heap-profile-samples.js | 94 ++++++++++++++++ typings/internalBinding/worker.d.ts | 12 ++ 13 files changed, 523 insertions(+), 2 deletions(-) create mode 100644 test/parallel/test-v8-heap-profile-samples.js create mode 100644 test/parallel/test-worker-heap-profile-samples.js diff --git a/doc/api/errors.md b/doc/api/errors.md index e6ab55bab058..e1e1c1688aac 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1528,6 +1528,13 @@ file in chunks. The number of file system events queued without being handled exceeded the size specified in `maxQueue` in `fs.watch()`. + + +### `ERR_HEAP_PROFILE_NOT_STARTED` + +An operation was attempted on a heap profile that has not been started or has +already been stopped or disposed. + ### `ERR_HTTP2_ALTSVC_INVALID_ORIGIN` diff --git a/doc/api/v8.md b/doc/api/v8.md index 2517866581e5..85785b65cf39 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -1618,6 +1618,62 @@ added: v26.1.0 > Stability: 1 - Experimental +### `syncHeapProfileHandle.getSamples()` + + + +* Returns: {Object\[]} + * `size` {number} Estimated total allocation size in bytes, equal to + `objectSize * objectCount`. + * `objectSize` {number} Size of the sampled object in bytes. + * `objectCount` {number} Estimated number of objects represented by the sample. + * `nodeId` {number} Identifier of the allocation's node in the profile call tree. + * `ordinal` {number} Unique, time-ordered identifier of the sample. + * `isLive` {boolean} Whether the sampled object is still live. + * `sampleInterval` {number} Sampling interval in bytes used when the sample + was selected. + +Returns the currently retained allocation samples without stopping profiling or +building the full profile call tree and resolving its script metadata. The sample +fields match those in the JSON returned by `stop()`. Use `ordinal` to identify +samples across calls; array order is unspecified. + +Live allocation samples are available with the default profiling options. +To also retain samples after their objects are collected, enable +`includeObjectsCollectedByMajorGC` or `includeObjectsCollectedByMinorGC` when +starting the profile. These samples have `isLive` set to `false`. The `forceGC` +option also applies to `getSamples()`. + +Throws `ERR_HEAP_PROFILE_NOT_STARTED` if this handle has been stopped or disposed. + +### `syncHeapProfileHandle.setSampleInterval(sampleInterval)` + + + +* `sampleInterval` {integer} Average sampling interval in bytes. Must be between + `1` and `Number.MAX_SAFE_INTEGER`, inclusive. + +Updates the sampling interval for future sample scheduling without restarting +profiling or discarding existing samples. A larger interval reduces sampling +frequency. Each sample retains the `sampleInterval` used when it was selected. + +Throws `ERR_HEAP_PROFILE_NOT_STARTED` if this handle has been stopped or disposed. + +```cjs +const v8 = require('node:v8'); + +const handle = v8.startHeapProfile({ sampleInterval: 1024 }); +// Run the workload to profile. +const samples = handle.getSamples(); +handle.setSampleInterval(4096); +// Continue profiling with less frequent sampling. +const profile = handle.stop(); +``` + ### `syncHeapProfileHandle.stop()` +### `heapProfileHandle.getSamples()` + + + +* Returns: {Promise} Fulfills with an {Object\[]} of allocation samples. + +Asynchronously retrieves the worker's retained allocation samples without +stopping profiling or building the full profile call tree. The sample fields and +profiling options are described in +[`syncHeapProfileHandle.getSamples()`][]. + +Rejects with `ERR_HEAP_PROFILE_NOT_STARTED` if this handle has been stopped or +disposed, or `ERR_WORKER_NOT_RUNNING` if the worker is no longer running. + +### `heapProfileHandle.setSampleInterval(sampleInterval)` + + + +* `sampleInterval` {integer} Average sampling interval in bytes. Must be between + `1` and `Number.MAX_SAFE_INTEGER`, inclusive. +* Returns: {Promise} Fulfills with `undefined` after the interval is updated. + +Asynchronously updates the worker's sampling interval for future sample +scheduling without restarting profiling or discarding existing samples. Each +sample retains the `sampleInterval` used when it was selected. + +Invalid arguments throw synchronously. The returned promise rejects with +`ERR_HEAP_PROFILE_NOT_STARTED` if this handle has been stopped or disposed, or +`ERR_WORKER_NOT_RUNNING` if the worker is no longer running. + ### `heapProfileHandle.stop()`