feat: extract symbols from separate debug files via .gnu_debuglink

Move find_debug_file to elf_helper.rs so it can be shared, and use it
in ModuleSymbols::from_elf to merge symbols from the .debug file when
the main binary has an incomplete symbol table (e.g. only .dynsym).

This fixes "Unknown symbol" entries in flamegraphs for internal
functions in stripped system libraries like ld-linux, where the full
.symtab is only available in the debug package.

Author: not-matthias

src/executor/wall_time/perf/debug_info.rs

@@ -1,3 +1,4 @@
+use super::elf_helper::find_debug_file;
 use super::parse_perf_file::LoadedModule;
 use crate::executor::wall_time::perf::module_symbols::ModuleSymbols;
 use crate::prelude::*;
@@ -11,41 +12,6 @@ use std::path::PathBuf;
 
 type EndianRcSlice = gimli::EndianRcSlice<gimli::RunTimeEndian>;
 
-/// Search for a separate debug info file using `.gnu_debuglink`.
-///
-/// Follows the standard GDB search order:
-/// 1. `<binary_dir>/<debuglink>`
-/// 2. `<binary_dir>/.debug/<debuglink>`
-/// 3. `/usr/lib/debug/<binary_dir>/<debuglink>`
-fn find_debug_file(object: &object::File, binary_path: &Path) -> Option<PathBuf> {
-    let (debuglink, expected_crc) = object.gnu_debuglink().ok()??;
-    let debuglink = std::str::from_utf8(debuglink).ok()?;
-    let dir = binary_path.parent()?;
-
-    let candidates = [
-        dir.join(debuglink),
-        dir.join(".debug").join(debuglink),
-        Path::new("/usr/lib/debug")
-            .join(dir.strip_prefix("/").unwrap_or(dir))
-            .join(debuglink),
-    ];
-
-    candidates.into_iter().find(|p| {
-        let Ok(content) = std::fs::read(p) else {
-            return false;
-        };
-        let actual_crc = crc32fast::hash(&content);
-        if actual_crc != expected_crc {
-            trace!(
-                "CRC mismatch for {}: expected {expected_crc:#x}, got {actual_crc:#x}",
-                p.display()
-            );
-            return false;
-        }
-        true
-    })
-}
-
 pub trait ModuleDebugInfoExt {
     fn from_symbols<P: AsRef<Path>>(
         path: P,

src/executor/wall_time/perf/elf_helper.rs

@@ -1,8 +1,10 @@
 //! Based on this: https://github.com/mstange/samply/blob/4a5afec57b7c68b37ecde12b5a258de523e89463/samply/src/linux_shared/svma_file_range.rs#L8
 
 use anyhow::Context;
+use log::trace;
 use object::Object;
 use object::ObjectSegment;
+use std::path::{Path, PathBuf};
 
 // A file range in an object file, such as a segment or a section,
 // for which we know the corresponding Stated Virtual Memory Address (SVMA).
@@ -188,3 +190,40 @@ pub fn relative_address_base(object_file: &object::File) -> u64 {
 pub fn compute_base_avma(base_svma: u64, load_bias: u64) -> u64 {
     base_svma.wrapping_add(load_bias)
 }
+
+/// Search for a separate debug info file using `.gnu_debuglink`.
+///
+/// Follows the standard GDB search order:
+/// 1. `<binary_dir>/<debuglink>`
+/// 2. `<binary_dir>/.debug/<debuglink>`
+/// 3. `/usr/lib/debug/<binary_dir>/<debuglink>`
+///
+/// Validates the CRC32 checksum to avoid using stale debug files.
+pub fn find_debug_file(object: &object::File, binary_path: &Path) -> Option<PathBuf> {
+    let (debuglink, expected_crc) = object.gnu_debuglink().ok()??;
+    let debuglink = std::str::from_utf8(debuglink).ok()?;
+    let dir = binary_path.parent()?;
+
+    let candidates = [
+        dir.join(debuglink),
+        dir.join(".debug").join(debuglink),
+        Path::new("/usr/lib/debug")
+            .join(dir.strip_prefix("/").unwrap_or(dir))
+            .join(debuglink),
+    ];
+
+    candidates.into_iter().find(|p| {
+        let Ok(content) = std::fs::read(p) else {
+            return false;
+        };
+        let actual_crc = crc32fast::hash(&content);
+        if actual_crc != expected_crc {
+            trace!(
+                "CRC mismatch for {}: expected {expected_crc:#x}, got {actual_crc:#x}",
+                p.display()
+            );
+            return false;
+        }
+        true
+    })
+}

src/executor/wall_time/perf/module_symbols.rs

@@ -1,7 +1,9 @@
 use crate::executor::wall_time::perf::elf_helper;
+use log::trace;
 use object::{Object, ObjectSymbol, ObjectSymbolTable};
 use runner_shared::module_symbols::SYMBOLS_MAP_SUFFIX;
 use std::{
+    collections::HashSet,
     fmt::Debug,
     io::{BufWriter, Write},
     path::Path,
@@ -55,11 +57,8 @@ impl ModuleSymbols {
         )
     }
 
-    /// Extract symbols from an ELF file (pid-agnostic, load_bias = 0).
-    pub fn from_elf<P: AsRef<Path>>(path: P) -> anyhow::Result<Self> {
-        let content = std::fs::read(path.as_ref())?;
-        let object = object::File::parse(&*content)?;
-
+    /// Extract raw symbols from an object file's `.symtab` and `.dynsym` tables.
+    fn extract_symbols_from_object(object: &object::File) -> Vec<Symbol> {
         let mut symbols = Vec::new();
 
         if let Some(symbol_table) = object.symbol_table() {
@@ -82,6 +81,44 @@ impl ModuleSymbols {
             }));
         }
 
+        symbols
+    }
+
+    /// Extract symbols from an ELF file (pid-agnostic, load_bias = 0).
+    ///
+    /// If the binary has a `.gnu_debuglink` pointing to a separate debug file,
+    /// symbols from that file are merged in. This provides full symbol coverage
+    /// for stripped system libraries when debug packages are installed.
+    pub fn from_elf<P: AsRef<Path>>(path: P) -> anyhow::Result<Self> {
+        let content = std::fs::read(path.as_ref())?;
+        let object = object::File::parse(&*content)?;
+
+        let mut symbols = Self::extract_symbols_from_object(&object);
+
+        // Merge symbols from a separate debug file if available
+        if let Some(debug_path) = elf_helper::find_debug_file(&object, path.as_ref()) {
+            trace!(
+                "Merging symbols from debug file {:?} for {:?}",
+                debug_path,
+                path.as_ref()
+            );
+            let debug_symbols = std::fs::read(&debug_path).ok().and_then(|c| {
+                object::File::parse(&*c)
+                    .ok()
+                    .map(|o| Self::extract_symbols_from_object(&o))
+            });
+
+            if let Some(debug_symbols) = debug_symbols {
+                let existing: HashSet<(u64, String)> =
+                    symbols.iter().map(|s| (s.addr, s.name.clone())).collect();
+                symbols.extend(
+                    debug_symbols
+                        .into_iter()
+                        .filter(|s| !existing.contains(&(s.addr, s.name.clone()))),
+                );
+            }
+        }
+
         // Filter out
         //  - ARM ELF "mapping symbols" (https://github.com/torvalds/linux/blob/9448598b22c50c8a5bb77a9103e2d49f134c9578/tools/perf/util/symbol-elf.c#L1591C1-L1598C4)
         //  - symbols that have en empty name
@@ -227,4 +264,20 @@ mod tests {
         let module_symbols = ModuleSymbols::from_elf(MODULE_PATH).unwrap();
         insta::assert_debug_snapshot!(module_symbols);
     }
+
+    #[test]
+    fn test_stripped_binary_merges_debug_file_symbols() {
+        // The stripped binary has only .dynsym, the .debug file has the full .symtab.
+        // from_elf should merge both via .gnu_debuglink.
+        let stripped_only =
+            ModuleSymbols::from_elf("testdata/perf_map/cpp_my_benchmark_stripped.bin").unwrap();
+        let full = ModuleSymbols::from_elf("testdata/perf_map/cpp_my_benchmark.bin").unwrap();
+
+        assert!(
+            stripped_only.symbols().len() == full.symbols().len(),
+            "stripped+debug ({}) should have the same number of symbols as the original ({})",
+            stripped_only.symbols().len(),
+            full.symbols().len(),
+        );
+    }
 }