ebpf-anomaly-rootcause

ebpf-anomaly-rootcause 是一个面向 Linux/openKylin/openEuler 的系统异常观测与根因定位工具。项目用 Python 组织诊断流程，结合 procfs 与 bpftrace/eBPF 采集 CPU、I/O、内存、锁竞争和系统调用信号，并输出 JSON、完整 Markdown 报告和更容易阅读的中文摘要报告。

当前能力

• anomdiag diagnose：执行采集、规则分析和报告生成，输出结构化根因诊断结果。
• anomdiag summarize：把 JSON 诊断结果转换成中文可读摘要，方便直接查看和答辩展示。
• anomdiag doctor：检查 bpftrace、stress-ng、fio、tracefs/procfs 等运行环境。
• anomdiag install-deps：打印或执行当前 Linux 发行版的依赖安装命令。
• --dry-run：在没有 eBPF 权限的开发机上验证完整流程。
• 支持诊断目标：cpu、io、memory、lock、syscall、all。
• 支持 JSON、YAML、Markdown、HTML 输出；报告包含异常类型、关联进程/线程、关键指标、时间窗口、疑似根因、证据链、建议结论和主因排序。
• 提供赛题验收矩阵：scripts/acceptance_matrix.py 会根据报告和证据目录生成 acceptance_matrix.json 与 acceptance_matrix.md，把评分项拆成“已验证 / 部分验证 / 待真机 / 未通过”。
• 支持容器/cgroup 上下文识别：Docker、Podman、containerd、container ID、cgroup 路径和资源限制字段。
• 内置插件化元数据：CPU、I/O、内存、锁竞争、syscall 插件均可独立扩展新的采集信号和诊断规则。
• CPU 目标支持 procfs 基线模式，在没有 bpftrace 时也能给出诊断结果。
• I/O、锁竞争、系统调用目标在没有 bpftrace 时会明确降级为不可用提示。

目录结构

anomdiag/
  collectors/   # 指标采集入口，当前以 procfs + bpftrace 为主
  analyzers/    # 根因判断规则
  report/       # JSON、完整 Markdown、可读摘要报告
  utils/        # 命令执行、运行环境探测、指标模型
bpftrace/       # bpftrace 采集脚本
scripts/        # 异常复现与演示脚本
examples/       # 示例输入/输出
docs/           # 设计与开发文档
tests/          # 自动化测试

安装

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

在 openKylin/openEuler/Ubuntu 真机或云服务器上采集 eBPF 信号时，建议先检查环境：

anomdiag doctor
anomdiag install-deps

如果确认要自动安装依赖：

anomdiag install-deps --yes

快速看到结果

最适合演示的一条命令：

bash scripts/demo_cpu.sh

脚本会自动制造一个 CPU 压力场景，运行 CPU 诊断，并在终端打印 reports/latest_summary.md 的中文可读摘要。输出文件包括：

reports/cpu_real.json        # 完整机器可读结果
reports/latest_summary.md    # 中文可读摘要
reports/cpu_stress.log       # 压力工具日志

内存压力演示：

bash scripts/demo_memory.sh

默认参数会使用较保守的内存压力，适合 2 核 2G 云服务器先跑通。输出文件包括：

reports/memory_real.json             # 完整机器可读结果
reports/latest_memory_summary.md     # 中文可读摘要
reports/memory_stress.log            # 压力工具日志

I/O 延迟抖动演示：

bash scripts/demo_io.sh

脚本会启动随机读写压力，运行 I/O 诊断，并生成中文可读摘要：

reports/io_real.json                 # 完整机器可读结果
reports/latest_io_summary.md         # 中文可读摘要
reports/io_stress.log                # 压力工具日志

如果已经有 JSON 诊断结果，也可以单独生成摘要：

anomdiag summarize reports/cpu_real.json --output reports/latest_summary.md
cat reports/latest_summary.md

常用命令

查看支持的诊断目标：

anomdiag list-targets

在任意开发环境验证流程：

anomdiag diagnose all --duration 5 --dry-run --format markdown

采集 CPU 异常信号并输出 JSON：

anomdiag diagnose cpu --duration 30 --format json --output reports/cpu.json

