Add AsyncLocalStorage/ContinuationPreservedEmbedderData-based CLs.

Introduce custom labels stored in Node's AsyncLocalStorage. We require
that Node use its async_context_frame strategy for storing and
propagating this data (which is the default beginning in Node v24, and
requires the --experimental-async-context-frame flag in v22 and
v23). This strategy works by storing the stored value in v8's
ContinuationPreservedEmbedderData, which causes the runtime itself to
handle propagation. We refuse to use the previous default
AsyncLocalStorage propagation strategy, which is basically similar to
our prior approach, which was rejected due to being too slow.

The internal v8 data structures we walk are explained in the comment
on maybe_add_node_custom_labels.

Author: umanwizard

interpreter/customlabels/customlabels.go

@@ -16,14 +16,22 @@ import (
 const (
 	abiVersionExport    = "custom_labels_abi_version"
 	currentSetTlsExport = "custom_labels_current_set"
+
+	alsIdentityHashExport = "custom_labels_als_identity_hash"
+	alsHandleExport       = "custom_labels_als_handle"
 )
 
 var dsoRegex = regexp.MustCompile(`.*/libcustomlabels.*\.so`)
+var nodeRegex = regexp.MustCompile(`.*/customlabels\.node`)
 
 type data struct {
 	abiVersionElfVA   libpf.Address
 	currentSetTlsAddr libpf.Address
 
+	hasAlsData          bool
+	alsIdentityHashAddr libpf.Address
+	alsHandleAddr       libpf.Address
+
 	isSharedLibrary bool
 }
 
@@ -53,9 +61,13 @@ func Loader(_ interpreter.EbpfHandler, info *interpreter.LoaderInfo) (interprete
 	// symbol.
 	fn := info.FileName()
 	isNativeSharedLibrary := dsoRegex.MatchString(fn)
+	isNodeExtension := (!isNativeSharedLibrary) && nodeRegex.MatchString(fn)
+	isSharedLibrary := isNativeSharedLibrary || isNodeExtension
 
 	var currentSetTlsAddr libpf.Address
-	if isNativeSharedLibrary {
+	var alsIdentityHashAddr, alsHandleAddr libpf.Address
+	var hasAlsId, hasAlsData bool
+	if isSharedLibrary {
 		// Resolve thread info TLS export.
 		tlsDescs, err := ef.TLSDescriptors()
 		if err != nil {
@@ -66,6 +78,12 @@ func Loader(_ interpreter.EbpfHandler, info *interpreter.LoaderInfo) (interprete
 		if !ok {
 			return nil, errors.New("failed to locate TLS descriptor for custom labels")
 		}
+		if isNodeExtension {
+			alsIdentityHashAddr, hasAlsId = tlsDescs[alsIdentityHashExport]
+			if hasAlsId {
+				alsHandleAddr, hasAlsData = tlsDescs[alsHandleExport]
+			}
+		}
 	} else {
 		offset, err := ef.LookupTLSSymbolOffset(currentSetTlsExport)
 		if err != nil {
@@ -75,9 +93,12 @@ func Loader(_ interpreter.EbpfHandler, info *interpreter.LoaderInfo) (interprete
 	}
 
 	d := data{
-		abiVersionElfVA:   libpf.Address(abiVersionSym.Address),
-		currentSetTlsAddr: currentSetTlsAddr,
-		isSharedLibrary:   isNativeSharedLibrary,
+		abiVersionElfVA:     libpf.Address(abiVersionSym.Address),
+		currentSetTlsAddr:   currentSetTlsAddr,
+		isSharedLibrary:     isSharedLibrary,
+		hasAlsData:          hasAlsData,
+		alsIdentityHashAddr: alsIdentityHashAddr,
+		alsHandleAddr:       alsHandleAddr,
 	}
 	return &d, nil
 }
@@ -107,8 +128,18 @@ func (d data) Attach(ebpf interpreter.EbpfHandler, pid libpf.PID,
 		currentSetTlsOffset = uint64(d.currentSetTlsAddr)
 	}
 
+	var alsIdentityHashTlsOffset, alsHandleTlsOffset uint64
+	if d.hasAlsData {
+		alsIdentityHashTlsOffset = rm.Uint64(bias + d.alsIdentityHashAddr + 8)
+		alsHandleTlsOffset = rm.Uint64(bias + d.alsHandleAddr + 8)
+	}
+
 	procInfo := support.NativeCustomLabelsProcInfo{
-		Set_tls_offset: currentSetTlsOffset,
+		Current_set_tls_offset: currentSetTlsOffset,
+
+		Has_als_data:                 d.hasAlsData,
+		Als_identity_hash_tls_offset: alsIdentityHashTlsOffset,
+		Als_handle_tls_offset:        alsHandleTlsOffset,
 	}
 	if err := ebpf.UpdateProcData(libpf.CustomLabels, pid, unsafe.Pointer(&procInfo)); err != nil {
 		return nil, err

interpreter/customlabels/integrationtests/node_test.go

@@ -63,7 +63,6 @@ func TestIntegration(t *testing.T) {
 		// is on v25 by then.
 		"latest",
 		"22.19.0",
-		"20.19.5",
 	} {
 		name := "node-" + nodeVersion
 		t.Run(name, func(t *testing.T) {

interpreter/customlabels/integrationtests/testdata/node-md-render/Dockerfile

@@ -1,4 +1,4 @@
-ARG NODE_VERSION=20
+ARG NODE_VERSION=22
 FROM node:${NODE_VERSION}
 
 # Install build dependencies for native modules
@@ -25,5 +25,9 @@ COPY *.js ./
 # Expose ports for app and gdbserver
 EXPOSE 80
 
-# Start the application
-CMD ["node", "index.js"]
+# Start the application with conditional flag for Node < 24
+CMD if [ $(node -v | cut -c2- | cut -d. -f1) -lt 24 ]; then \
+        exec node --experimental-async-context-frame index.js; \
+    else \
+        exec node index.js; \
+    fi

interpreter/customlabels/integrationtests/testdata/node-md-render/package.json

@@ -9,7 +9,7 @@
   "author": "The Parca Authors",
   "license": "Apache-2.0",
   "dependencies": {
-    "@polarsignals/custom-labels": "^0.2.0",
+    "@polarsignals/custom-labels": "^0.3.2",
     "marked": "^16.1.2"
   }
 }

interpreter/nodev8/v8.go

@@ -154,6 +154,7 @@ package nodev8 // import "go.opentelemetry.io/ebpf-profiler/interpreter/nodev8"
 
 import (
 	"bytes"
+	"encoding/binary"
 	"errors"
 	"fmt"
 	"io"
@@ -480,6 +481,17 @@ type v8Data struct {
 
 	// frametypeToName caches frametype's name
 	frametypeToName [MaxFrameType]libpf.String
+
+	// isolateSym is the symbol of the v8 thread-local current isolate
+	isolateSym libpf.Address
+
+	// cpedOffset is the offset of continuation_preserved_embedder_data_ in
+	// the isolate data.
+	cpedOffset uint32
+
+	// wrappedObjectOffset is the offset of a wrapped (via ObjectWrap) C++ object
+	// in the corresponding JS object.
+	wrappedObjectOffset uint32
 }
 
 type v8Instance struct {
@@ -1782,6 +1794,9 @@ func (d *v8Data) Attach(ebpf interpreter.EbpfHandler, pid libpf.PID, _ libpf.Add
 		Codekind_shift:        vms.CodeKind.FieldShift,
 		Codekind_mask:         uint8(vms.CodeKind.FieldMask),
 		Codekind_baseline:     vms.CodeKind.Baseline,
+		Isolate_sym:           uint64(d.isolateSym),
+		Cped_offset:           d.cpedOffset,
+		Wrapped_object_offset: d.wrappedObjectOffset,
 	}
 	if err := ebpf.UpdateProcData(libpf.V8, pid, unsafe.Pointer(&data)); err != nil {
 		return nil, err
@@ -2079,6 +2094,52 @@ func (d *v8Data) readIntrospectionData(ef *pfelf.File) error {
 	return nil
 }
 
+// loadNodeClData loads various offsets that are needed for custom labels handling.
+func (d *v8Data) loadNodeClData(ef *pfelf.File) error {
+	offset, err := ef.LookupTLSSymbolOffset("_ZN2v88internal18g_current_isolate_E")
+	if err != nil {
+		return err
+	}
+	d.isolateSym = libpf.Address(offset)
+
+	syms, err := ef.ReadSymbols()
+	if err != nil {
+		return fmt.Errorf("failed to read symbols: %w", err)
+	}
+
+	sym, err := syms.LookupSymbol("_ZZ21napi_get_node_versionE7version")
+	if err != nil {
+		return fmt.Errorf("failed to lookup Node version symbol: %w", err)
+	}
+
+	if sym == nil {
+		return errors.New("Node version symbol not found")
+	}
+
+	if sym.Size < 12 {
+		return fmt.Errorf("Node version symbol size too small: %d", sym.Size)
+	}
+
+	versBuf := make([]byte, 12)
+	if _, err = ef.ReadVirtualMemory(versBuf, int64(sym.Address)); err != nil {
+		return fmt.Errorf("failed to read Node version data: %w", err)
+	}
+
+	major := binary.LittleEndian.Uint32(versBuf[0:4])
+
+	if major >= 22 {
+		if major < 24 {
+			d.cpedOffset = 576
+			d.wrappedObjectOffset = 24
+		} else {
+			d.cpedOffset = 632
+			d.wrappedObjectOffset = 32
+		}
+		return nil
+	}
+	return fmt.Errorf("Unsupported Node major version: %d", major)
+}
+
 func Loader(ebpf interpreter.EbpfHandler, info *interpreter.LoaderInfo) (interpreter.Data, error) {
 	if !v8Regex.MatchString(info.FileName()) {
 		return nil, nil
@@ -2147,6 +2208,10 @@ func Loader(ebpf interpreter.EbpfHandler, info *interpreter.LoaderInfo) (interpr
 		}
 	}
 
+	if err = d.loadNodeClData(ef); err != nil {
+		log.Warnf("Failed to load extra data for Node.js custom labels handling: %v", err)
+	}
+
 	// load introspection data
 	if err = d.readIntrospectionData(ef); err != nil {
 		return nil, err

metrics/ids.go

@@ -2093,11 +2093,32 @@
     "field": "bpf.luajit.errors.no_proc_info",
     "id": 290
   },
+  {
+    "description": "Number of attempts to read Node.js custom labels",
+    "type": "counter",
+    "name": "UnwindNodeCustomLabelsAttempts",
+    "field": "bpf.node_custom_labels.attempts",
+    "id": 291
+  },
+  {
+    "description": "Number of successful reads of Node.js custom labels",
+    "type": "counter",
+    "name": "UnwindNodeCustomLabelsSuccesses",
+    "field": "bpf.node_custom_labels.successes",
+    "id": 292
+  },
+  {
+    "description": "Number of failed attempts to read Node.js custom labels",
+    "type": "counter",
+    "name": "UnwindNodeCustomLabelsFailures",
+    "field": "bpf.node_custom_labels.failures",
+    "id": 293
+  },
   {
     "description": "Number of times rtld:map_complete USDT probe was fired",
     "type": "counter",
     "name": "RtldMapCompleteHits",
     "field": "bpf.rtld.map_complete_hits",
-    "id": 291
+    "id": 294
   }
 ]