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

参赛队伍：超威战队赛题：基于eBPF的系统异常观测与根因定位工具（社区赛题），赛题原文见 docs/赛题要求.md

sysrca（System Root Cause Analyzer）是一款基于 eBPF（libbpf + CO-RE）的轻量级系统异常观测与根因定位工具。它以低侵入、低开销的方式在内核态采集调度、块 I/O、内存回收、锁竞争与系统调用等关键事件，结合 /proc、/sys 系统指标进行多维关联分析与因果排序，实时识别典型系统异常，输出包含证据链的结构化诊断结论（JSON/Markdown/YAML），并提供 Web 可视化界面。

一句话验证：sudo ./scripts/install_deps.sh && make -C src && sudo ./scripts/run_scenario.sh all 60

功能特性

覆盖赛题要求的全部 5 类典型异常场景：

场景	内核观测点	关键证据
CPU 异常占用 / 调度延迟	sched_switch / sched_wakeup	CPU 利用率、run queue 等待直方图与 P99、上下文切换、热点进程 on-CPU 时间
I/O 延迟抖动 / 阻塞等待	block_rq_issue / block_rq_complete（raw tracepoint）	IOPS、平均/最大/P99 时延、队列深度、热点设备与进程；文件 I/O 高耗时自动归类并与块层互证
内存抖动 / OOM 风险	vmscan 回收、oom/mark_victim + /proc/meminfo、/proc/vmstat	可用内存、major fault、缺页风暴、kswapd/直接回收耗时、OOM 受害与触发进程、Top RSS
锁竞争性能退化	sys_enter/exit_futex	热点锁地址、并发等待者数、等待频率、平均/最大等待时间、涉事线程清单
系统调用热点	raw_syscalls:sys_enter/sys_exit	高频/高耗时系统调用、占单核比例、(进程, 调用号) 热点

结构化输出：JSON / Markdown / YAML 三格式，异常八字段齐备（类型、关联对象、关键指标、时间窗口、证据链、疑似根因、建议结论、置信度），字段稳定、机器可解析
Web 可视化：零依赖 Python 服务 + ECharts 离线仪表盘，指标时间线与异常证据链浏览器交互查看
高准确性：静态阈值 + 滑动基线（Welford z-score）双轨判定、多模块交叉验证与因果排序；针对线程池空闲阻塞、高频低耗系统调用等易误报场景做了专项设计，空载零误报
低开销：事件在内核态 BPF map 内就地聚合（per-CPU 无锁 + LRU 有界），无逐事件上报；计算型负载吞吐影响 < 1%，工具自身 CPU≈0、内存约 5MB
可移植：纯 CO-RE 实现，一次编译多内核运行（5.8 ~ 6.6+），已适配 block 层跟踪点跨版本差异；内置 vmlinux.h 回退，无 bpftool、无外网也能编译
可复现：一键安装、五场景复现、A/B 开销评测、openKylin 评测虚拟机一键构建与自动验证脚本

总体架构与工作原理

内核态 5 个 BPF 模块把每事件数据折叠为计数/求和/最大值/log2 直方图存于 map；用户态每窗口（默认 5s）批量读取并清零，融合 /proc//sys 指标完成检测、根因分类与证据链组装；结束时做因果排序并生成报告。

sysrca 总体架构

sysrca 工作流程

结构化输出的字段构成：

结构化诊断输出

openKylin 实测结果（官方参考负载）

评测环境：openKylin 2.0 SP1（内核 6.6.0-22）QEMU/KVM 虚拟机 4核8G（与赛题基础评测环境一致），按赛题官方参考命令原始参数（180 秒、fio 4G）实测，报告原件见 output/openkylin-verify/official/：