采集内存压力信号并输出 JSON：

anomdiag diagnose memory --duration 10 --format json --output reports/memory.json

采集 I/O 延迟信号并输出 JSON：

anomdiag diagnose io --duration 10 --format json --output reports/io.json

输出完整 Markdown 报告：

anomdiag diagnose cpu --duration 30 --format markdown --output reports/cpu.md

输出 YAML 结构化报告：

anomdiag diagnose all --duration 10 --format yaml --output reports/diagnosis.yaml

输出 HTML 报告：

anomdiag diagnose all --duration 10 --format html --output reports/diagnosis.html

结构化诊断字段

diagnose 输出会保留原始 metrics 和 findings，同时增加 diagnosis 顶层字段，便于机器解析和人工复核：

diagnosis.schema_version              # 报告结构版本
diagnosis.time_window                 # 观测开始/结束时间、持续时间、采样间隔
diagnosis.automatic_classification    # CPU/I/O/内存/锁/syscall 自动归类
diagnosis.primary_cause               # 多异常并发时的主因
diagnosis.findings_ranked             # 按严重级别和置信度排序的异常列表
diagnosis.correlations                # 多维关联关系
diagnosis.runtime_overhead            # 采集方式、指标数量、开销测量说明
diagnosis.container_observability     # 容器运行时、container ID、cgroup 上下文
diagnosis.plugins                     # 内置插件清单和扩展点
diagnosis.compatibility_matrix        # 架构、发行版、内核适配矩阵

每条 finding 也会补充：

anomaly_type             # 异常类型
related_processes        # 关联进程
related_threads          # 关联线程，存在 tid 时自动填充
related_resources        # 块设备、文件路径、锁实例、syscall 等资源
container_context        # Docker / Podman / containerd / cgroup 信息
key_metrics              # 支撑判断的关键指标
time_window              # 当前结论对应的观测窗口
suspected_root_cause     # 疑似根因
evidence_chain           # 为什么这么判断的证据链
recommendations          # 建议性结论
confidence               # 诊断置信度
rank                     # 主因排序

当前 CPU、内存、I/O 已能稳定形成真实闭环；CPU 已补线程级热点、热点函数和用户态栈样本，I/O 已补文件路径，锁竞争已补线程等待、wchan/futex 热点和 futex 栈样本，syscall 已补具体调用、错误码和慢调用栈样本；容器/cgroup 上下文、插件清单和 HTML 报告也已接入。

平台适配说明：当前服务器已验证 x86_64 / Ubuntu；openKylin、openEuler、Debian、Anolis、ARM64、RISC-V 走 procfs 基线兼容设计，eBPF 路径需要目标系统提供 tracefs/debugfs 与 bpftrace tracepoints。anomdiag doctor 会输出当前机器的架构、发行版、内核和兼容矩阵。

旧命令 anomdiag run --target cpu 仍然可用，diagnose 是更适合比赛演示的别名。

兼容性

• 在主流 Linux 发行版上，procfs 基线模式通常可用。
• 需要 eBPF/bpftrace 的目标，要求 Linux 内核、root 权限、tracefs/debugfs 和 bpftrace 可用。
• 如果 eBPF 条件不足，工具会自动降级，并在报告中标明当前采集模式。
• Windows 本机可以用 --dry-run 做流程开发；真实 eBPF 采集应放在 Linux 机器或云服务器上。

异常复现

bash scripts/reproduce/cpu_stress.sh
bash scripts/reproduce/io_stress.sh
bash scripts/reproduce/memory_stress.sh
bash scripts/reproduce/lock_stress.sh

建议先启动对应复现脚本，再运行 anomdiag diagnose <target> 采集诊断结果。

锁竞争诊断示例：

bash scripts/reproduce/lock_stress.sh 20 8 &
anomdiag diagnose lock --duration 8 --format json --output reports/lock.json
anomdiag summarize reports/lock.json --output reports/latest_lock_summary.md

开发

python -m pytest
python -m ruff check .

开销测量：

bash scripts/bench/overhead.sh 10 reports
cat reports/overhead.md

更多开发说明见 docs/development.md，测试与复现说明见 docs/testing.md。