eano — 基于 eBPF 的系统异常观测与根因定位工具

赛道：系统创新（社区赛题）· 目标环境：openKylin / Kernel 6.6+ · 技术栈：libbpf + CO-RE（C）

eano 用 eBPF 在主机/OS 层采集五类系统异常，做跨资源、时间窗关联，输出带证据链的结构化诊断，满足赛题”可回溯、降低幻觉”的要求。

覆盖的五类异常

类别	挂载点（稳定 ABI 优先）	参考谱系
① CPU/调度延迟	`sched_wakeup` / `sched_switch` tracepoint	runqlat
② 块 I/O 延迟	`block_rq_issue` / `block_rq_complete`	biolatency
③ 内存抖动/OOM	`handle_mm_fault` kprobe + `vmscan` tp + `oom_kill_process`	oomkill/cachestat
④ 锁竞争(futex)	`sys_enter/exit_futex` tracepoint	offcputime
⑤ syscall 热点	`raw_syscalls:sys_enter/sys_exit`	syscount

设计要点（对齐评分项）

内核侧聚合 + ring buffer：延迟类指标在内核用直方图/hash map 聚合，仅超阈值离群事件上送 ring buffer → 压低自身开销。
统一事件时间轴：所有探针事件带时间戳/PID/TID/CPU/设备维度，单点消费。
确定性关联引擎：规则评分 + 证据链固化，结论可回溯，不依赖 LLM 推断根因。
结构化输出：JSON，字段含异常类型/关联对象/关键指标/时间窗/疑似根因/证据链/建议。

目录结构

src/eano.h            内核↔用户共享数据结构
src/bpf/*.bpf.c       5 个 CO-RE BPF 程序
src/collectors/*.c    各维度用户态采集器
src/correlate.{c,h}   关联与证据链评分引擎
src/json.{c,h} hist.{c,h}  轻量 JSON / 直方图工具
src/eano.c            主程序(编排→消费→关联→输出)
scripts/              环境自检 / vmlinux.h 生成 / 复现负载 / 部署
src_mcp/              eano MCP 服务(stdio): 把诊断能力封装成 MCP 工具
src_web/              Web 聊天 demo: FastAPI+SSE 后端 + Vue3 前端 (见 src_web/README.md)

在服务器上构建与运行

# 0. 环境自检 (落实报告头号风险: BTF 是否开启)
bash scripts/check_env.sh

# 1. 拉取依赖子模块 (需要 git 仓库)
git submodule update --init --recursive

# 2. 一键部署(自检→子模块→vmlinux.h→make)
bash scripts/deploy.sh
# 或手动:
make -j$(nproc)

# 3. 运行 (需 root / CAP_BPF)
sudo ./eano                      # 人类可读, 5s 诊断周期
sudo ./eano -j -i 3000           # JSON 结构化输出, 3s 周期
sudo ./eano -p $(pgrep -n stress-ng) -d 60   # 仅观测某进程, 跑 60s

依赖（openKylin / Debian 系）

sudo apt install -y clang llvm libelf-dev zlib1g-dev make git \
                    linux-tools-common stress-ng fio

注入-验证（复现脚本）

开两个终端：一个跑 sudo ./eano，另一个注入负载。

bash scripts/workload_cpu.sh        # ① CPU 饱和/调度延迟
bash scripts/workload_io.sh         # ② I/O 延迟抖动 (fio)
bash scripts/workload_mem.sh        # ③ 内存抖动/OOM
bash scripts/workload_lock.sh       # ④ futex 锁竞争
bash scripts/workload_syscall.sh    # ⑤ syscall 热点

调试指引（远程 Linux）

若 make 或运行报错，请把以下输出贴回，便于定位：

bash scripts/check_env.sh 全文（确认 BTF / 工具链）。
make 的首条报错（通常是 BPF 程序里 CO-RE 字段名与本机内核 BTF 不符，最可能在 bio.bpf.c 的设备号读取、或 tracepoint 上下文字段）。
运行期 sudo ./eano -v 的 libbpf 详细日志（attach 失败时）。

已知跨内核版本敏感点：block_rq_* 的 request->q->disk 路径、handle_mm_fault 是否被内联、mm_vmscan_direct_reclaim_begin tracepoint 名称。这些在 openKylin 6.6 上若不符，按报错改 BPF_CORE_READ 路径或 tracepoint 名即可。

输出样例（JSON）

{"epoch":3,"window_start_ns":...,"finding_count":1,
 "findings":[{"anomaly_type":"CPU/调度延迟",
   "related_object":{"pid":12345,"comm":"stress-ng-cpu"},
   "score":80,"root_cause":"就绪队列拥塞, CPU 资源争用导致上 CPU 延迟",
   "suggestion":"核对 CPU 亲和/配额, 排查同机计算密集型干扰进程",
   "evidence":["run queue 延迟离群 73 次, 峰值 45.120 ms"]}]}

MCP 服务与 Web 聊天 Demo

在 eano 之上封装了一层 MCP 服务和 Web 聊天 demo,让 LLM 能调用 eBPF 诊断能力做根因分析。

src_mcp/：标准 MCP 服务(stdio),把诊断封装成 3 个工具 eano_diagnose / eano_list_samples / eano_replay_sample,可直接接入 Claude Desktop 等 MCP host。
src_web/：FastAPI + SSE 后端(MCP host + LLM 编排)+ Vue3 前端聊天界面。

cp src_web/backend/.env.example src_web/backend/.env   # 填入 OPENAI_API_KEY(支持 OpenAI/DeepSeek/通义/本地)
bash scripts/run_backend.sh     # 终端 A: 后端 :8000 (首次自建 venv)
bash scripts/run_frontend.sh    # 终端 B: 前端 :5173 (首次 pnpm install)

有 root 时现场跑 ./eano 真实采集;无 root 时自动回放 test_results/*.json 历史样本, 保证没有权限也能完整演示。详见 src_web/README.md。