feat: add eBPF map configuration with unified CompileOptions

Author: swananan

config.toml

@@ -96,3 +96,26 @@ output_dir = "."
 # Default filename prefix for auto-generated realtime log files
 # Default: "ghostscope_session"
 filename_prefix = "ghostscope_session"
+
+[ebpf]
+# RingBuf map size in bytes (must be power of 2)
+# This controls the size of the ring buffer used to transfer trace events from kernel to userspace.
+# Larger sizes allow more events to be buffered but consume more kernel memory.
+# Valid range: 4096 (4KB) to 16777216 (16MB)
+# Recommended values:
+#   - Low-frequency tracing: 131072 (128KB)
+#   - Medium-frequency tracing: 262144 (256KB)
+#   - High-frequency tracing: 524288 (512KB) or 1048576 (1MB)
+# Default: 262144 (256KB)
+ringbuf_size = 262144
+
+# Maximum number of (pid, module) offset entries for ASLR translation
+# This map stores the runtime address offsets for each loaded module in each process.
+# Each entry stores offsets for text/rodata/data/bss sections.
+# Valid range: 64 to 65536
+# Recommended values:
+#   - Single process: 1024
+#   - Multi-process: 4096
+#   - System-wide tracing: 8192 or 16384
+# Default: 4096
+proc_module_offsets_max_entries = 4096

docs/configuration.md

@@ -206,6 +206,27 @@ enabled = true
 
 # Maximum history entries
 max_entries = 5000
+
+[ebpf]
+# RingBuf map size in bytes (must be power of 2)
+# Controls the size of the ring buffer for transferring trace events from kernel to userspace
+# Valid range: 4096 (4KB) to 16777216 (16MB)
+ringbuf_size = 262144  # 256KB (default)
+
+# Recommended values:
+#   - Low-frequency tracing: 131072 (128KB)
+#   - Medium-frequency tracing: 262144 (256KB)
+#   - High-frequency tracing: 524288 (512KB) or 1048576 (1MB)
+
+# Maximum number of (pid, module) offset entries for ASLR translation
+# Stores runtime address offsets for each loaded module in each process
+# Valid range: 64 to 65536
+proc_module_offsets_max_entries = 4096  # Default
+
+# Recommended values:
+#   - Single process: 1024
+#   - Multi-process: 4096
+#   - System-wide tracing: 8192 or 16384
 ```
 
 ### Configuration Examples
@@ -261,6 +282,40 @@ enabled = true
 max_entries = 10000
 ```
 
+#### High-Frequency Tracing Configuration
+
+```toml
+# Optimized for high-frequency event tracing
+[ebpf]
+ringbuf_size = 1048576  # 1MB buffer for high event rates
+proc_module_offsets_max_entries = 8192  # Support many modules
+
+[general]
+log_level = "info"  # Reduce logging overhead
+enable_console_logging = false
+```
+
+#### Low-Overhead Configuration
+
+```toml
+# Minimal resource usage for production
+[ebpf]
+ringbuf_size = 131072  # 128KB minimal buffer
+proc_module_offsets_max_entries = 1024  # Single process only
+
+[general]
+log_level = "error"
+enable_logging = false
+
+[files]
+[files.save_llvm_ir]
+debug = false
+release = false
+[files.save_ebpf]
+debug = false
+release = false
+```
+
 ## Environment Variables
 
 ### RUST_LOG
@@ -337,6 +392,9 @@ GhostScope validates configuration at startup:
 4. **Panel Ratios**: Ensures all 3 values are positive (non-zero) integers
 5. **Log Level**: Validates against allowed values (error, warn, info, debug, trace)
 6. **Layout Mode**: Validates against allowed values (Horizontal, Vertical - capitalized)
+7. **eBPF Configuration**:
+   - **ringbuf_size**: Must be power of 2, range 4096-16777216 bytes
+   - **proc_module_offsets_max_entries**: Must be in range 64-65536
 
 Invalid configuration will produce clear error messages with suggestions for fixes.
 