场景（官方参考负载）	主导异常（检出窗口）	根因定位
stress-ng –cpu 4 –cpu-method matrixprod	CPU异常占用/调度延迟（35/35, critical）	stress-ng-cpu 忙循环，热点进程+切换+调度等待
fio randrw 4G iodepth=64 numjobs=4	I/O延迟抖动/阻塞等待（34/35）	fio 进程 + pread64 文件I/O等待，块层IOPS/P99互证
stress-ng –vm 4 –vm-bytes 80% –vm-keep	内存抖动/回收压力（35/35）	stress-ng-vm 缺页1.2万次/秒、可用内存降至10.5%
stress-ng –mutex 8	锁竞争（20/21）	锁实例 0xfe1c80、3并发等待线程、5.7万次/秒
小块同步写风暴（自研补充）	系统调用热点（12/12）	stress-ng-hdd 的 write 热点

另：memhog 高压内存场景可稳定触发「内存抖动/OOM」（critical, 95%），OOM 受害/触发进程均定位。

五类场景实测结果

空载连续观测零误报；性能开销：计算型基准吞吐 -0.05%，纯上下文切换微基准（最坏情况）约 -29%，工具自身 CPU≈0、内存约 5MB（详见 docs/images/overhead.png）。

快速开始

# 1. 安装依赖（openKylin/Ubuntu/Debian 用 apt，openEuler/Fedora 用 dnf；
#    已自动处理 openKylin nile 源的 clang/bpftool/stress-ng 依赖问题）
sudo ./scripts/install_deps.sh

# 2. 编译（自动生成 vmlinux.h 与系统调用表；无 bpftool 时自动使用内置回退头文件）
make -C src

# 3. 运行（默认全部 5 个模块，5s 一个分析窗口，Ctrl-C 结束并出报告）
sudo ./src/sysrca -d 60 -o report -f json,md,yaml

# 4. 一键复现异常场景并验证诊断（cpu|io|mem|lock|syscall|all）
sudo ./scripts/run_scenario.sh lock 60

# 5. 评估工具自身开销
sudo ./scripts/overhead_bench.sh 30

# 6. Web 可视化查看诊断报告（零依赖，浏览器打开 http://127.0.0.1:8688）
python3 scripts/sysrca_web.py

在任意 x86_64 Linux 主机上一键构建 openKylin 评测虚拟机并自动完成全部验证：

sudo ./scripts/build_openkylin_vm.sh /opt/okylin-vm   # 构建（含内核6.6与工具链）
sudo /opt/okylin-vm/start_vm.sh                       # 启动（SSH 127.0.0.1:2222 / okylin）
./scripts/vm_verify.sh                                # 虚拟机内编译+五场景+开销评估

命令行参数

sudo sysrca [选项]
  -d, --duration SEC   观测总时长，0 表示持续运行至 Ctrl-C（默认 0）
  -i, --interval SEC   分析窗口长度（默认 5）
  -m, --modules LIST   启用模块：cpu,io,mem,lock,syscall（默认全部）
  -p, --pid PID        仅观测指定进程（默认全系统）
  -o, --output PREFIX  报告文件前缀（默认 sysrca_report）
  -f, --format LIST    输出格式：json,md,yaml（默认 json,md）
  -c, --config FILE    阈值配置文件（key=value，见 configs/sysrca.conf）
  -b, --bpf-path DIR   BPF 对象目录（默认与可执行文件同级的 bpf/）
  -q, --quiet          不打印实时窗口信息
  -V, --version        显示版本

全部检测阈值（CPU 利用率、I/O P99、锁等待频率、缺页速率等 15 项）可通过 configs/sysrca.conf 调整，含义见 docs/USAGE.md。

输出示例

控制台实时输出（每窗口一行概览 + 异常告警）：

