Add remote symbolication support with build-id and PC offset

README.md

@@ -402,6 +402,25 @@ Improved thread-local storage initialization to prevent race conditions:
 
 These architectural improvements focus on eliminating race conditions, improving performance in high-throughput scenarios, and providing better debugging capabilities for the native profiling engine.
 
+### Remote Symbolication Support (2025)
+
+Added support for remote symbolication to enable offloading symbol resolution from the agent to backend services:
+
+- **Build-ID extraction**: Automatically extracts GNU build-id from ELF binaries on Linux
+- **Raw addressing information**: Stores build-id and PC offset instead of resolved symbol names
+- **Remote symbolication mode**: Enable with `remotesym=true` profiler argument
+- **JFR integration**: Remote frames serialized with build-id and offset for backend resolution
+- **Zero encoding overhead**: Uses dedicated frame type (FRAME_NATIVE_REMOTE) for efficient serialization
+
+**Benefits**:
+- Reduces agent overhead by eliminating local symbol resolution
+- Enables centralized symbol resolution with better caching
+- Supports scenarios where debug symbols are not available locally
+
+**Key files**: `elfBuildId.h`, `elfBuildId.cpp`, `profiler.cpp`, `flightRecorder.cpp`
+
+For detailed documentation, see [doc/REMOTE_SYMBOLICATION.md](doc/REMOTE_SYMBOLICATION.md).
+
 ## Contributing
 1. Fork the repository
 2. Create a feature branch

ddprof-lib/src/main/cpp/arguments.cpp

