doc: add heap profiler labels API documentation

Document the new labels API on startSamplingHeapProfiler,
getAllocationProfile, withHeapProfileLabels, and
setHeapProfileLabels.

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

Author: rudolf

doc/api/v8.md

@@ -1453,6 +1453,108 @@ added:
 
 Returns true if the Node.js instance is run to build a snapshot.
 
+## Heap profile labels
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Attach string labels to V8 sampling heap profiler allocation samples.
+Combined with [`AsyncLocalStorage`][], labels propagate through `await`
+boundaries for per-context memory attribution (e.g., per-HTTP-route).
+
+### `v8.startSamplingHeapProfiler([sampleInterval[, stackDepth[, options]]])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sampleInterval` {number} Average interval in bytes. **Default:** `524288`.
+* `stackDepth` {number} Maximum call stack depth. **Default:** `16`.
+* `options` {Object}
+  * `includeCollectedObjects` {boolean} Retain samples for GC'd objects.
+    **Default:** `false`.
+
+Starts the V8 sampling heap profiler.
+
+### `v8.stopSamplingHeapProfiler()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Stops the sampling heap profiler and clears all registered label entries.
+
+### `v8.getAllocationProfile()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object | undefined}
+
+Returns the current allocation profile, or `undefined` if the profiler is
+not running.
+
+```json
+{
+  "samples": [
+    { "nodeId": 1, "size": 128, "count": 4, "sampleId": 42,
+      "labels": { "route": "/users/:id" } }
+  ]
+}
+```
+
+* `samples[].labels` — key-value string pairs from the active label context
+  at allocation time. Empty object if no labels were active.
+
+### `v8.withHeapProfileLabels(labels, fn)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `labels` {Object} Key-value string pairs (e.g., `{ route: '/users/:id' }`).
+* `fn` {Function} May be `async`.
+* Returns: {*} Return value of `fn`.
+
+Runs `fn` with the given labels active. If `fn` returns a promise, labels
+remain active until the promise settles.
+
+```js
+v8.startSamplingHeapProfiler(64);
+
+await v8.withHeapProfileLabels({ route: '/users' }, async () => {
+  const data = await fetchUsers();
+  return processData(data);
+});
+
+const profile = v8.getAllocationProfile();
+v8.stopSamplingHeapProfiler();
+```
+
+### `v8.setHeapProfileLabels(labels)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `labels` {Object} Key-value string pairs.
+
+Sets labels for the current async scope using `enterWith` semantics.
+Useful for frameworks where the handler runs after the extension returns.
+
+Prefer [`v8.withHeapProfileLabels()`][] when possible for automatic cleanup.
+
+### Limitations — what is measured
+
+Heap samples cover V8 heap allocations (JS objects, strings, closures).
+
+Not measured: `Buffer`/`ArrayBuffer` backing stores, native addon memory,
+JIT code space, OS-level allocations.
+
 ## Class: `v8.GCProfiler`
 
 <!-- YAML
@@ -1798,7 +1900,10 @@ console.log(profile);
 [`serializer.transferArrayBuffer()`]: #serializertransferarraybufferid-arraybuffer
 [`serializer.writeRawBytes()`]: #serializerwriterawbytesbuffer
 [`settled` callback]: #settledpromise
+[`v8.setHeapProfileLabels()`]: #v8setheapprofilelabelslabels
 [`v8.stopCoverage()`]: #v8stopcoverage
 [`v8.takeCoverage()`]: #v8takecoverage
+[`v8.withHeapProfileLabels()`]: #v8withheapprofilelabelslabels-fn
+[Limitations — what is measured]: #limitations--what-is-measured
 [`vm.Script`]: vm.md#new-vmscriptcode-options
 [worker threads]: worker_threads.md