ebpf-diag

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

简介

ebpf-diag 是一款轻量级、低开销的 Linux 系统异常实时观测与诊断工具，基于 eBPF 技术实现。支持对 CPU 异常占用、I/O 延迟抖动、内存抖动、锁竞争等典型异常场景进行实时观测、指标采集、事件关联分析和结构化诊断结果输出。

赛题: 全国研究生操作系统比赛 — 基于 eBPF 的系统异常观测与根因定位工具

目标平台: openKylin (Kernel 6.6+), x86_64 / ARM64

当前版本: v0.2.0 (5/5 类异常已覆盖，性能基准已验证)

代码仓库: https://gitlink.org.cn/llg987/jyedxtycgcygydwgj

特性

低侵入观测: 基于 eBPF 内核探针，零代码修改、低运行时开销
5 类异常全覆盖: CPU 异常、内存抖动、I/O 延迟、锁竞争、系统调用热点（均通过 Linux 6.8 真机验证）
自适应检测: 自适应基线学习 + 相对阈值，自动适配不同性能的硬件设备
多维关联分析: 跨指标关联推断，系统健康评分（100 分制）
实时检测: 时间窗口聚合 + 3 窗口防抖，秒级检测
结构化输出: JSON 格式诊断报告，含证据链、根因分析、系统摘要
可复现: 一键环境部署脚本和异常复现测试脚本
跨平台: Docker 容器化 + CO-RE 跨内核版本兼容

快速开始

环境要求

Linux Kernel 5.8+ (推荐 6.6+)
libbpf ≥ 1.0 (Ubuntu 22.04 的 0.5.0 版本需升级，参见 docs/测试方法.md)
clang, cmake
root 权限或 CAP_BPF, CAP_PERFMON, CAP_SYS_ADMIN

编译

# 安装依赖 (Ubuntu/openKylin)
sudo apt install -y build-essential cmake clang llvm libbpf-dev libelf-dev zlib1g-dev

# 注意: Ubuntu 22.04 的 libbpf-dev 版本为 0.5.0, 需手动升级:
# git clone --depth 1 --branch v1.4.0 https://github.com/libbpf/libbpf.git
# cd libbpf/src && make -j$(nproc) && sudo make install

# 生成 vmlinux.h (基于当前内核)
bpftool btf dump file /sys/kernel/btf/vmlinux format c > ebpf/vmlinux.h

# 编译
mkdir build && cd build
cmake .. && make -j$(nproc)

运行

# 监控 CPU 和内存异常，60秒，JSON 输出
sudo ./build/ebpf-diag --monitor cpu,mem --duration 60 --output json

# 全场景监控（5 类异常 + 交叉关联分析）
sudo ./build/ebpf-diag --monitor all --duration 60 \
    --output json --output-file output/report.json --verbose

# 一键测试
sudo bash scripts/test_all.sh

# 列出可用探针
sudo ./build/ebpf-diag --list-probes

Docker 环境

cd docker
docker-compose build
docker-compose run --privileged ebpf-diag-dev

项目结构

ebpf-diag/
├── ebpf/                # eBPF 内核态程序 (.bpf.c)
│   ├── cpu.bpf.c        # CPU 异常观测探针 (sched_switch + sched_wakeup)
│   ├── memory.bpf.c     # 内存异常观测探针 (page_alloc + kswapd + OOM)
│   ├── io.bpf.c         # I/O 延迟观测探针 (block_rq_issue + block_rq_complete)
│   ├── lock.bpf.c       # 锁竞争观测探针 (futex_wait kprobe + kretprobe)
│   ├── syscall.bpf.c    # 系统调用热点探针 (sys_enter + sys_exit)
│   └── common.bpf.h     # 共享 eBPF 数据结构
├── include/             # 用户态头文件
│   ├── types.h          # 公共数据类型 (Event, Metrics, AnomalyReport)
│   ├── collector.h      # 采集器接口 (BaseCollector, 5 类 Collector)
│   ├── detector.h       # 检测器接口 (自适应基线检测)
│   ├── analyzer.h       # 根因分析引擎 + EvidenceBuilder
│   └── reporter.h       # 报告输出 (JsonReporter + SummaryData)
├── src/                 # 用户态 C++ 实现
│   ├── main.cpp         # CLI 入口 + 主循环
│   ├── core/            # EbpfLoader, EventReader, Logger, Symbols
│   ├── collector/       # 5 类指标采集器 (主导进程追踪)
│   ├── detector/        # 5 类异常检测器 (自适应基线)
│   ├── analyzer/        # 根因分析 + 多维交叉关联
│   └── reporter/        # JSON 结构化输出 + 系统摘要
├── scripts/             # 7 个测试脚本 (test_*.sh, benchmark.sh)
├── docker/              # Dockerfile + docker-compose.yml
├── docs/                # 设计文档、测试方法、阶段总结
└── output/              # 诊断输出目录

支持的异常场景

场景	状态	验证方式	说明
CPU 异常占用	✅	`stress-ng --cpu 4`	自适应基线检测，正确识别 stress-ng，区分计算热点/线程竞争
内存抖动	✅	`stress-ng --vm 4 80%`	kswapd 活跃度 + page fault + OOM 多条件联合检测
I/O 延迟抖动	✅	`fio` on SD 卡	自适应基线（安静窗口学习）+ 相对阈值检测
锁竞争	✅	pthread mutex ×16	kprobe/kretprobe on `futex_wait`，测量实际等待时间
多类型关联	✅	CPU+Lock 同时触发	跨指标关联引擎输出关联提示
系统调用热点	✅	futex 锁竞争	PERCPU_HASH 直读 + 高延迟判定，同窗口 Top-3 热点

验证环境

项目	配置
OS	Ubuntu 22.04.5 LTS
Kernel	6.8.0-124-generic
CPU	24 核 (x86_64)
存储	NVMe SSD + SD 卡
libbpf	v1.4.0（从源码升级）

输出格式

{
  "tool": "ebpf-diag",
  "version": "0.2.0",
  "duration_seconds": 30,
  "total_anomalies": 24,
  "anomalies": [
    {
      "type": "CPU异常占用",
      "severity": "critical",
      "object": { "pid": 161000, "comm": "stress-ng" },
      "key_metrics": {
        "CPU使用率": 358.23,
        "上下文切换": 160463
      },
      "suspected_root_cause": "用户态计算热点导致CPU持续饱和",
      "evidence_chain": [
        "CPU利用率 358% 超过阈值 90%",
        "异常持续 3 个观测窗口",
        "关联进程: stress-ng (PID=161000)"
      ],
      "suggestion": "检查进程 stress-ng (PID=161000) 的计算逻辑是否可优化",
      "confidence": 0.67
    }
  ],
  "summary": {
    "system_health_score": 0,
    "dominant_issue": "锁竞争",
    "overall_assessment": "系统负载较重，多类异常并发...",
    "breakdown": { "cpu": 7, "memory": 0, "io": 0, "lock": 10, "syscall": 2, "correlations": 7 }
  }
}

文档导航

文档	内容
docs/设计文档.md	架构设计、技术选型、eBPF 探针设计
docs/测试方法.md	各场景测试步骤、一键脚本、故障排查
docs/当前状态与下一阶段计划.md	项目全面总结 + Phase 3 计划
docs/工具运行流程.md	以 CPU 为例的完整数据流详解
docs/第一阶段总结.md	Phase 1 技术总结
docs/第二阶段总结.md	Phase 2 技术总结

许可证

GPL-2.0