Skip to content

node:v8: implement GCProfiler report shape #3142

Description

@andrewtdiz

Summary

new v8.GCProfiler() should expose a profiling object whose start() / stop() methods collect and return a GC profiler report. Perry currently has no public node:v8 GCProfiler implementation.

Node Behavior

A minimal Node probe shows the profiler shape:

const v8 = require("node:v8");
const profiler = new v8.GCProfiler();
console.log(typeof v8.GCProfiler, profiler.constructor.name);
console.log(typeof profiler.start, typeof profiler.stop);
console.log(profiler.start());
const result = profiler.stop();
console.log(Object.keys(result));

Observed on Node v25.9.0: GCProfiler is a constructor; instances expose function-valued start and stop; start() returns undefined; stop() returns an object with keys including version, startTime, statistics, and endTime.

Perry Behavior

docs/runtime-parity.md marks new GCProfiler() missing under node:v8. docs/runtime-parity-gaps.md tracks node:v8 as a whole-module gap, source search found no public node:v8 GCProfiler 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:

Acceptance

  • A parity/regression test proves new v8.GCProfiler() returns an object with function-valued start and stop.
  • start() returns undefined, and stop() returns an object with Node-compatible report keys for the covered case.
  • The profiler data may reflect Perry internals or a minimal compatible report, but the constructor/method/report shape matches Node for package diagnostics.
  • Related known-failure/docs/manifest entries are updated if touched.

Activity

  1. andrewtdiz commented on Jun 3, 2026

    @andrewtdiz
    ContributorAuthor

    I am taking this with #3140 as one focused node:v8 snapshot/profiler output cut. Intended PR scope: add Node-shaped GCProfiler construction, start() / stop() behavior, and minimal report keys alongside the heap snapshot stream/file output work. Non-goals: exact V8 internals, startup snapshot APIs, serialization/heap-stat diagnostics, promise lifecycle hooks, and CPU/heap profiling handle APIs.

  2. andrewtdiz commented on Jun 3, 2026

    @andrewtdiz
    ContributorAuthor

    Opened draft PR #4182 for this: #4182

    It includes stateful GCProfiler construction, start() / stop() behavior, a minimal Node-shaped report object, and parity fixture coverage for namespace and named-import construction.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions