feat: resolve debug info from separate .debug files via .gnu_debuglink

When a binary has no embedded DWARF sections (e.g. stripped system
libraries like libc.so.6), fall back to searching for a separate debug
file using the .gnu_debuglink section. This follows the standard GDB
search order: same directory, .debug/ subdirectory, and
/usr/lib/debug/<path>/.

The debug file is validated with a CRC32 check to avoid silently using
stale or mismatched debug files after binary upgrades.

This means installing debug symbol packages (e.g. apt install libc6-dbg)
now actually works — the runner picks up the separate .debug file and
resolves file/line info for libc frames in flamegraphs.

Author: not-matthias

Cargo.lock

@@ -73,6 +73,7 @@ shell-words = "1.1.0"
 rmp-serde = "1.3.0"
 uuid = { version = "1.21.0", features = ["v4"] }
 which = "8.0.2"
+crc32fast = "1.5.0"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 procfs = "0.17.0"

Cargo.toml

@@ -11,6 +11,41 @@ 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,
@@ -43,7 +78,10 @@ pub trait ModuleDebugInfoExt {
 }
 
 impl ModuleDebugInfoExt for ModuleDebugInfo {
-    /// Create debug info from existing symbols by looking up file/line in DWARF
+    /// Create debug info from existing symbols by looking up file/line in DWARF.
+    ///
+    /// If the binary has no DWARF sections, tries to find a separate debug file
+    /// via `.gnu_debuglink` (e.g. installed by `libc6-dbg`).
     fn from_symbols<P: AsRef<Path>>(
         path: P,
         symbols: &ModuleSymbols,
@@ -52,7 +90,25 @@ impl ModuleDebugInfoExt for ModuleDebugInfo {
         let content = std::fs::read(path.as_ref())?;
         let object = object::File::parse(&*content)?;
 
-        let ctx = Self::create_dwarf_context(&object).context("Failed to create DWARF context")?;
+        // If the binary has no DWARF, try a separate debug file via .gnu_debuglink
+        let ctx = if object.section_by_name(".debug_info").is_some() {
+            Self::create_dwarf_context(&object).context("Failed to create DWARF context")?
+        } else {
+            let debug_path = find_debug_file(&object, path.as_ref()).with_context(|| {
+                format!(
+                    "No DWARF in {:?} and no separate debug file found",
+                    path.as_ref()
+                )
+            })?;
+            trace!(
+                "Using separate debug file {debug_path:?} for {:?}",
+                path.as_ref()
+            );
+            let debug_content = std::fs::read(&debug_path)?;
+            let debug_object = object::File::parse(&*debug_content)?;
+            Self::create_dwarf_context(&debug_object)
+                .context("Failed to create DWARF context from debug file")?
+        };
         let (mut min_addr, mut max_addr) = (None, None);
         let debug_infos = symbols
             .symbols()
@@ -213,6 +269,29 @@ mod tests {
         insta::assert_debug_snapshot!(module_debug_info.debug_infos);
     }
 
+    #[test]
+    fn test_stripped_binary_with_debuglink_resolves_debug_info() {
+        // Mimics the libc + libc6-dbg scenario:
+        // - cpp_my_benchmark_stripped.bin has symbols but no DWARF,
+        //   with a .gnu_debuglink pointing to cpp_my_benchmark.debug
+        // - cpp_my_benchmark.debug has the DWARF sections
+        const MODULE_PATH: &str = "testdata/perf_map/cpp_my_benchmark_stripped.bin";
+
+        let module_symbols = ModuleSymbols::from_elf(MODULE_PATH).unwrap();
+        assert!(
+            !module_symbols.symbols().is_empty(),
+            "symbols should load from .symtab"
+        );
+
+        // Should succeed by following .gnu_debuglink to the .debug file
+        let module_debug_info =
+            ModuleDebugInfo::from_symbols(MODULE_PATH, &module_symbols, 0).unwrap();
+        assert!(
+            !module_debug_info.debug_infos.is_empty(),
+            "should have resolved debug info from separate .debug file"
+        );
+    }
+
     #[test]
     fn test_ruff_debug_info() {
         const MODULE_PATH: &str = "testdata/perf_map/ty_walltime";