@@ -346,11 +404,19 @@ Invalid configuration will produce clear error messages with suggestions for fix
 - **"Target file does not exist"**: Specified target path not found. Check the file path.
 - **"Script file does not exist"**: Specified script file not found.
 - **"Invalid log level"**: Use one of: error, warn, info, debug, trace.
+- **"ringbuf_size must be a power of 2"**: Use values like 131072, 262144, 524288, etc.
+- **"ringbuf_size X is out of reasonable range"**: Must be between 4KB and 16MB.
+- **"proc_module_offsets_max_entries X is out of reasonable range"**: Must be between 64 and 65536.
 
 ## Best Practices
 
 1. **Use Configuration Files**: Store common settings in `~/.ghostscope/config.toml`
 2. **Environment-Specific Configs**: Keep separate configs for development and production
 3. **Log Rotation**: Configure external log rotation for long-running sessions
 4. **Debug Output**: Disable debug file saving in production for performance
-5. **Panel Layout**: Use horizontal layout for wide screens, vertical for narrow displays
+5. **Panel Layout**: Use horizontal layout for wide screens, vertical for narrow displays
+6. **eBPF Tuning**:
+   - Start with default `ringbuf_size` (256KB) and increase if events are dropped
+   - Monitor kernel memory usage when using large ringbuf sizes
+   - Use smaller `proc_module_offsets_max_entries` for single-process debugging
+   - Increase buffer size for high-frequency tracing scenarios

docs/zh/configuration.md

@@ -206,6 +206,27 @@ enabled = true
 
 # 最大历史条目数
 max_entries = 5000
+
+[ebpf]
+# RingBuf map 大小（字节，必须是 2 的幂）
+# 控制从内核向用户空间传输跟踪事件的环形缓冲区大小
+# 有效范围：4096 (4KB) 到 16777216 (16MB)
+ringbuf_size = 262144  # 256KB（默认）
+
+# 推荐值：
+#   - 低频跟踪：131072 (128KB)
+#   - 中频跟踪：262144 (256KB)
+#   - 高频跟踪：524288 (512KB) 或 1048576 (1MB)
+
+# ASLR 地址转换的 (pid, module) 偏移条目最大数量
+# 存储每个进程中每个加载模块的运行时地址偏移
+# 有效范围：64 到 65536
+proc_module_offsets_max_entries = 4096  # 默认
+
+# 推荐值：
+#   - 单进程：1024
+#   - 多进程：4096
+#   - 系统级跟踪：8192 或 16384
 ```
 
 ### 配置示例
@@ -261,6 +282,40 @@ enabled = true
 max_entries = 10000
 ```
 
+#### 高频跟踪配置
+
+```toml
+# 针对高频事件跟踪优化
+[ebpf]
+ringbuf_size = 1048576  # 1MB 缓冲区用于高事件率
+proc_module_offsets_max_entries = 8192  # 支持更多模块
+
+[general]
+log_level = "info"  # 降低日志开销
+enable_console_logging = false
+```
+
+#### 低开销配置
+
+```toml
+# 生产环境最小资源占用
+[ebpf]
+ringbuf_size = 131072  # 128KB 最小缓冲区
+proc_module_offsets_max_entries = 1024  # 仅单进程
+
+[general]
+log_level = "error"
+enable_logging = false
+
+[files]
+[files.save_llvm_ir]
+debug = false
+release = false
+[files.save_ebpf]
+debug = false
+release = false
+```
+
 ## 环境变量
 
 ### RUST_LOG
@@ -337,6 +392,9 @@ GhostScope 在启动时验证配置：
 4. **面板比例**：确保所有 3 个值都是正（非零）整数
 5. **日志级别**：验证是否为允许的值（error, warn, info, debug, trace）
 6. **布局模式**：验证是否为允许的值（Horizontal, Vertical - 首字母大写）
