deps: add heap profile sample labels to V8 profiler

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

At allocation time, SampleObject() captures the
ContinuationPreservedEmbedderData (CPED) as a Global<Value> on each
internal Sample. At profile-read time, BuildSamples() invokes the
registered HeapProfileSampleLabelsCallback with each sample's stored
CPED, allowing embedders to resolve labels from the async context.

This two-phase approach (capture at allocation, resolve at read) avoids
running embedder callbacks inside DisallowGarbageCollection scopes and
is immune to CPED identity changes caused by unrelated
AsyncLocalStorage stores.

Changes:
- AllocationProfile::Sample gains a `labels` field
- New HeapProfileSampleLabelsCallback typedef on HeapProfiler
- Internal Sample stores `Global<Value> cped` at allocation time
- BuildSamples() invokes labels callback with stored CPED
- Seven cctests covering callback API, GC behavior, unregistration
- features.gypi enables v8_enable_continuation_preserved_embedder_data

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,26 @@ 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, capture the CPED
+  // (ContinuationPreservedEmbedderData) for later label resolution in
+  // BuildSamples(). Storing as Global keeps the AsyncContextFrame alive
+  // and prevents it from being GC'd while the sample exists.
+  // Global::Reset is safe inside DisallowGC (uses malloc, not V8 heap).
+  {
+    HeapProfiler* hp = isolate_->heap()->heap_profiler();
+    if (hp->sample_labels_callback()) {
+      v8::Isolate* v8_isolate = reinterpret_cast<v8::Isolate*>(isolate_);
+      v8::Local<v8::Value> context =
+          v8_isolate->GetContinuationPreservedEmbedderData();
+      if (!context.IsEmpty() && !context->IsUndefined()) {
+        sample->cped.Reset(v8_isolate, context);
+      }
+    }
+  }
+#endif  // V8_HEAP_PROFILER_SAMPLE_LABELS
+
   sample->global.SetWeak(sample.get(), OnWeakCallback,
                          WeakCallbackType::kParameter);
   samples_.emplace(sample.get(), std::move(sample));
@@ -307,14 +328,34 @@ v8::AllocationProfile* SamplingHeapProfiler::GetAllocationProfile() {
 }
 
 const std::vector<v8::AllocationProfile::Sample>
-SamplingHeapProfiler::BuildSamples() const {
+SamplingHeapProfiler::BuildSamples() {
   std::vector<v8::AllocationProfile::Sample> samples;
   samples.reserve(samples_.size());
+
+#ifdef V8_HEAP_PROFILER_SAMPLE_LABELS
+  HeapProfiler* hp = heap_->heap_profiler();
+  auto callback = hp->sample_labels_callback();
+  void* callback_data = hp->sample_labels_data();
+  v8::Isolate* v8_isolate = reinterpret_cast<v8::Isolate*>(isolate_);
+#endif
+
   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
+    std::vector<std::pair<std::string, std::string>> labels;
+    if (callback && !sample->cped.IsEmpty()) {
+      HandleScope scope(isolate_);
+      v8::Local<v8::Value> cped_local = sample->cped.Get(v8_isolate);
+      callback(callback_data, cped_local, &labels);
+    }
+    samples.emplace_back(sample->owner->id_, sample->size,
+                         ScaleSample(sample->size, 1).count,
+                         sample->sample_id, std::move(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,12 @@ class SamplingHeapProfiler {
     Global<Value> global;
     SamplingHeapProfiler* const profiler;
     const uint64_t sample_id;
+    std::vector<std::pair<std::string, std::string>> labels;
+    // ContinuationPreservedEmbedderData captured at allocation time.
+    // Stored as Global to prevent GC of the AsyncContextFrame while
+    // the sample exists. Labels are resolved from this at read time
+    // (in BuildSamples) via the registered labels callback.
+    Global<Value> cped;
   };
 
   SamplingHeapProfiler(Heap* heap, StringsStorage* names, uint64_t rate,
@@ -160,7 +166,7 @@ class SamplingHeapProfiler {
 
   void SampleObject(Address soon_object, size_t size);
 
-  const std::vector<v8::AllocationProfile::Sample> BuildSamples() const;
+  const std::vector<v8::AllocationProfile::Sample> BuildSamples();
 
   AllocationNode* FindOrAddChildNode(AllocationNode* parent, const char* name,
                                      int script_id, int start_position);