KylinSight

基于 eBPF 的 Linux 系统异常观测与根因定位平台（第三届中国研究生操作系统开源创新大赛决赛作品）。

项目简介

KylinSight 通过内核态 eBPF 程序对系统运行队列延迟（RunQLat）、块 I/O 延迟、内存异常、Futex 锁竞争、系统调用热点五类观测点进行无侵入式采集，经用户态 Collector 统一上报至 Python 诊断服务，由规则引擎与根因关联器完成异常识别与根因定位，并通过 Web Dashboard 实时展示。

应用场景

云原生 / 服务器系统性能异常的可观测与快速定位；
CPU 调度延迟、I/O 抖动、内存异常、锁竞争、热点系统调用等问题的排查；
系统运维中的实时监控与历史回溯。

主要功能

五类观测模块：CPU/RunQLat、Block I/O、Memory、Futex Lock、Syscall Hotspot；
异常检测 + 根因定位（规则引擎 rules-v2 + 根因关联器）；
REST 接口 + SSE 实时推送 + Web Dashboard；
历史持久化（SQLite）与诊断报告导出；
一键决赛演示与证据包生成（scripts/run_final_demo.sh）。

目录结构

.
├── README.md               # 本文件
├── src/                    # 项目源代码（构建/运行均在此目录）
│   ├── README.md           # 源码级说明（架构、API、版本历史等）
│   ├── CMakeLists.txt      # Collector 构建配置
│   ├── pyproject.toml      # Python 项目与依赖配置
│   ├── api/  analyzer/  cli/  bpf/  collector/  scripts/  scenarios/  deploy/  configs/
├── docs/                   # 项目说明书、创新说明、分工、AI 工具使用说明（PDF）
├── tests/                  # 测试及验证材料（pytest 单元/契约测试）
├── demo/                   # 与赛道相适配的可验证交付物
├── presentation/           # 决赛现场演示 PPT 与演示视频
└── 作品原创承诺书.pdf

系统环境

操作系统：openKylin 2.0 / Ubuntu 22.04+；
内核：Linux 6.6+（需开启 BTF）；
权限：root。

依赖要求

编译工具：clang、gcc、cmake（≥3.16）、bpftool；
内核/用户态库：libbpf-dev、libelf-dev、zlib1g-dev、libzstd-dev；
Python ≥ 3.10，依赖清单见 src/pyproject.toml。

构建方法

cd src
sudo ./scripts/setup_env.sh   # 安装依赖并创建 .venv
./scripts/build.sh            # 编译 BPF 与用户态 Collector

运行方法

cd src
sudo ./scripts/start_kylinsight.sh
# 浏览器访问 http://localhost:8888/dashboard

一键生成完整证据包（兼容性事实、接口延迟、五类真实场景、发布门禁、准确率、误报/漏报、Doctor 检查）：

cd src
bash scripts/run_final_demo.sh --start-if-needed --base-url http://127.0.0.1:8888

测试方法

# 单元 / 契约测试（从仓库根目录运行；tests/conftest.py 会自动把 src/ 加入 import 路径）
python3 -m pytest tests/

一键验收与证据评估（需真实 eBPF 环境）：

cd src
bash scripts/run_kylinsight_acceptance.sh

已知限制

Memory、Block I/O、Futex Lock 三个观测模块为实验性，默认禁用，需真实 BPF Collector 才能启用；
真实 eBPF 采集依赖 root 权限与内核 6.6+（BTF），容器 / 受限内核环境下功能受限；
详见 src/README.md 的「已知限制」章节。

源码与架构细节：src/README.md；
提交文档：docs/；
可验证交付物：demo/。