+7. **eBPF 配置**：
+   - **ringbuf_size**：必须是 2 的幂，范围 4096-16777216 字节
+   - **proc_module_offsets_max_entries**：必须在 64-65536 范围内
 
 无效配置将产生清晰的错误消息和修复建议。
 
@@ -346,6 +404,9 @@ GhostScope 在启动时验证配置：
 - **"Target file does not exist"**：未找到指定的目标路径。检查文件路径。
 - **"Script file does not exist"**：未找到指定的脚本文件。
 - **"Invalid log level"**：使用以下之一：error, warn, info, debug, trace。
+- **"ringbuf_size must be a power of 2"**：使用 2 的幂值，如 131072、262144、524288 等。
+- **"ringbuf_size X is out of reasonable range"**：必须在 4KB 到 16MB 之间。
+- **"proc_module_offsets_max_entries X is out of reasonable range"**：必须在 64 到 65536 之间。
 
 ## 最佳实践
 
@@ -354,3 +415,8 @@ GhostScope 在启动时验证配置：
 3. **日志轮转**：为长时间运行的会话配置外部日志轮转
 4. **调试输出**：在生产环境中禁用调试文件保存以提高性能
 5. **面板布局**：宽屏使用水平布局，窄屏使用垂直布局
+6. **eBPF 调优**：
+   - 从默认 `ringbuf_size`（256KB）开始，如果事件丢失则增加
+   - 使用大缓冲区时监控内核内存使用情况
+   - 单进程调试时使用较小的 `proc_module_offsets_max_entries`
+   - 高频跟踪场景下增加缓冲区大小

ghostscope-compiler/src/ebpf/context.rs

@@ -90,14 +90,22 @@ pub struct EbpfContext<'ctx> {
 
     // Per-invocation stack key for proc_module_offsets lookups (allocated in entry block)
     pub pm_key_alloca: Option<inkwell::values::PointerValue<'ctx>>, // [3 x i32] alloca
