v8.setHeapProfileNearHeapLimit

v8.setHeapProfileNearHeapLimit(limit): void

Writes the active sampling heap profile as a .heapprofile file when V8 is near the heap limit, up to limit times. Files are written to the directory configured by --diagnostic-dir (or to the current working directory if the option is unset), using the Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile naming convention.

v8.startHeapProfile() must be called before this API can capture a profile. If no sampling heap profile is active when V8 reaches the heap limit, the callback is uninstalled and V8 continues its normal out-of-memory behavior.

This API can be used together with v8.setHeapSnapshotNearHeapLimit(). Each API maintains its own limit.

Writing is best-effort. Materializing the sampled call tree can allocate V8 and native memory, so the profile might not be completed if the process has insufficient memory available. The serialized profile is written by native code and is not exposed to JavaScript.

Calling setHeapProfileNearHeapLimit() more than once is a no-op. limit must be a positive integer.