lib: add heap profile labels API to v8 module

JS API for heap profile label attribution:
- withHeapProfileLabels(labels, fn): scoped labels via AsyncLocalStorage
  — just ALS.run with pre-flattened label array, zero C++ calls
- setHeapProfileLabels(labels): enterWith semantics for frameworks where
  the handler runs after the middleware returns (e.g., Hapi)
- startSamplingHeapProfiler with includeCollectedObjects option
- stopSamplingHeapProfiler and getAllocationProfile with labels

Labels are pre-flattened to [key, val, key, val, ...] arrays at set
time for GC safety — the C++ callback runs during BuildSamples()
iteration where V8 object allocation could invalidate the iterator.

Signed-off-by: Rudolf Meijering <[email protected]>

Author: rudolf

lib/v8.js

@@ -16,6 +16,7 @@
 
 const {
   Array,
+  ArrayPrototypePush,
   BigInt64Array,
   BigUint64Array,
   DataView,
@@ -26,7 +27,9 @@ const {
   Int32Array,
   Int8Array,
   JSONParse,
+  ObjectKeys,
   ObjectPrototypeToString,
+  String,
   SymbolDispose,
   Uint16Array,
   Uint32Array,
@@ -38,7 +41,10 @@ const {
 } = primordials;
 
 const { Buffer } = require('buffer');
+const { AsyncLocalStorage } = require('async_hooks');
 const {
+  validateFunction,
+  validateObject,
   validateString,
   validateUint32,
   validateOneOf,
@@ -156,6 +162,11 @@ const {
   heapSpaceStatisticsBuffer,
   getCppHeapStatistics: _getCppHeapStatistics,
   detailLevel,
+
+  startSamplingHeapProfiler: _startSamplingHeapProfiler,
+  stopSamplingHeapProfiler: _stopSamplingHeapProfiler,
+  getAllocationProfile: _getAllocationProfile,
+  setHeapProfileLabelsStore: _setHeapProfileLabelsStore,
 } = binding;
 
 const kNumberOfHeapSpaces = kHeapSpaces.length;
@@ -494,6 +505,81 @@ class GCProfiler {
   }
 }
 
+// --- Heap profile labels API ---
+// Internal AsyncLocalStorage for propagating labels through async context.
+// Requires --experimental-async-context-frame (Node 22) or Node 24+.
+const _heapProfileLabelsALS = new AsyncLocalStorage();
+// Register the ALS instance with C++ so the V8 callback can look up
+// label values from stored CPED (AsyncContextFrame Map) at read time.
+_setHeapProfileLabelsStore(_heapProfileLabelsALS);
+
+/**
+ * Convert a labels object to a flat array [key1, val1, key2, val2, ...].
+ * Pre-flattened at label-set time (not per allocation/sample) because the
+ * C++ callback runs during BuildSamples() iteration where V8 Object property
+ * access could allocate and trigger GC, invalidating the sample iterator.
+ * @param {Record<string, string>} labels
+ * @returns {string[]}
+ */
+function labelsToFlat(labels) {
+  const keys = ObjectKeys(labels);
+  const flat = [];
+  for (let i = 0; i < keys.length; i++) {
+    ArrayPrototypePush(flat, String(keys[i]), String(labels[keys[i]]));
+  }
+  return flat;
+}
+
+/**
+ * Starts the V8 sampling heap profiler.
+ * @param {number} [sampleInterval] - Average bytes between samples (default 512 KB).
+ * @param {number} [stackDepth] - Maximum stack depth for samples (default 16).
+ * @param {object} [options] - Options object.
+ * @param {boolean} [options.includeCollectedObjects] - If true, retain
+ *   samples for objects collected by GC (allocation-rate mode).
+ */
+function startSamplingHeapProfiler(sampleInterval, stackDepth, options) {
+  if (sampleInterval !== undefined) validateUint32(sampleInterval, 'sampleInterval');
+  if (stackDepth !== undefined) validateUint32(stackDepth, 'stackDepth');
+  if (options !== undefined) validateObject(options, 'options');
+  return _startSamplingHeapProfiler(sampleInterval, stackDepth, options);
+}
+
+/**
+ * Runs `fn` with the given heap profile labels active. Labels propagate
+ * across `await` boundaries via AsyncLocalStorage. If `fn` returns a
+ * Promise, labels remain active until the Promise settles.
+ *
+ * @param {Record<string, string>} labels
+ * @param {Function} fn
+ * @returns {*} The return value of `fn`.
+ */
+function withHeapProfileLabels(labels, fn) {
+  validateObject(labels, 'labels');
+  validateFunction(fn, 'fn');
+  // Store the flat [key1, val1, key2, val2, ...] array in ALS.
+  // Conversion happens once at label-set time (not per allocation).
+  // Must stay pre-flattened because the C++ callback runs during
+  // BuildSamples iteration — Object property access would allocate
+  // V8 objects, potentially triggering GC and invalidating the iterator.
+  const flat = labelsToFlat(labels);
+  return _heapProfileLabelsALS.run(flat, fn);
+}
+
+/**
+ * Sets heap profile labels for the current async scope using
+ * `enterWith` semantics. Labels persist until overwritten or the
+ * async scope ends. Useful for frameworks (e.g. Hapi) where the
+ * handler runs after the extension returns.
+ *
+ * @param {Record<string, string>} labels
+ */
+function setHeapProfileLabels(labels) {
+  validateObject(labels, 'labels');
+  const flat = labelsToFlat(labels);
+  _heapProfileLabelsALS.enterWith(flat);
+}
+
 module.exports = {
   cachedDataVersionTag,
   getHeapSnapshot,
@@ -518,4 +604,9 @@ module.exports = {
   GCProfiler,
   isStringOneByteRepresentation,
   startCpuProfile,
+  startSamplingHeapProfiler,
+  stopSamplingHeapProfiler: _stopSamplingHeapProfiler,
+  getAllocationProfile: _getAllocationProfile,
+  withHeapProfileLabels,
+  setHeapProfileLabels,
 };