+
+    // Compilation options (includes eBPF map configuration)
+    pub compile_options: crate::CompileOptions,
 }
 
 // Temporary alias for backward compatibility during refactoring
 pub type NewCodeGen<'ctx> = EbpfContext<'ctx>;
 
 impl<'ctx> EbpfContext<'ctx> {
     /// Create a new eBPF code generation context
-    pub fn new(context: &'ctx Context, module_name: &str, trace_id: Option<u32>) -> Result<Self> {
+    pub fn new(
+        context: &'ctx Context,
+        module_name: &str,
+        trace_id: Option<u32>,
+        compile_options: &crate::CompileOptions,
+    ) -> Result<Self> {
         let module = context.create_module(module_name);
         let builder = context.create_builder();
 
@@ -177,6 +185,7 @@ impl<'ctx> EbpfContext<'ctx> {
             trace_context: ghostscope_protocol::TraceContext::new(),
             current_resolved_var_module_path: None,
             pm_key_alloca: None,
+            compile_options: compile_options.clone(),
         })
     }
 
@@ -186,8 +195,9 @@ impl<'ctx> EbpfContext<'ctx> {
         module_name: &str,
         process_analyzer: Option<&mut DwarfAnalyzer>,
         trace_id: Option<u32>,
+        compile_options: &crate::CompileOptions,
     ) -> Result<Self> {
-        let mut codegen = Self::new(context, module_name, trace_id)?;
+        let mut codegen = Self::new(context, module_name, trace_id, compile_options)?;
         codegen.process_analyzer = process_analyzer.map(|pa| pa as *const _ as *mut _);
         Ok(codegen)
     }
@@ -302,13 +312,14 @@ impl<'ctx> EbpfContext<'ctx> {
             };
 
         // Create required maps - critical for eBPF loader
+        // Use configured ringbuf size directly (in bytes)
         self.map_manager
             .create_ringbuf_map(
                 &self.module,
                 &self.di_builder,
                 &self.compile_unit,
                 "ringbuf",
-                8,
+                self.compile_options.ringbuf_size,
             )
             .map_err(|e| CodeGenError::LLVMError(format!("Failed to create ringbuf map: {e}")))?;
 
@@ -319,7 +330,7 @@ impl<'ctx> EbpfContext<'ctx> {
                 &self.di_builder,
                 &self.compile_unit,
                 "proc_module_offsets",
-                4096,
+                self.compile_options.proc_module_offsets_max_entries,
             )
             .map_err(|e| {
                 CodeGenError::LLVMError(format!("Failed to create proc_module_offsets map: {e}"))

ghostscope-compiler/src/ebpf/maps.rs

@@ -124,21 +124,42 @@ impl<'ctx> MapManager<'ctx> {
         };
         let max_entries_u32 = max_entries.min(u32::MAX as u64) as u32;
 
-        // Create a simple struct with basic map definition layout
-        // Use the standard 4-field layout that most eBPF maps use
-        let elements = vec![
-            i32_type.into(), // type (map type)
-            i32_type.into(), // key_size
-            i32_type.into(), // value_size
-            i32_type.into(), // max_entries
-        ];
+        // Create struct with appropriate fields based on map type
+        // Ringbuf only needs type and max_entries, others need all 4 fields
+        let (elements, initializer_values): (Vec<_>, Vec<_>) = match map_type {
+            BpfMapType::Ringbuf => {
+                // Ringbuf: only type and max_entries
+                (
+                    vec![
+                        i32_type.into(), // type
+                        i32_type.into(), // max_entries
+                    ],
+                    vec![
+                        i32_type.const_int(map_type_id as u64, false).into(),
+                        i32_type.const_int(max_entries_u32 as u64, false).into(),
+                    ],
+                )
+            }
+            _ => {
+                // Other maps: type, key_size, value_size, max_entries
+                (
+                    vec![
+                        i32_type.into(), // type
+                        i32_type.into(), // key_size
+                        i32_type.into(), // value_size
+                        i32_type.into(), // max_entries
+                    ],
+                    vec![
+                        i32_type.const_int(map_type_id as u64, false).into(),
+                        i32_type.const_int(key_size as u64, false).into(),
+                        i32_type.const_int(value_size as u64, false).into(),
+                        i32_type.const_int(max_entries_u32 as u64, false).into(),
+                    ],
+                )
+            }
+        };
         let struct_type = self.context.struct_type(&elements, false);
-        let initializer = struct_type.const_named_struct(&[
-            i32_type.const_int(map_type_id as u64, false).into(),
-            i32_type.const_int(key_size as u64, false).into(),
-            i32_type.const_int(value_size as u64, false).into(),
-            i32_type.const_int(max_entries_u32 as u64, false).into(),
-        ]);
+        let initializer = struct_type.const_named_struct(&initializer_values);
 
         // Create BTF type information for the map
         // This is critical for aya to understand the map structure
@@ -215,15 +236,13 @@ impl<'ctx> MapManager<'ctx> {
         di_builder: &DebugInfoBuilder<'ctx>,
         compile_unit: &inkwell::debug_info::DICompileUnit<'ctx>,
         name: &str,
-        perf_rb_pages: u64,
+        ringbuf_size: u64,
     ) -> Result<()> {
-        // For ringbuf, max_entries should be power of 2 and reasonable size
-        // Use 256KB (262144 bytes) which is a common size for eBPF ringbuf
-        let max_entries = 256 * 1024; // 262144
-        info!(
-            "Creating ringbuf map: {} with {} max entries ({} pages)",
-            name, max_entries, perf_rb_pages
-        );
+        // For ringbuf, max_entries is the buffer size in bytes (must be power of 2)
+        // The parameter name is kept as perf_rb_pages for backward compatibility,
+        // but we now interpret it directly as the ringbuf size in bytes
+        let max_entries = ringbuf_size;
+        info!("Creating ringbuf map: {} with {} bytes", name, max_entries);
         self.create_map_definition(
             module,
             di_builder,