@@ -88,7 +88,10 @@ static const Multiplier UNIVERSAL[] = {
 //                          samples
 //     generations        - track surviving generations
 //     lightweight[=BOOL] - enable lightweight profiling - events without
-//     stacktraces (default: true) jfr                - dump events in Java
+//     stacktraces (default: true)
+//     remotesym[=BOOL]   - enable remote symbolication for native frames
+//                          (stores build-id and PC offset instead of symbol names)
+//     jfr                - dump events in Java
 //     Flight Recorder format interval=N         - sampling interval in ns
 //     (default: 10'000'000, i.e. 10 ms) jstackdepth=N      - maximum Java stack
 //     depth (default: 2048) safemode=BITS      - disable stack recovery
@@ -339,18 +342,30 @@ Error Arguments::parse(const char *args) {
         _enable_method_cleanup = true;
       }
 
-      CASE("wallsampler")
+      CASE("remotesym")
       if (value != NULL) {
         switch (value[0]) {
-        case 'j':
-          _wallclock_sampler = JVMTI;
+        case 'y': // yes
+        case 't': // true
+          _remote_symbolication = true;
           break;
-        case 'a':
         default:
-          _wallclock_sampler = ASGCT;
+          _remote_symbolication = false;
         }
       }
 
+      CASE("wallsampler")
+      if (value != NULL) {
+          switch (value[0]) {
+              case 'j':
+                  _wallclock_sampler = JVMTI;
+                  break;
+              case 'a':
+              default:
+                  _wallclock_sampler = ASGCT;
+          }
+      }
+
       DEFAULT()
       if (_unknown_arg == NULL)
         _unknown_arg = arg;

ddprof-lib/src/main/cpp/arguments.h

@@ -188,6 +188,7 @@ class Arguments {
   std::vector<std::string> _context_attributes;
   bool _lightweight;
   bool _enable_method_cleanup;
+  bool _remote_symbolication;  // Enable remote symbolication for native frames
 
   Arguments(bool persistent = false)
       : _buf(NULL),
@@ -221,7 +222,8 @@ class Arguments {
         _context_attributes({}),
         _wallclock_sampler(ASGCT),
         _lightweight(false),
-        _enable_method_cleanup(true) {}
+        _enable_method_cleanup(true),
+        _remote_symbolication(false) {}
 
   ~Arguments();
 

ddprof-lib/src/main/cpp/codeCache.cpp

@@ -37,6 +37,11 @@ CodeCache::CodeCache(const char *name, short lib_index,
   _plt_size = 0;
   _debug_symbols = false;
 
+  // Initialize build-id fields
+  _build_id = nullptr;
+  _build_id_len = 0;
+  _load_bias = 0;
+
   memset(_imports, 0, sizeof(_imports));
   _imports_patchable = imports_patchable;
 
@@ -54,10 +59,27 @@ CodeCache::CodeCache(const CodeCache &other) {
   _min_address = other._min_address;
   _max_address = other._max_address;
   _text_base = other._text_base;
+  _image_base = other._image_base;
 
-  _imports_patchable = other._imports_patchable;
   _plt_offset = other._plt_offset;
   _plt_size = other._plt_size;
+  _debug_symbols = other._debug_symbols;
+
+  // Copy build-id information
+  _build_id_len = other._build_id_len;
+  if (other._build_id != nullptr && other._build_id_len > 0) {
+    size_t hex_str_len = strlen(other._build_id);
+    _build_id = static_cast<char*>(malloc(hex_str_len + 1));
+    if (_build_id != nullptr) {
+      strcpy(_build_id, other._build_id);
+    }
+  } else {
+    _build_id = nullptr;
+  }
+  _load_bias = other._load_bias;
+
+  memset(_imports, 0, sizeof(_imports));
+  _imports_patchable = other._imports_patchable;
 
   _dwarf_table_length = other._dwarf_table_length;
   _dwarf_table = new FrameDesc[_dwarf_table_length];
@@ -77,17 +99,34 @@ CodeCache &CodeCache::operator=(const CodeCache &other) {
     delete _name;
     delete _dwarf_table;
     delete _blobs;
+    free(_build_id);  // Free existing build-id
 
     _name = NativeFunc::create(other._name, -1);
     _lib_index = other._lib_index;
     _min_address = other._min_address;
     _max_address = other._max_address;
     _text_base = other._text_base;
-
-    _imports_patchable = other._imports_patchable;
+    _image_base = other._image_base;
 
     _plt_offset = other._plt_offset;
     _plt_size = other._plt_size;
+    _debug_symbols = other._debug_symbols;
+
+    // Copy build-id information
+    _build_id_len = other._build_id_len;
+    if (other._build_id != nullptr && other._build_id_len > 0) {
+      size_t hex_str_len = strlen(other._build_id);
+      _build_id = static_cast<char*>(malloc(hex_str_len + 1));
+      if (_build_id != nullptr) {
+        strcpy(_build_id, other._build_id);
+      }
+    } else {
+      _build_id = nullptr;
+    }
+    _load_bias = other._load_bias;
+
+    memset(_imports, 0, sizeof(_imports));
+    _imports_patchable = other._imports_patchable;
 
     _dwarf_table_length = other._dwarf_table_length;
     _dwarf_table = new FrameDesc[_dwarf_table_length];
@@ -110,6 +149,7 @@ CodeCache::~CodeCache() {
   NativeFunc::destroy(_name);
   delete[] _blobs;
   delete _dwarf_table;
+  free(_build_id);  // Free build-id memory
 }
 
 void CodeCache::expand() {
@@ -387,3 +427,23 @@ FrameDesc CodeCache::findFrameDesc(const void *pc) {
     return FrameDesc::default_frame;
   }
 }
+
+void CodeCache::setBuildId(const char* build_id, size_t build_id_len) {
+  // Free existing build-id if any
+  free(_build_id);
+  _build_id = nullptr;
+  _build_id_len = 0;
+
+  if (build_id != nullptr && build_id_len > 0) {
+    // build_id is a hex string, allocate based on actual string length
+    size_t hex_str_len = strlen(build_id);
+    _build_id = static_cast<char*>(malloc(hex_str_len + 1));
+
+    if (_build_id != nullptr) {
+      // Copy the hex string
+      strcpy(_build_id, build_id);
+      // Store the original byte length (not hex string length)
+      _build_id_len = build_id_len;
+    }
+  }
+}

ddprof-lib/src/main/cpp/codeCache.h

@@ -116,6 +116,11 @@ class CodeCache {
   unsigned int _plt_offset;
   unsigned int _plt_size;
 
+  // Build-ID and load bias for remote symbolication
+  char *_build_id;           // GNU build-id (hex string, null if not available)
+  size_t _build_id_len;      // Build-id length in bytes (raw, not hex string length)
+  uintptr_t _load_bias;      // Load bias (image_base - file_base address)
+
   void **_imports[NUM_IMPORTS][NUM_IMPORT_TYPES];
   bool _imports_patchable;
   bool _debug_symbols;
@@ -169,6 +174,19 @@ class CodeCache {
 
   void setDebugSymbols(bool debug_symbols) { _debug_symbols = debug_symbols; }
 
+  // Build-ID and remote symbolication support
+  const char* buildId() const { return _build_id; }
+  size_t buildIdLen() const { return _build_id_len; }
+  bool hasBuildId() const { return _build_id != nullptr; }
+  uintptr_t loadBias() const { return _load_bias; }
+  short libIndex() const { return _lib_index; }
+
+  // Sets the build-id (hex string) and stores the original byte length
+  // build_id: null-terminated hex string (e.g., "abc123..." for 40-char string)
+  // build_id_len: original byte length before hex conversion (e.g., 20 bytes)
+  void setBuildId(const char* build_id, size_t build_id_len);
+  void setLoadBias(uintptr_t load_bias) { _load_bias = load_bias; }
+
   void add(const void *start, int length, const char *name,
            bool update_bounds = false);
   void updateBounds(const void *start, const void *end);
@@ -225,7 +243,7 @@ class CodeCacheArray {
     memset(_libs, 0, MAX_NATIVE_LIBS * sizeof(CodeCache *));
   }
 
-  CodeCache *operator[](int index) { return _libs[index]; }
+  CodeCache *operator[](int index) const { return __atomic_load_n(&_libs[index], __ATOMIC_ACQUIRE); }
 
   int count() const { return __atomic_load_n(&_count, __ATOMIC_RELAXED); }
 
@@ -247,7 +265,7 @@ class CodeCacheArray {
     return lib;
   }
 
-  size_t memoryUsage() {
+  size_t memoryUsage() const {
     return __atomic_load_n(&_used_memory, __ATOMIC_RELAXED);
   }
 };

ddprof-lib/src/main/cpp/flightRecorder.cpp

@@ -114,6 +114,25 @@ void Lookup::fillNativeMethodInfo(MethodInfo *mi, const char *name,
   }
 }
 
+void Lookup::fillRemoteFrameInfo(MethodInfo *mi, const RemoteFrameInfo *rfi) {
+  // Store build-id in the class name field
+  mi->_class = _classes->lookup(rfi->build_id);
+
+  // Store PC offset in hex format in the signature field
+  char offset_hex[32];
+  snprintf(offset_hex, sizeof(offset_hex), "0x%lx", rfi->pc_offset);
+  mi->_sig = _symbols.lookup(offset_hex);
+
+  // Use same modifiers as regular native frames (0x100 = ACC_NATIVE for consistency)
+  mi->_modifiers = 0x100;
+  // Use FRAME_NATIVE_REMOTE type to indicate remote symbolication
+  mi->_type = FRAME_NATIVE_REMOTE;
+  mi->_line_number_table = nullptr;
+
+  // Method name indicates need for remote symbolication
+  mi->_name = _symbols.lookup("<remote>");
+}
+
 void Lookup::cutArguments(char *func) {
   char *p = strrchr(func, ')');
   if (p == NULL)
@@ -322,6 +341,9 @@ MethodInfo *Lookup::resolveMethod(ASGCT_CallFrame &frame) {
       const char *name = (const char *)method;
       fillNativeMethodInfo(mi, name,
                            Profiler::instance()->getLibraryName(name));
+    } else if (frame.bci == BCI_NATIVE_FRAME_REMOTE) {
+      const RemoteFrameInfo *rfi = (const RemoteFrameInfo *)method;
+      fillRemoteFrameInfo(mi, rfi);
     } else {
       fillJavaMethodInfo(mi, method, first_time);
     }
@@ -1036,18 +1058,23 @@ void Recording::writeNativeLibraries(Buffer *buf) {
   if (_recorded_lib_count < 0)
     return;
 
-  Profiler *profiler = Profiler::instance();
-  CodeCacheArray &native_libs = profiler->_native_libs;
+  Libraries *libraries = Libraries::instance();
+  const CodeCacheArray &native_libs = libraries->native_libs();
   int native_lib_count = native_libs.count();
 
   for (int i = _recorded_lib_count; i < native_lib_count; i++) {
+    CodeCache* lib = native_libs[i];
+
+    // Emit jdk.NativeLibrary event with extended fields (buildId and loadBias)
     flushIfNeeded(buf, RECORDING_BUFFER_LIMIT - MAX_STRING_LENGTH);
     int start = buf->skip(5);
     buf->putVar64(T_NATIVE_LIBRARY);
     buf->putVar64(_start_ticks);
-    buf->putUtf8(native_libs[i]->name());
-    buf->putVar64((uintptr_t)native_libs[i]->minAddress());
-    buf->putVar64((uintptr_t)native_libs[i]->maxAddress());
+    buf->putUtf8(lib->name());
+    buf->putVar64((uintptr_t)lib->minAddress());
+    buf->putVar64((uintptr_t)lib->maxAddress());
+    buf->putUtf8(lib->hasBuildId() ? lib->buildId() : "");
+    buf->putVar64((uintptr_t)lib->loadBias());
     buf->putVar32(start, buf->offset() - start);
     flushIfNeeded(buf);
   }

ddprof-lib/src/main/cpp/flightRecorder.h

@@ -276,6 +276,7 @@ class Lookup {
 private:
   void fillNativeMethodInfo(MethodInfo *mi, const char *name,
                             const char *lib_name);
+  void fillRemoteFrameInfo(MethodInfo *mi, const RemoteFrameInfo *rfi);
   void cutArguments(char *func);
   void fillJavaMethodInfo(MethodInfo *mi, jmethodID method, bool first_time);
   bool has_prefix(const char *str, const char *prefix) const {

ddprof-lib/src/main/cpp/frame.h

@@ -9,6 +9,7 @@ enum FrameTypeId {
   FRAME_CPP = 4,
   FRAME_KERNEL = 5,
   FRAME_C1_COMPILED = 6,
+  FRAME_NATIVE_REMOTE = 7,  // Native frame with remote symbolication (build-id + pc-offset)
 };
 
 class FrameType {

ddprof-lib/src/main/cpp/jfrMetadata.cpp

@@ -323,7 +323,9 @@ void JfrMetadata::initialize(
               << field("startTime", T_LONG, "Start Time", F_TIME_TICKS)
               << field("name", T_STRING, "Name")
               << field("baseAddress", T_LONG, "Base Address", F_ADDRESS)
-              << field("topAddress", T_LONG, "Top Address", F_ADDRESS))
+              << field("topAddress", T_LONG, "Top Address", F_ADDRESS)
+              << field("buildId", T_STRING, "GNU Build ID")
+              << field("loadBias", T_LONG, "Load Bias", F_ADDRESS))
 
           << (type("profiler.Log", T_LOG, "Log Message")
               << category("Profiler")