ebpf-rca

第三届中国研究生操作系统开源创新大赛参赛项目。目标平台为 openKylin、Kernel 6.6+、 x86_64/ARM64。

工具在内核事件点运行 eBPF 程序，将高频事件聚合到 BPF map；Go 用户态按真实采样窗口读取差分，再用确定性规则完成检测和根因分类。输出包含关联对象、指标、时间窗、稳定根因代码、证据链与建议。

内核事件 -> eBPF 探针 -> BPF map -> collector -> detector -> RCA -> 结构化输出

覆盖场景

场景	主要挂载点	主要结论
CPU	`tp_btf/sched_*`、10 Hz per-CPU perf event	计算热点 / 调度压力
I/O	`tp_btf/block_rq_complete`；异常后按需 `tp_btf/iomap_dio_rw_begin`	队列拥塞 / 设备时延 / 有条件的进程与文件归因
内存	`vmscan` tracepoint、`tp_btf/mark_victim`	回收压力 / 已发生 OOM
锁	wait-only futex helper 与 `schedule` 的 fentry/fexit；可选 `tp_btf/sched_*`	futex 竞争 / 内核同步等待
syscall	`tp_btf/sys_enter`；独立 target 或全局慢调用 opt-in 追加 raw `sys_exit`	高频 / 非等待型高耗时调用

I/O 主路径只在最终 complete 读取 request.start_time_ns，独立模式按稳定分配时间确定性采样 1/8 并以逆概率权重还原，all-mode 使用 1/32 事件采样与 1/5 duty。块层指标先触发异常，随后才按需挂载 direct-I/O 提交探针；只有设备、窗口、覆盖率、Top share、实际样本数与 PID starttime 全部通过门槛，才把 PID/文件写入根因对象，否则保持设备级结论。内存检测由持续系统压力触发，进程匿名 RSS/direct reclaim/major fault 增量只负责根因对象归因。

快速运行

仓库已跟踪 bpf2go 生成物；普通 clean clone 可直接构建：

cd ebpf-rca
bash scripts/deploy.sh

sudo ./bin/ebpf-rca --scenario all --duration 60s --format json --output session.json
sudo ./bin/ebpf-rca --scenario all --format jsonl
sudo ./bin/ebpf-rca --scenario all --duration 60s --report report.md

如需跳过本机构建，可直接使用 release/openkylin-x86_64/ 中的 Linux x86_64 预构建版本。请先按目录内说明校验 SHA-256，再授予执行权限并以 root 或等价 capability 运行。预构建文件用于快速复现，不替代源码和构建脚本。

修改 .bpf.c 时才需要在目标内核重新生成：

# 在仓库根目录执行；要求 tracked tree clean。
bash ebpf-rca/scripts/deploy.sh --regenerate

默认部署只校验并消费已提交的 bpf2go 产物，不改写 go.mod、vmlinux.h 或生成文件。 --regenerate 在 /var/tmp 的临时 clean tree 中使用 dependencies.lock.json 固定的依赖和目标机 BTF 重建，仅输出生成物 hash 对比，不覆盖工作区。

加载探针需要 root 或等价 capability。strict all-mode 需要表中全部内核能力；单场景只要求对应 collector 的挂载点。锁符号化还需要可解析的 /proc/kallsyms。

可视化

sudo ./bin/ebpf-rca --scenario all --visual --duration 60s --output session.json

程序在 stderr 输出带临时 token 的本机 URL。服务只监听 loopback；远程查看使用 SSH 端口转发。 CPU/lock 展示探针实际采到的栈；lock 的用户栈绑定采样 waiter TID，不是 owner 栈。 I/O/mem/syscall 只展示指标，不合成火焰图。

strict all-mode 会按事件合并跨层症状：块 I/O 主报告吸收关联窗口内的 I/O-path syscall；只有被这些 syscall 证据确认的同 PID CPU 症状才会并入，不同 PID 仍独立报告。PI futex 只把 helper entry 时原子读取的状态字解释为 owner 快照；普通非 PI futex 没有可靠 owner，waker_tid 也只表示唤醒者。

默认全局/all-mode syscall 是 frequency-only。--scenario syscall --target-pid PID 可对目标树的非等待型调用做精确 enter/exit；--scenario syscall --target-pid 0 --syscall-global-latency 显式启用全局慢调用模式，也只精确配对非等待型调用。epoll/futex/read/write 等等待型调用在两种精确模式中仍只统计频率，不因正常 wall time 较长触发高耗时结论。 frequency-only duty 在挂载前预写内核单调时钟 [start_ns,end_ns)，并提前挂载 tracing link； BPF 以 bpf_ktime_get_ns() 自行开关窗口，用户态边界唤醒不参与开启或关闭，只在窗口结束后卸载。因此调度迟到不会移动统计边界。全局模式先做独立 1/16 事件筛选，只有入样事件读取窗口 map 和内核时钟；syscall 时间片为每个 Poll 的 1/20，总权重 320。窗口内随机事件筛选保持无偏，时间外推要求片段对整窗具有代表性；全部 BPF 运行时间仍计入正式性能开销。

文档入口

测试与复现

仓库直接包含完整测试树，不需要额外覆盖包：

cd ebpf-rca
go test ./...
make test-local       # 五类正例，需要 openKylin/Linux、root 或等价 capability
make test-negative    # 语义负例
make accuracy-full    # 严格 oracle、多轮准确率评测
make bench-full       # 配对性能基准
bash scripts/platform_acceptance.sh

当前源码树包含 24 个 Go 测试文件（179 个 Test* 函数）和 4 个 Python 测试文件（48 个 test_* 函数）。结构化会话格式为 DiagnosticSession 1.1。仓库内附带 ebpf-rca-demo.mp4 演示视频，比赛平台如有独立视频字段，可同时上传同一文件。

证据边界

仓库不附带当前提交的正式 platform bundle，也不宣称当前 checkout 已完成 openKylin 正式平台验收。 evidence/reference-openkylin/ 保存的是 2026-07-27、openKylin x86_64、Kernel 6.6.0-22-generic 上的冻结前历史回归，运行器未记录确切 source_commit，因此只能作为方法与结果快照参考，不能外推为当前提交成绩。

该历史准确率快照为 100/100 有效轮次通过；严格性能复测中 all-mode 最大吞吐下降为 1.851%、最大组合内存为 60.906 MiB，但 fio P99 增幅为 6.256%，超过 5% 门槛，因此不能宣称性能验收通过。完整引用边界见 REFERENCE_EVIDENCE.json。 ARM64 仅提供静态交叉编译门禁，不宣称已通过 ARM64 目标内核 verifier 或实机运行；不宣称 RISC-V 适配完成。

License

见 LICENSE。eBPF 程序以 GPL 兼容许可证加载。