[窗口#3 07:37:30] CPU 94.8% 切换 559598 | IO 17 iops P99 5.4ms | 内存可用 95.2% | 锁竞争等待 9578ms | 系统调用 900794
  >> [warning] 锁竞争 | 锁实例 0xfe1c80（进程 stress-ng-mutex, tgid=3247）
     指标: 热点锁平均等待=0.08 ms 等待次数=119808 (23962 次/秒) 并发等待线程数=2
     根因: 进程 stress-ng-mutex 的 2 个线程集中争用同一 futex(0xfe1c80)... (置信度 70%)

JSON 报告中的一条异常记录（字段稳定，便于机器解析与评测）：

{
  "type": "锁竞争",
  "severity": "warning",
  "object": "锁实例 0xfe1c80（进程 stress-ng-mutex, tgid=3247）",
  "time_window": {"start": "2026-07-29 07:37:30", "end": "2026-07-29 07:37:39"},
  "key_metrics": {"热点锁平均等待": "0.08 ms", "热点锁等待次数": "119808 (23962 次/秒)",
                   "并发等待线程数": "2", "竞争锁等待总量": "46661.1 ms"},
  "evidence_chain": [
    "futex 跟踪：锁 0xfe1c80 窗口内等待 119808 次（23962 次/秒），平均 0.08ms（阈值 10ms）...",
    "该锁最大并发等待线程数 2（>=2 表明存在真实同时争用，已排除线程池空闲阻塞等待）",
    "等待线程 Top1：stress-ng-mutex(tid=3479) 等待 119810 次、累计 9578.9ms",
    "同期上下文切换 689401 次/秒，与锁等待相互印证（线程因抢锁失败被频繁挂起唤醒）"
  ],
  "suspected_root_cause": "进程 stress-ng-mutex 的 2 个线程集中争用同一 futex(0xfe1c80)...",
  "suggestion": "建议缩小临界区、拆分热点锁（分段锁/无锁结构），或用 perf lock ...",
  "confidence": 0.7
}

报告同时保留每个窗口的原始聚合指标（windows[].metrics），支持结论回溯复核； Markdown 版含诊断结论、异常明细与窗口概览表，YAML 版面向自动化流水线。

Web 可视化

python3 scripts/sysrca_web.py            # 默认扫描 output/ 下的 JSON 报告
python3 scripts/sysrca_web.py -d /path -p 8688

浏览器打开 http://127.0.0.1:8688：观测概览卡片、诊断结论、CPU/I/O/内存/锁/系统调用五维指标时间线，以及可逐条展开证据链与根因的异常明细。服务端仅用 Python 标准库，前端 ECharts 已离线打包，无需外网。

Web 可视化界面

异常判定与根因分类

异常类型	触发条件（任一，全部可配）	根因分类依据
CPU异常占用/调度延迟	利用率≥90%；调度P99≥10ms；切换≥4000/s/核	热点进程切出频率与占核数区分忙循环/线程竞争/调度延迟
I/O延迟抖动	P99≥50ms；平均≥20ms	队列深度区分设备拥堵/进程集中下发
内存抖动/OOM	OOM事件；可用<10%；majflt≥100/s；直接回收≥100ms；缺页≥5000/s且可用<20%	回收/换页/缺页风暴/OOM 分级，关联 Top RSS 进程
锁竞争	并发等待者≥2 且频率≥50/s 且（平均≥10ms 或竞争总量≥1s）	三重判据排除线程池空闲等待
系统调用热点	非等待型且窗口耗时≥2s；频率≥5万/s且占单核≥20%	文件I/O高耗时自动归类为I/O阻塞等待并与块层互证

判定叠加滑动基线 z-score（偏离≥3σ 写入证据链并提高置信度）；汇总结论做因果排序—— 锁竞争/内存压力/文件I/O等待引发的 CPU 升高会归因到资源类根因，CPU 异常视为伴生现象。详见 docs/DESIGN.md。

性能开销

指标	实测值（openKylin 6.6, 4C8G）
计算型基准吞吐（stress-ng cpu）	-0.05%
纯上下文切换微基准（最坏情况）	约 -29%（sched/raw_syscalls 挂载点固有成本，可 `-m` 关闭高频模块降低）
工具自身 CPU 占用	≈0（窗口间休眠）
工具自身常驻内存 RSS	约 5MB
内核 map 内存	有界（每 map ≤10240 项，<16MB）

复测方法：sudo ./scripts/overhead_bench.sh 30（A/B 对比，自动输出报告）。

多平台适配

openKylin 2.0+（内核 6.6）：评测目标环境，编译/运行/五场景/开销全部实测通过； install_deps.sh 已适配 nile 源的 clang/bpftool/stress-ng 依赖问题，无 bpftool 时自动使用内置 vmlinux.h 回退，无外网亦可编译
Ubuntu 20.04（内核 5.8）：开发环境，全功能实测通过（验证跨内核 CO-RE 能力）
架构：x86_64 实测；构建系统支持 arm64/riscv/loongarch 目标宏自动映射
内核要求：≥5.8 且开启 CONFIG_DEBUG_INFO_BTF（存在 /sys/kernel/btf/vmlinux）
权限：root 或 CAP_BPF + CAP_PERFMON + CAP_SYS_ADMIN

目录结构与文档

src/common.h        BPF 与用户态共享结构定义
src/bpf/            5 个 eBPF 内核态观测模块（CO-RE）+ 内置 vmlinux.h 回退
src/user/           用户态：加载采集(collector) / 检测引擎(detector) / 报告(report)
tools/              lockbench(锁竞争压测)、memhog(内存抖动压测)
web/                Web 可视化前端（ECharts 离线仪表盘）
scripts/            安装/场景复现/开销评测/openKylin虚拟机/Web服务/文档生成等脚本
configs/            阈值配置（key=value，全部可调）
docs/               文档、图表与赛题原文
output/openkylin-verify/           openKylin 实测报告原件
output/openkylin-verify/official/  赛题官方参考命令(180s)实测报告原件

文档	内容
docs/INSTALL.md	安装部署、openKylin 直接验证指南、评测虚拟机一键构建
docs/USAGE.md	参数说明、阈值配置、输出格式定义、判定逻辑
docs/DESIGN.md	架构设计、CO-RE 适配细节、准确性与开销设计、已知限制
docs/TEST.md	测试方法、场景复现说明、双环境与官方命令实测结果

常见问题

提示找不到 /sys/kernel/btf/vmlinux：内核未开启 CONFIG_DEBUG_INFO_BTF，请使用 openKylin 6.6 等自带 BTF 的内核
openKylin 上装不了 clang/llvm 元包：install_deps.sh 已自动回退安装 clang-17 并建立软链
没有可用的 bpftool：无需处理，构建自动使用内置的 openKylin 6.6 vmlinux.h （CO-RE 按运行内核 BTF 重定位，跨版本安全）；也可 BPFTOOL=/path/to/bpftool make -C src
openKylin 上 stress-ng/fio 装不上：场景脚本自动回退自带的 lockbench/memhog/ stress-ng –hdd；也可源码构建（stress-ng 0.17、fio 3.36 实测编译通过）
加载失败/权限不足：需 root 或 CAP_BPF+CAP_PERFMON+CAP_SYS_ADMIN
工具退出后内核有残留吗：无。退出时自动卸载全部 BPF 程序与 map（可用 bpftool prog list 复核）

已知限制

I/O 按进程归因取 block_rq_issue 时的当前任务，经页缓存的异步写回会归因到 kworker （direct I/O 与读路径归因准确）
锁观测覆盖 futex 族（pthread mutex/cond/rwlock 最终都走 futex），纯内核锁（spinlock/rwsem）竞争不在本版本范围
每任务缺页计数依赖 /proc 全局值，未做 per-task 缺页 eBPF 归因（开销权衡）
LRU map 满载时淘汰最久未更新项，极端多任务场景下长尾任务统计可能不完整（容量可调）

提交材料

文件	说明
项目说明书.docx	按官网模板撰写，含自动目录与 7 张图表
作品介绍PPT.pptx	按官网模板撰写，卡片式排版，作品演示页内嵌演示视频
演示视频.mp4	openKylin 虚拟机内实录（约 2 分 12 秒）
作品原创承诺书.docx	原创承诺书
提交说明.txt	提交材料清单与说明

致谢与开源协议

感谢 eBPF/libbpf 社区、openKylin 社区及 stress-ng、fio、Apache ECharts 等开源项目。

本项目以 GPL-2.0 协议开源（eBPF 内核态部分要求 GPL 兼容协议）。第三方组件引用情况见项目说明书”代码原创说明”章节。