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()`