Repository navigation
node:v8: implement heap snapshot output #3140
Description
Summary
v8.getHeapSnapshot([options]) and v8.writeHeapSnapshot([filename[, options]]) should expose Node-compatible heap snapshot output as a readable stream and a written .heapsnapshot file. Perry currently has no public node:v8 implementation for this snapshot output surface.
Node Behavior
A minimal Node probe shows the stream and file contracts:
const v8 = require("node:v8");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
const stream = v8.getHeapSnapshot();
console.log(typeof stream.read, typeof stream.on, stream.constructor.name);
stream.setEncoding("utf8");
stream.once("data", chunk => console.log(chunk.slice(0, 20)));
const file = path.join(os.tmpdir(), "probe.heapsnapshot");
const written = v8.writeHeapSnapshot(file);
console.log(written, fs.existsSync(written), fs.statSync(written).size > 0);Observed on Node v25.9.0: getHeapSnapshot() returns a readable HeapSnapshotStream whose UTF-8 data starts with heap snapshot JSON such as {"snapshot":...; writeHeapSnapshot(file) writes a non-empty .heapsnapshot file and returns the written path.
Perry Behavior
docs/runtime-parity-gaps.md lists v8.getHeapSnapshot([options]) and v8.writeHeapSnapshot([filename[, options]]); docs/runtime-parity.md marks these rows covered based on external inventory. Source search across crates/perry-api-manifest/src/entries.rs, crates/perry-runtime/src, crates/perry-codegen/src, and crates/perry-stdlib/src found no public node:v8 heap snapshot implementation, and there is no dedicated V8 parity fixture in this checkout.
Suggested PR Cut
Batch this with related issues in:
#3296 - node:v8: snapshot and profiler output parity cut
Good batch candidates:
Do not batch with:
- unrelated modules
- broad subsystem rewrites
- fixes needing different test harnesses
- promise lifecycle hooks
- startup snapshot APIs
- serialization/heap-stat diagnostics (node:v8: expose serialize and deserialize round trips #3137, node:v8: expose heap statistics shape #3138, node:v8: expose Serializer and Deserializer class APIs #3294)
- exact V8 heap internals beyond Node-observable stream/file shape
Acceptance
- A parity/regression test proves
getHeapSnapshot()returns a readable stream and emits heap-snapshot-shaped JSON for the covered case. writeHeapSnapshot(filename)writes a non-empty file and returns the written path.- The snapshot contents may reflect Perry internals rather than V8 internals, but the stream/file contract and basic JSON shape match Node for package diagnostics.
- Related known-failure/docs/manifest entries are updated if touched.
Activity
andrewtdiz commentedon May 31, 2026
Fresh local check against the rebuilt release binary confirms this leaf is still open.
Current Node v25.9.0:
Current Perry manifest does not include either export, and with
PERRY_ALLOW_UNIMPLEMENTED=1the runtime namespace reports:Related broader v8 follow-up from the same probe: lifecycle/diagnostic-control exports are being tracked separately so this issue can stay focused on heap snapshot stream/file output.
fix(v8): expose modern diagnostics/profiler named exports (#3904)
fix(v8): expose modern diagnostics/profiler named exports (#3904) (#4012
andrewtdiz commentedon Jun 2, 2026
I am taking this cut.
Intended PR scope:
node:v8heap snapshot output forgetHeapSnapshot()andwriteHeapSnapshot(filename);This is a single-issue cut because the suggested related snapshot/profiler umbrella and GCProfiler child are already closed.
andrewtdiz commentedon Jun 3, 2026
Expanding this claimed cut to include #3142 as the focused
node:v8snapshot/profiler output PR. Scope remains narrow: heap snapshot stream/file shape plusGCProfilerconstructor/start/stop/report shape. Non-goals remain exact V8 heap internals, startup snapshot APIs, serialization/heap-stat diagnostics, promise lifecycle hooks, and CPU/heap profiling handle APIs.andrewtdiz commentedon Jun 3, 2026
Opened draft PR #4182 to implement the heap snapshot output APIs:
v8.getHeapSnapshot([options])now returns a readable heap-snapshot JSON stream, andv8.writeHeapSnapshot([filename[, options]])writes the same JSON to disk with Node-shaped argument validation.PR: #4182
andrewtdiz commentedon Jun 3, 2026
Opened draft PR #4182 for this: #4182
It includes
getHeapSnapshot()/writeHeapSnapshot()stream and file output, Node-shaped path/options validation, parity fixture coverage, and the related v8 export/native dispatch wiring.