feat: support multi-thread python unwind with robust fallbacks

Author: kylewanginchina

agent/crates/trace-utils/cbindgen.toml

@@ -60,7 +60,8 @@ include = [
   "LuaUnwindInfo",
   "LuaUnwindTable",
   "LuaOfs",
-  "LjOfs"
+  "LjOfs",
+  "TSDInfo"
 ]
 exclude = [
   "bpf_update_elem",
@@ -80,6 +81,7 @@ ProcessShardList = "process_shard_list_t"
 UnwindEntry = "unwind_entry_t"
 UnwindEntryShard = "unwind_entry_shard_t"
 UnwindTable = "unwind_table_t"
+TSDInfo = "tsd_info_t"
 PyCframe = "py_cframe_t"
 PyCodeObject = "py_code_object_t"
 PyFrameObject = "py_frame_object_t"

agent/crates/trace-utils/src/error.rs

@@ -37,6 +37,8 @@ pub enum Error {
     InvalidPointer(u64),
     #[error("Invalid or corrupted data")]
     InvalidData,
+    #[error("{0}")]
+    Msg(String),
 }
 
 pub type Result<T> = std::result::Result<T, Error>;

agent/crates/trace-utils/src/maps.rs

@@ -21,7 +21,7 @@ use std::path::PathBuf;
 
 use log::trace;
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct MemoryArea {
     pub m_start: u64,
     pub mx_start: u64, // start address of executable section

agent/crates/trace-utils/src/trace_utils.h

@@ -91,8 +91,41 @@ typedef struct {
 } unwind_entry_shard_t;
 
 typedef struct {
-    uint64_t thread_state_address;
+    /**
+     * Offset from thread pointer base (TPBASE) to TSD storage
+     */
+    int16_t offset;
+    /**
+     * TSD key multiplier (glibc=16, musl=8)
+     */
+    uint8_t multiplier;
+    /**
+     * Whether indirect addressing is needed (musl=1, glibc=0)
+     */
+    uint8_t indirect;
+} tsd_info_t;
+
+typedef struct {
+    /**
+     * Address of autoTLSkey variable in Python runtime
+     */
+    uint64_t auto_tls_key_addr;
+    /**
+     * Python version encoded as 0xMMmm (e.g., 0x030A for 3.10)
+     */
+    uint16_t version;
+    /**
+     * Thread Specific Data info for multi-threading support
+     */
+    tsd_info_t tsd_info;
+    /**
+     * ID for looking up python_offsets in the offsets map
+     */
     uint8_t offsets_id;
+    /**
+     * Padding for alignment
+     */
+    uint8_t _padding[5];
 } python_unwind_info_t;
 
 typedef struct {
@@ -396,6 +429,12 @@ void v8_unwind_table_unload(v8_unwind_table_t *table, uint32_t pid);
 
 int32_t read_offset_of_stack_in_task_struct(void);
 
+/**
+ * Read TPBASE offset from kernel functions
+ * Returns the offset of fsbase/tpidr in task_struct, or -1 on failure
+ */
+int64_t read_tpbase_offset(void);
+
 int rustc_demangle(const char *mangled, char *out, size_t out_size);
 
 unwind_table_t *unwind_table_create(int32_t process_shard_list_map_fd,

agent/crates/trace-utils/src/unwind.rs

@@ -19,6 +19,8 @@ pub mod elf_utils;
 pub mod lua;
 pub mod php;
 pub mod python;
+pub mod tpbase;
+pub mod tsd;
 pub mod v8;
 
 use std::alloc::{alloc, dealloc, handle_alloc_error, Layout};