450 lines
17 KiB
Markdown
450 lines
17 KiB
Markdown
# eBPF 诊断工具
|
||
|
||
本目录包含用于监控和诊断 `agent_runner` 及其子进程性能的 eBPF 工具。
|
||
|
||
## 📊 监控架构总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 进程性能监控完整方案 │
|
||
├─────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ CPU 性能监控（持续） │ │
|
||
│ │ │ │
|
||
│ │ Grafana Alloy (eBPF) → Pyroscope Server → Web UI (4040) │ │
|
||
│ │ - 97 Hz 采样率 │ │
|
||
│ │ - 每 15 秒发送数据 │ │
|
||
│ │ - 自动发现进程 │ │
|
||
│ │ - 支持历史查询 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 进程指标监控（持续） │ │
|
||
│ │ │ │
|
||
│ │ Alloy Process Exporter → Prometheus → Grafana Dashboard │ │
|
||
│ │ - CPU、内存、I/O、FD、线程数 │ │
|
||
│ │ - 15 秒采集间隔 │ │
|
||
│ │ - 时序数据存储 │ │
|
||
│ │ - Dashboard 可视化 (3000) │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Off-CPU 阻塞监控（定期） │ │
|
||
│ │ │ │
|
||
│ │ offcputime-bpfcc → SVG 火焰图文件 │ │
|
||
│ │ - 每 60 秒生成一次 │ │
|
||
│ │ - 显示阻塞堆栈 │ │
|
||
│ │ - 识别 I/O、锁、等待等阻塞 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 系统调用监控（持续） │ │
|
||
│ │ │ │
|
||
│ │ syscount-bpfcc → 统计文件 │ │
|
||
│ │ execsnoop-bpfcc → 进程创建日志 │ │
|
||
│ │ opensnoop-bpfcc → 文件访问日志 │ │
|
||
│ │ - 每 60 秒统计一次 │ │
|
||
│ │ - 持续追踪进程和文件访问 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 手动诊断工具（按需使用） │ │
|
||
│ │ │ │
|
||
│ │ diag-tool.sh - 综合诊断工具 │ │
|
||
│ │ auto-flamegraph.sh - 自动火焰图生成 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
ebpf-tools/
|
||
├── README.md # 本文档
|
||
├── alloy-config.alloy # Grafana Alloy 配置（CPU 监控 + 进程指标导出）
|
||
├── diag-tool.sh # 手动诊断工具
|
||
├── auto-flamegraph.sh # 自动火焰图生成
|
||
├── offcpu-monitor.sh # Off-CPU 阻塞监控
|
||
└── syscall-monitor.sh # 系统调用监控
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 工具详解
|
||
|
||
### 1. alloy-config.alloy - Grafana Alloy 配置
|
||
|
||
**用途**: 持续 CPU 性能监控 + 进程指标导出
|
||
|
||
**工作原理**:
|
||
- 使用 eBPF 自动发现 `agent_runner` 及其子进程
|
||
- 以 97 Hz 频率采样 CPU 性能数据，发送到 Pyroscope
|
||
- 采集进程指标（CPU、内存、I/O、FD、线程数），发送到 Prometheus
|
||
- 在 Web UI 中实时查看：Pyroscope (4040) + Grafana (3000)
|
||
|
||
**采集的指标**:
|
||
| 指标类别 | 指标名称 | 说明 |
|
||
|---------|---------|------|
|
||
| **CPU** | `process_cpu_seconds_total` | CPU 时间（累计） |
|
||
| **内存** | `process_resident_memory_bytes` | 常驻内存（RSS） |
|
||
| **内存** | `process_virtual_memory_bytes` | 虚拟内存（VSZ） |
|
||
| **FD** | `process_open_fds` | 打开的文件描述符 |
|
||
| **I/O** | `process_read_bytes_total` | 读取字节数 |
|
||
| **I/O** | `process_write_bytes_total` | 写入字节数 |
|
||
| **线程** | `process_num_threads` | 线程数量 |
|
||
| **上下文切换** | `process_context_switches_total` | 上下文切换次数 |
|
||
|
||
**进程标签**:
|
||
- `process_pid`: 进程 PID
|
||
- `process_name`: 进程名称
|
||
- `process_exe`: 完整执行路径
|
||
- `parent_pid`: 父进程 PID
|
||
- `project_id`: 项目 ID
|
||
- `container_id`: 容器 ID
|
||
|
||
**环境变量**:
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `ENABLE_ALLOY` | - | 是否启用（由 ebpf-debug feature 控制） |
|
||
| `PYROSCOPE_URL` | http://pyroscope:4040 | Pyroscope Server 地址 |
|
||
| `PROMETHEUS_URL` | http://prometheus:9090/api/v1/write | Prometheus 写入地址 |
|
||
|
||
**查看数据**:
|
||
```bash
|
||
# 1. Pyroscope Web UI (CPU 性能)
|
||
open http://localhost:4040
|
||
|
||
# 2. Grafana Dashboard (进程指标)
|
||
open http://localhost:3000
|
||
# 登录: admin / admin
|
||
# 查找: "Agent Runner 进程监控"
|
||
```
|
||
|
||
---
|
||
|
||
### 2. offcpu-monitor.sh - Off-CPU 阻塞监控
|
||
|
||
**用途**: 定期生成 Off-CPU 阻塞火焰图，分析进程阻塞原因
|
||
|
||
**工作原理**:
|
||
- 每 60 秒自动运行一次（可配置）
|
||
- 对 `agent_runner` 及其所有子进程进行采样
|
||
- 使用 `offcputime-bpfcc` 捕获阻塞堆栈
|
||
- 生成 SVG 火焰图文件，自动清理旧文件（最多保留 50 个）
|
||
|
||
**环境变量**:
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `ENABLE_OFFCPUTIME` | - | 是否启用（由 ebpf-debug feature 控制） |
|
||
| `OFFCPU_DURATION` | 30 | 每次采样时长（秒） |
|
||
| `OFFCPU_INTERVAL` | 60 | 生成间隔（秒） |
|
||
| `MAX_OFFCPU_FILES` | 50 | 最多保留文件数量 |
|
||
|
||
**输出文件**:
|
||
```
|
||
/app/container-logs/diag/
|
||
├── offcpu-monitor.log # 监控日志
|
||
├── offcpu-agent_runner-1-20250111_143025.svg # 主进程阻塞火焰图
|
||
└── offcpu-claude-code-acp-123-*.svg # 子进程阻塞火焰图
|
||
```
|
||
|
||
---
|
||
|
||
### 3. syscall-monitor.sh - 系统调用监控
|
||
|
||
**用途**: 监控进程的系统调用活动，包括进程创建、文件访问和系统调用统计
|
||
|
||
**工作原理**:
|
||
- 每 60 秒统计一次系统调用（可配置）
|
||
- 后台持续追踪进程创建 (`execsnoop-bpfcc`)
|
||
- 后台持续追踪文件访问 (`opensnoop-bpfcc`)
|
||
- 定期生成系统调用统计报告
|
||
|
||
**采集的数据**:
|
||
| 工具 | 数据 | 说明 |
|
||
|------|------|------|
|
||
| `syscount-bpfcc` | 系统调用统计 | 每个系统调用的次数和耗时 |
|
||
| `execsnoop-bpfcc` | 进程创建日志 | 新进程的创建时间和命令行 |
|
||
| `opensnoop-bpfcc` | 文件访问日志 | 文件打开/关闭操作 |
|
||
|
||
**环境变量**:
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `ENABLE_SYSCALL_MONITOR` | - | 是否启用（由 ebpf-debug feature 控制） |
|
||
| `SAMPLE_DURATION` | 30 | 每次采样时长（秒） |
|
||
| `GENERATE_INTERVAL` | 60 | 生成间隔（秒） |
|
||
|
||
**输出文件**:
|
||
```
|
||
/app/container-logs/diag/
|
||
├── syscall-monitor.log # 监控日志
|
||
├── syscall-count-agent_runner-1-*.txt # 系统调用统计
|
||
├── execsnoop-*.log # 进程创建日志
|
||
└── opensnoop-*.log # 文件访问日志
|
||
```
|
||
|
||
**日志说明**:
|
||
- **控制台输出**: 每次采样只输出一行汇总日志
|
||
- **文件日志**: 详细日志写入 `syscall-monitor.log`
|
||
|
||
---
|
||
|
||
### 4. diag-tool.sh - 手动诊断工具
|
||
|
||
手动触发的 eBPF 诊断工具，用于在怀疑有性能问题时主动采集数据。
|
||
|
||
**用法**:
|
||
```bash
|
||
diag-tool.sh {offcpu|flame|profile|all} <pid> [duration]
|
||
```
|
||
|
||
**命令**:
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `offcpu <pid> [duration]` | 分析 off-cpu 堆栈，默认 30 秒 |
|
||
| `flame <pid> [duration]` | 生成火焰图，默认 30 秒 |
|
||
| `profile <pid> [duration]` | CPU 性能分析，默认 30 秒 |
|
||
| `all <pid>` | 综合诊断（包含所有分析） |
|
||
|
||
**快捷命令**:
|
||
- `e-offcpu` - 等同于 `diag-tool.sh offcpu`
|
||
- `e-flame` - 等同于 `diag-tool.sh flame`
|
||
- `e-profile` - 等同于 `diag-tool.sh profile`
|
||
- `e-all` - 等同于 `diag-tool.sh all`
|
||
|
||
---
|
||
|
||
### 5. auto-flamegraph.sh - 自动火焰图生成
|
||
|
||
持续在后台运行的火焰图生成工具，自动监控 `agent_runner` 及其所有子进程。
|
||
|
||
**工作原理**:
|
||
1. 自动检测 `agent_runner` 进程 PID
|
||
2. 递归获取所有子进程 PID
|
||
3. 使用 bpftrace 采样性能数据（默认 30 秒）
|
||
4. 生成火焰图 SVG 文件
|
||
5. 每 60 秒重复一次
|
||
|
||
---
|
||
|
||
## 🎯 使用场景
|
||
|
||
### 场景 1: 持续监控 CPU 性能
|
||
|
||
**目标**: 在 Web UI 中实时查看 agent_runner 性能数据
|
||
|
||
**步骤**:
|
||
1. 确保容器已启动（Alloy 自动运行）
|
||
2. 打开 http://localhost:4040 (Pyroscope)
|
||
3. 选择应用 `agent_runner`
|
||
4. 按需过滤标签（如 `process_name="agent_runner"`）
|
||
5. 查看火焰图、时序数据、Top 函数
|
||
|
||
**适用问题**:
|
||
- CPU 使用率异常
|
||
- 函数调用热点分析
|
||
- 性能回归检测
|
||
|
||
---
|
||
|
||
### 场景 2: 查看进程指标趋势
|
||
|
||
**目标**: 监控内存、I/O、FD 等进程指标的趋势
|
||
|
||
**步骤**:
|
||
1. 打开 http://localhost:3000 (Grafana)
|
||
2. 登录（admin / admin）
|
||
3. 查找 "Agent Runner 进程监控" Dashboard
|
||
4. 选择 `project_id`、`instance`、`process_name` 过滤
|
||
5. 查看各面板数据
|
||
|
||
**可用面板**:
|
||
- 概览: RSS/VSZ 内存、CPU 使用率、文件描述符
|
||
- 内存趋势: RSS 和 VSZ 的时间序列图
|
||
- I/O 监控: 读取/写入速率
|
||
- 上下文切换: 自愿/非自愿切换速率
|
||
- 线程详情: 线程数量、FD 使用率
|
||
- 缺页错误: 次要/主要缺页错误速率
|
||
|
||
---
|
||
|
||
### 场景 3: 分析进程阻塞问题
|
||
|
||
**目标**: 找出进程为什么被阻塞（等待 I/O、锁等）
|
||
|
||
**步骤**:
|
||
1. 等待 offcpu-monitor 自动生成火焰图（或手动触发）
|
||
2. 导出 SVG 文件到本地
|
||
3. 在浏览器中打开火焰图
|
||
4. 查找宽的阻塞堆栈
|
||
|
||
```bash
|
||
# 导出最新的 Off-CPU 火焰图
|
||
docker cp <container>:/app/container-logs/diag/offcpu-*.svg ./
|
||
open offcpu-*.svg
|
||
```
|
||
|
||
**适用问题**:
|
||
- `new_session` 超时
|
||
- 进程响应缓慢
|
||
- I/O 阻塞
|
||
- 锁竞争
|
||
|
||
---
|
||
|
||
### 场景 4: 分析系统调用模式
|
||
|
||
**目标**: 了解进程的系统调用行为，找出系统调用热点
|
||
|
||
**步骤**:
|
||
1. 查看系统调用统计日志
|
||
2. 分析哪些系统调用最频繁
|
||
3. 查看 execsnoop/opensnoop 日志了解进程和文件访问
|
||
|
||
```bash
|
||
# 查看系统调用统计
|
||
docker exec <container> cat /app/container-logs/diag/syscall-count-*.txt | head -20
|
||
|
||
# 查看进程创建日志
|
||
docker exec <container> tail -f /app/container-logs/diag/execsnoop-*.log
|
||
```
|
||
|
||
---
|
||
|
||
### 场景 5: 手动诊断已知问题
|
||
|
||
```bash
|
||
# 进入容器
|
||
docker exec -it <container> bash
|
||
|
||
# 诊断 agent_runner
|
||
e-all $(pgrep agent_runner)
|
||
|
||
# 导出结果
|
||
docker cp <container>:/app/container-logs/diag ./diag-results
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 火焰图分析
|
||
|
||
### CPU 火焰图（Alloy + Pyroscope）
|
||
|
||
**如何阅读**:
|
||
- **横轴**: CPU 时间占比（越宽表示占用越多）
|
||
- **纵轴**: 调用堆栈（从上到下是调用关系）
|
||
- **颜色**: 暖色调表示热点函数
|
||
|
||
**典型问题识别**:
|
||
| 现象 | 可能原因 |
|
||
|------|----------|
|
||
| 某个函数占据大部分宽度 | CPU 密集型计算 |
|
||
| 深层函数很宽 | 递归调用或深层嵌套 |
|
||
| 出现 `syscall` 大量时间 | 系统调用开销 |
|
||
| 出现 `sleep`/`usleep` | 主动休眠或等待 |
|
||
|
||
### Off-CPU 火焰图（offcputime-bpfcc）
|
||
|
||
**如何阅读**:
|
||
- **横轴**: 阻塞时间占比（越宽表示阻塞越久）
|
||
- **纵轴**: 阻塞时的调用堆栈
|
||
- **颜色**: 暖色调表示阻塞热点
|
||
|
||
**典型问题识别**:
|
||
| 现象 | 可能原因 |
|
||
|------|----------|
|
||
| `schedule()` 占据大量时间 | 进程被调度出去（CPU 竞争） |
|
||
| `do_wait()`/`wait_event()` | 等待事件或信号 |
|
||
| `__sock_sendmsg()`/`__sock_recvmsg()` | 网络 I/O 阻塞 |
|
||
| `blk_mq_submit_bio()` | 磁盘 I/O 阻塞 |
|
||
| `futex_wait()` | 锁等待（互斥锁） |
|
||
|
||
---
|
||
|
||
## 🔍 故障排查
|
||
|
||
### Grafana Dashboard 显示 "No Data"
|
||
|
||
```bash
|
||
# 1. 检查 Prometheus 中是否有数据
|
||
curl -s 'http://localhost:9091/api/v1/query?query=process_resident_memory_bytes'
|
||
|
||
# 2. 检查标签值
|
||
curl -s 'http://localhost:9091/api/v1/label/project_id/values'
|
||
|
||
# 3. 确认 agent_runner 容器正在运行
|
||
docker ps | grep agent_runner
|
||
```
|
||
|
||
### 变量下拉框为空
|
||
|
||
```bash
|
||
# 检查标签值是否存在
|
||
curl -s 'http://localhost:9091/api/v1/label/project_id/values'
|
||
|
||
# 如果没有数据，说明没有 agent_runner 容器在运行
|
||
# 启动一个 agent_runner 容器后再检查
|
||
```
|
||
|
||
### Pyroscope Web UI 无数据
|
||
|
||
```bash
|
||
# 1. 检查 Pyroscope Server
|
||
docker ps | grep pyroscope
|
||
docker logs rcoder-pyroscope
|
||
|
||
# 2. 检查 Alloy 是否发送数据
|
||
docker exec <container> grep "collected profiles" /app/container-logs/diag/alloy.log
|
||
|
||
# 3. 检查网络连接
|
||
docker exec <container> curl http://pyroscope:4040
|
||
```
|
||
|
||
### Off-CPU 火焰图未生成
|
||
|
||
```bash
|
||
# 1. 检查 offcputime-bpfcc 是否可用
|
||
docker exec <container> which offcputime-bpfcc
|
||
|
||
# 2. 检查监控进程
|
||
docker exec <container> ps aux | grep offcpu-monitor
|
||
|
||
# 3. 查看监控日志
|
||
docker exec <container> tail -f /app/container-logs/diag/offcpu-monitor.log
|
||
```
|
||
|
||
### 系统调用监控无输出
|
||
|
||
```bash
|
||
# 1. 检查 syscount-bpfcc 是否可用
|
||
docker exec <container> which syscount-bpfcc
|
||
|
||
# 2. 检查监控脚本是否运行
|
||
docker exec <container> ps aux | grep syscall-monitor
|
||
|
||
# 3. 查看监控日志
|
||
docker exec <container> tail -f /app/container-logs/diag/syscall-monitor.log
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 安全注意事项
|
||
|
||
⚠️ **eBPF 工具需要容器特权模式运行**，仅在受信任的调试环境使用！
|
||
|
||
生产环境请使用 `make docker-build-agent-production` 构建无 eBPF 工具的镜像。
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [Grafana Alloy Documentation](https://grafana.com/docs/alloy/latest/)
|
||
- [Pyroscope Documentation](https://pyroscope.io/docs/)
|
||
- [Prometheus Documentation](https://prometheus.io/docs/)
|
||
- [Grafana Documentation](https://grafana.com/docs/)
|
||
- [Brendan Gregg's FlameGraph](https://github.com/brendangregg/FlameGraph)
|
||
- [bpftrace 参考指南](https://bpftrace.dev/)
|
||
- 主项目文档: `/docker/README.md`
|