deps: add HeapProfileSampleLabelsCallback to V8 profiler

Add a callback mechanism to V8's SamplingHeapProfiler that allows
embedders to attach key-value string labels to allocation samples.

The callback receives the ContinuationPreservedEmbedderData (CPED) and
writes labels into the sample. This enables per-context memory
attribution (e.g., per-HTTP-route) when combined with AsyncLocalStorage.

Changes:
- AllocationProfile::Sample gains a `labels` field
- New HeapProfileSampleLabelsCallback typedef on HeapProfiler
- SamplingHeapProfiler invokes the callback in SampleObject()
- BuildSamples() copies labels to public Sample structs
- Gated behind V8_HEAP_PROFILER_SAMPLE_LABELS (requires CPED)

Signed-off-by: Rudolf Meijering <skaapgif@gmail.com>

Author: rudolf

deps/v8/include/v8-profiler.h

@@ -11,6 +11,11 @@
 #include <unordered_set>
 #include <vector>
 
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+#include <string>
+#include <utility>
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
 #include "cppgc/common.h"          // NOLINT(build/include_directory)
 #include "v8-local-handle.h"       // NOLINT(build/include_directory)
 #include "v8-message.h"            // NOLINT(build/include_directory)
@@ -791,26 +796,39 @@ class V8_EXPORT AllocationProfile {
    * Represent a single sample recorded for an allocation.
    */
   struct Sample {
-    /**
-     * id of the node in the profile tree.
-     */
+    Sample(uint32_t node_id, size_t size, unsigned int count,
+           uint64_t sample_id)
+        : node_id(node_id), size(size), count(count), sample_id(sample_id) {}
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+    Sample(uint32_t node_id, size_t size, unsigned int count,
+           uint64_t sample_id,
+           std::vector<std::pair<std::string, std::string>> labels)
+        : node_id(node_id),
+          size(size),
+          count(count),
+          sample_id(sample_id),
+          labels(std::move(labels)) {}
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
+    /** id of the node in the profile tree. */
     uint32_t node_id;
-
-    /**
-     * Size of the sampled allocation object.
-     */
+    /** Size of the sampled allocation object. */
     size_t size;
-
-    /**
-     * The number of objects of such size that were sampled.
-     */
+    /** The number of objects of such size that were sampled. */
     unsigned int count;
-
     /**
      * Unique time-ordered id of the allocation sample. Can be used to track
      * what samples were added or removed between two snapshots.
      */
     uint64_t sample_id;
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+    /**
+     * Embedder-provided labels captured at allocation time via the
+     * HeapProfileSampleLabelsCallback. Each pair is (key, value).
+     * Empty if no callback is registered or the callback returned no labels.
+     */
+    std::vector<std::pair<std::string, std::string>> labels;
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
   };
 
   /**
@@ -1001,6 +1019,24 @@ class V8_EXPORT HeapProfiler {
       v8::Isolate* isolate, const v8::Local<v8::Value>& v8_value,
       uint16_t class_id, void* data);
 
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  /**
+   * Callback invoked during sampling heap profiler allocation events to
+   * retrieve embedder-defined labels for the current execution context.
+   *
+   * |data| is the opaque pointer passed to SetHeapProfileSampleLabelsCallback.
+   * |context| is the ContinuationPreservedEmbedderData (CPED) value, which
+   * the embedder can use to look up the current async context (e.g., route).
+   *
+   * Write labels to out_labels and return true, or return false if no labels
+   * apply. The caller provides a stack-local vector; returning false avoids
+   * any heap allocation on the hot path.
+   */
+  using HeapProfileSampleLabelsCallback = bool (*)(
+      void* data, v8::Local<v8::Value> context,
+      std::vector<std::pair<std::string, std::string>>* out_labels);
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
   /** Returns the number of snapshots taken. */
   int GetSnapshotCount();
 
@@ -1261,6 +1297,18 @@ class V8_EXPORT HeapProfiler {
 
   void SetGetDetachednessCallback(GetDetachednessCallback callback, void* data);
 
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  /**
+   * Registers a callback that the sampling heap profiler invokes on each
+   * allocation to retrieve embedder-defined string labels. The labels are
+   * stored on AllocationProfile::Sample::labels.
+   *
+   * Pass nullptr to clear the callback.
+   */
+  void SetHeapProfileSampleLabelsCallback(
+      HeapProfileSampleLabelsCallback callback, void* data = nullptr);
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
   /**
    * Returns whether the heap profiler is currently taking a snapshot.
    */

deps/v8/src/api/api.cc

@@ -11829,6 +11829,14 @@ void HeapProfiler::SetGetDetachednessCallback(GetDetachednessCallback callback,
                                                                        data);
 }
 
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+void HeapProfiler::SetHeapProfileSampleLabelsCallback(
+    HeapProfileSampleLabelsCallback callback, void* data) {
+  reinterpret_cast<i::HeapProfiler*>(this)
+      ->SetHeapProfileSampleLabelsCallback(callback, data);
+}
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
 bool HeapProfiler::IsTakingSnapshot() {
   return reinterpret_cast<i::HeapProfiler*>(this)->IsTakingSnapshot();
 }

deps/v8/src/profiler/heap-profiler.h

@@ -79,6 +79,21 @@ class HeapProfiler : public HeapObjectAllocationTracker {
   bool is_sampling_allocations() { return !!sampling_heap_profiler_; }
   AllocationProfile* GetAllocationProfile();
 
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  void SetHeapProfileSampleLabelsCallback(
+      v8::HeapProfiler::HeapProfileSampleLabelsCallback callback,
+      void* data) {
+    sample_labels_callback_ = callback;
+    sample_labels_data_ = data;
+  }
+
+  v8::HeapProfiler::HeapProfileSampleLabelsCallback
+  sample_labels_callback() const {
+    return sample_labels_callback_;
+  }
+  void* sample_labels_data() const { return sample_labels_data_; }
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
   void StartHeapObjectsTracking(bool track_allocations);
   void StopHeapObjectsTracking();
   AllocationTracker* allocation_tracker() const {
@@ -176,6 +191,11 @@ class HeapProfiler : public HeapObjectAllocationTracker {
   std::pair<v8::HeapProfiler::GetDetachednessCallback, void*>
       get_detachedness_callback_;
   std::unique_ptr<HeapProfilerNativeMoveListener> native_move_listener_;
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  v8::HeapProfiler::HeapProfileSampleLabelsCallback sample_labels_callback_ =
+      nullptr;
+  void* sample_labels_data_ = nullptr;
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
 };
 
 }  // namespace internal

deps/v8/src/profiler/sampling-heap-profiler.cc

@@ -15,6 +15,7 @@
 #include "src/execution/isolate.h"
 #include "src/heap/heap-layout-inl.h"
 #include "src/heap/heap.h"
+#include "src/profiler/heap-profiler.h"
 #include "src/profiler/strings-storage.h"
 
 namespace v8 {
@@ -96,6 +97,30 @@ void SamplingHeapProfiler::SampleObject(Address soon_object, size_t size) {
   node->allocations_[size]++;
   auto sample =
       std::make_unique<Sample>(size, node, loc, this, next_sample_id());
+
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  // If an embedder labels callback is registered, invoke it to capture
+  // context labels (e.g., route name from AsyncLocalStorage).
+  // V8 reads the CPED and passes it + the stored data pointer to the callback.
+  // The callback runs inside DisallowGarbageCollection — it must only use
+  // malloc-based allocations (std::string), not V8 heap allocations.
+  {
+    HeapProfiler* hp = isolate_->heap()->heap_profiler();
+    auto labels_callback = hp->sample_labels_callback();
+    if (labels_callback) {
+      v8::Isolate* v8_isolate = reinterpret_cast<v8::Isolate*>(isolate_);
+      v8::Local<v8::Value> context =
+          v8_isolate->GetContinuationPreservedEmbedderData();
+      if (!context.IsEmpty() && !context->IsUndefined()) {
+        std::vector<std::pair<std::string, std::string>> labels;
+        if (labels_callback(hp->sample_labels_data(), context, &labels)) {
+          sample->labels = std::move(labels);
+        }
+      }
+    }
+  }
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
   sample->global.SetWeak(sample.get(), OnWeakCallback,
                          WeakCallbackType::kParameter);
   samples_.emplace(sample.get(), std::move(sample));
@@ -312,9 +337,15 @@ SamplingHeapProfiler::BuildSamples() const {
   samples.reserve(samples_.size());
   for (const auto& it : samples_) {
     const Sample* sample = it.second.get();
-    samples.emplace_back(v8::AllocationProfile::Sample{
-        sample->owner->id_, sample->size, ScaleSample(sample->size, 1).count,
-        sample->sample_id});
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+    samples.emplace_back(sample->owner->id_, sample->size,
+                         ScaleSample(sample->size, 1).count,
+                         sample->sample_id, sample->labels);
+#else
+    samples.emplace_back(sample->owner->id_, sample->size,
+                         ScaleSample(sample->size, 1).count,
+                         sample->sample_id);
+#endif
   }
   return samples;
 }

deps/v8/src/profiler/sampling-heap-profiler.h

@@ -114,6 +114,7 @@ class SamplingHeapProfiler {
     Global<Value> global;
     SamplingHeapProfiler* const profiler;
     const uint64_t sample_id;
+    std::vector<std::pair<std::string, std::string>> labels;
   };
 
   SamplingHeapProfiler(Heap* heap, StringsStorage* names, uint64_t rate,

tools/v8_gypfiles/features.gypi

@@ -523,7 +523,12 @@
         'defines': ['V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS',],
       }],
       ['v8_enable_continuation_preserved_embedder_data==1', {
-        'defines': ['V8_ENABLE_CONTINUATION_PRESERVED_EMBEDDER_DATA',],
+        'defines': [
+          'V8_ENABLE_CONTINUATION_PRESERVED_EMBEDDER_DATA',
+          # Enable heap profiler sample labels for per-context memory
+          # attribution when CPED is available.
+          'V8_HEAP_PROFILER_SAMPLE_LABELS',
+        ],
       }],
       ['v8_enable_allocation_folding==1', {
         'defines': ['V8_ALLOCATION_FOLDING',],