KernelScope

KernelScope 是面向 openKylin/Linux 的本机性能异常观测与根因分析工具，支持 X86 与 aarch64 平台。系统使用 eBPF 与 /proc 采集内核和进程指标，覆盖 CPU、I/O、内存、锁竞争和系统调用 五类场景，并将异常检测、根因排序、关联事件聚合和证据输出组织为一条可复现的诊断链路。

内核观测 → 窗口化指标 → 异常检测 → 根因分析 → Incident 关联 → 结构化结果与证据

KernelScope 的目标是让每个异常结论都能回到具体时间窗口、进程或资源对象，以及被规则实际使用的观测值。工具输出示例见评测报告及 docs/example/。

核心亮点

本项目有如下核心亮点

一、双进程解耦架构，兼顾灵活部署与安全管控

本系统采用双进程架构，将不同职责与权限边界进行隔离。各进程可根据实际场景独立部署、升级和扩缩容，既能适配本地化、容器化等多种部署方式，也有利于实现细粒度的权限管理，降低模块耦合和安全风险。

二、RCA 规则与代码分离，构建可扩展的根因分析能力

将根因分析（RCA）规则从业务代码中抽离，通过统一的规则描述方式，组合多种计算算子、判断条件与分析公式。新增或调整分析规则时无需频繁修改核心代码，能够显著降低维护成本，并支持不同业务场景下的快速配置和能力扩展。

三、面向大模型的结构化输出，提升智能分析的准确性与可解释性

将指标、异常现象、计算结果、关联关系和分析依据组织为结构化数据，为大语言模型提供清晰、完整的分析上下文。在减少无效信息和模型理解偏差的同时，使大模型能够进一步生成更具体的根因判断、证据说明和处置建议，形成”规则计算 + 大模型推理”的协同分析模式。

系统能力

当前支持的场景

场景	主要观测	可定位对象	主要诊断方向
CPU 异常占用与调度延迟	线程 CPU、上下文切换、调度等待、run queue、load、用户栈	PID/TID、CPU、热点栈	用户态计算、syscall busy loop、锁竞争、运行队列过载、持续饱和
I/O 延迟抖动与阻塞	IOPS、吞吐、await、队列深度、利用率、P95/P99、热点 FD	设备、PID/TID、FD、路径	设备高延迟、队列饱和、同步刷盘、热点访问、阻塞读
内存抖动与 OOM 风险	可用内存、RSS/匿名页、缺页、回收、Swap、OOM	系统、PID、进程名	匿名页增长、缺页风暴、回收压力、Swap、OOM
锁竞争	Futex 等待次数和时长、等待线程、锁地址、用户栈	PID/TID、锁地址	热点 Futex、阻塞线程集中、长等待
系统调用热点与失败重试	调用速率、耗时、错误率、errno	PID/TID、syscall、errno	高频调用、相同错误重试、慢调用、阻塞 read

其它核心能力

• 覆盖五类典型异常。Collector 同时观测 CPU、I/O、内存、Futex 锁竞争和系统调用，原始指标按统一字段写入 9 个 CSV 文件。
• 从异常发现走到根因解释。Analyzer 利用版本化规则、多证据评分、反向证据和数据质量降权生成 rca-events.jsonl。
• 能够定位到具体对象。分析结果可关联 PID/TID、设备、路径、FD 代次、锁地址、系统调用和 errno，帮助用户从指标异常追踪到具体异常对象。
• 每个结论都可以回查证据。RCA 结果记录 Run、Window、Record 和观测值级 EvidenceRef，可通过 rca_result.evidence[] 回到原始采集记录核验。
• 把同一故障的相关异常组织为 Incident。系统根据实体关系和显式因果事实合并相关事件，并保留 source_event_id，避免把一条故障链拆成互不关联的告警。
• 采集层支持两类主流服务器架构。Collector 为 x86_64 和 aarch64/arm64 提供独立构建入口，并配有 CMake 配置检查和 smoke test。
• 提供可重复的功能与性能实验。Evaluation 包含 24 个正例、负例和混合场景，同时支持 baseline/instrumented 成对实验，产出 Ground Truth、校验报告以及 CPU、RSS、吞吐和 P99 样本。
• 具备完整的验证和结果查看入口。项目提供 Collector/Analyzer 构建、协议测试、单元测试和 Evaluation 测试；结果既可直接检查 JSONL，也可通过可选的 Web 页面查看。

系统有哪些组件

系统由两个核心进程和两个配套组件组成：

• Collector：以 root 运行，通过 eBPF 与 /proc 采集指标，并写入 CSV 和 Unix Socket。
• Analyzer：以普通用户权限运行，完成窗口校验、异常检测、RCA、Incident 聚合和 JSONL 输出。
• Web（可选）：只读展示 Run、异常和 RCA 报告，并提供可选的 LLM 深度分析。
• Evaluation：用于测试；编排异常场景，生成 Ground Truth，并校验功能与性能结果；不属于在线诊断链路。

Collector 与 Analyzer 的分离隔离了高权限采集和诊断规则。整体架构参见系统设计说明。

根因诊断原理

Detector 负责检测异常事件，而 RCA 再结合窗口历史解释为什么发生。RCA Engine 采用确定性领域规则，不依赖外部大模型。候选根因统一使用多证据评分，选出评分规则最高根因作为主因。评分规则为：

$R(C)=G(C)\times {[\sum _i{w}_i{E}_i-\lambda \sum _j{p}_j{X}_j]}^{+}R(C)\; =\; G(C)\backslash times\; \backslash left[\; \backslash sum\_i\; w\_i\; E\_i\; -\; \backslash lambda\backslash sum\_j\; p\_j\; X\_j\; \backslash right]^+$

具体评分逻辑参考参数与配置说明：判定、状态与能力边界。

每个完成态根因必须引用同一结果中的证据。基线或异常区间不完整、窗口断档、记录丢失等情况会降低数据质量因子和置信度；降权后候选未达到阈值时，结果降级为 insufficient_evidence，不会生成伪主因。具体参见 RCA Engine 设计说明：执行流程和 RcaResult 状态定义。

规则包在 Analyzer 启动时完成 schema 校验、兼容性检查和 SHA-256 摘要计算，并冻结为不可变快照。结果会保存 Engine 版本、Rule Pack 版本和摘要，因此同一输入和同一规则快照能够得到可重复核验的结果。

快速开始

1. 环境

推荐环境：

• openKylin 2.0 SP2 或兼容 Linux；
• Linux 6.6+，并提供 BTF、所需 tracepoint/kprobe 和 BPF 能力；
• x86_64 或 aarch64/arm64；
• 复现环境建议至少 4 核 CPU、8 GiB 内存和 50 GB 存储空间；
• Collector 使用 root，Analyzer 使用具有 Socket 和输出目录权限的普通用户。

安装常用构建依赖：

sudo apt update
sudo apt install -y \
  clang llvm bpftool libbpf-dev libelf-dev zlib1g-dev \
  gcc g++ make cmake pkg-config nlohmann-json3-dev python3

运行前检查：

test -r /sys/kernel/btf/vmlinux && echo "BTF OK"
uname -m
sudo bpftool feature probe kernel

完整要求见安装部署与使用说明和适用范围与兼容性说明。

2. 构建与离线测试

make
make workloads
make check

命令	作用
make	构建 Collector 和 Analyzer
make collector	构建 build/bin/sys_monitor
make analyzer	构建 build/bin/kernelscope-analyzer
make workloads	构建 build/workloads/*
make check	运行 Analyzer、Evaluation 和窗口协议测试
make clean	清理 build/

根 Makefile 通过两个独立 CMake 子工程构建 Collector 和 Analyzer。

3. 一键启动在线诊断

仅启动 Collector 与 Analyzer：

make run

同时启动 Web 结果页：

npm --prefix web/frontend ci
npm --prefix web/frontend run build
make run-web

输出目录、Socket、采样间隔以及 Web 监听地址和端口均可通过 RUN_ARGS 配置，例如：

make run-web RUN_ARGS='--interval 2 --web-host 127.0.0.1 --web-port 9000'

Web 的“AI 深度分析”是可选能力。如需使用，应在启动前配置模型环境变量；未配置时不影响核心诊断和只读结果展示。

export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_RCA_MODEL="Deepseek-v4-Pro"
make run-web

make run 和 make run-web 会统一构建并启动进程、申请 Collector 所需权限、创建本次运行目录，并在退出时按顺序停止 Collector、刷新 Analyzer 中未关闭的 Incident。启动参数见安装部署与使用说明：便捷命令与启动参数，模型变量见参数与配置说明：LLM 深度分析。

运行被测负载时，应保留足够的基线、注入和恢复窗口。按 Ctrl+C 停止后，终端会打印本次运行目录。

4. 查看结果

启动脚本默认将每次运行写入独立目录，并在终端打印实际路径：

results/live/<timestamp>-<pid>/
├── collector/
│   ├── cpu.csv
│   ├── cpu_hotspot.csv
│   ├── io.csv
│   ├── io_latency.csv
│   ├── io_hotspot.csv
│   ├── memory.csv
│   ├── lock.csv
│   ├── syscall.csv
│   └── syscall_error.csv
├── analyzer/
│   └── rca-events.jsonl
└── logs/

将脚本打印的路径赋给 RUN_DIR 后，可查看最近一条完整结果：

RUN_DIR="results/live/<timestamp>-<pid>"
tail -n 1 "$RUN_DIR/analyzer/rca-events.jsonl" | jq .

查看主因与置信度：

jq -c '{
  result_id,
  run_id,
  status: .rca_result.status,
  cause: .rca_result.primary_cause.cause_type,
  confidence: .rca_result.primary_cause.confidence
}' "$RUN_DIR/analyzer/rca-events.jsonl"

rca-events.jsonl 在异常达到触发条件且 Incident 关闭或连接结束刷新后写入；文件暂时为空不等价于部署失败。

使用 make run-web 时，终端还会打印 Web 地址，可直接浏览 Run、异常和报告。Web 仅是展示入口，正式评测仍以原始 Event Log、Ground Truth 和自动校验文件为准。详见Web 结果查看说明。

一键复现五类场景

Evaluation 提供 24 个正例、负例和混合用例。e2e profile 使用真实 Collector 与 Analyzer，覆盖五类正向场景及典型负例：

sudo mkdir -p /mnt/osic-test
sudo chown "$USER":"$USER" /mnt/osic-test
sudo -v

make all workloads
OSIC_IO_DIR=/mnt/osic-test ./evaluation/run-suite e2e

典型 Run 目录包含：

results/evaluation/<run-id>/
├── command.txt
├── ground-truth.json
├── timeline.jsonl
├── collector/
├── analyzer/rca-events.jsonl
├── collector-validation.json
├── analyzer-validation.json
├── analyzer-validation.md
├── performance-samples.csv
├── performance-summary.json
└── performance.svg

严格模式会校验 CSV、Window Contract、RCA Envelope、主根因、目标实体和 Evidence 引用；必要检查失败时命令返回非零。

压力用例只能在专用、可恢复环境运行。I/O 用例只操作 OSIC_IO_DIR 下的普通文件，高内存和 cgroup/OOM 场景应先阅读 Evaluation 运行手册。

性能影响评测

项目使用成对实验区分系统本身的异常指标与 KernelScope 带来的额外影响：

• baseline：只运行 workload
• instrumented：运行 Collector + Analyzer + 相同 workload

一键采集 CPU、I/O、内存和锁场景的 A/B 数据：

sudo -v

OSIC_OFFICIAL_FIO_FILE=/mnt/osic-test/fio-test.img \
tools/official_benchmark_suite.sh \
  --case all \
  --duration 180 \
  --strict-capture

性能测试报告见评测报告。

平台适配

Collector 通过架构兼容层和 CMake 目标参数支持：

make collector ARCH=x86
make collector ARCH=arm64

系统调用号和 eBPF 目标宏在 Collector 层适配；上层 Metric Record、Window 协议、Detector、RCA Rule Pack 和 Evidence 结构保持架构无关。详见多平台适配说明。

项目结构

KernelScope/
├── collector/          eBPF 与 /proc 采集、CSV/Socket Writer
├── analyzer/           Window、Detector、RCA、Incident、Event Log
├── shared/             类型化指标和窗口协议模型
├── rules/rca/v1/       版本化 RCA Rule Pack
├── evaluation/         场景编排、Ground Truth、自动校验和性能采样
├── tests/              协议、Analyzer 和 RCA 测试
├── web/                Node.js REST 后端与 Vue 结果页
└── docs/               设计、部署、复现、评测与兼容性说明

其他必要说明

• 为了适用于团队协作，采用了 Git 裸仓库、上传分支，人工核对再合并入主线的协作方式，早期开发没有采用较为重量的 PR 协作方式。
• 为保证提交历史线形、清晰，团队推荐采用 rebase 方式进行分支合并，也使用了大量 squash merge，仅在必要时采用 merge 方式，因此当前 Git 提交历史是有意简化后的状态。
• 团队默认使用 markdown 格式管理文档。为保证通用性，通过 pre-commit hook 自动生成在提交关键文档变更时自动转化为 docx 格式。不过，受限于 docx 文档能力，部分格式转换可能出错，跨文档引用支持可能受限，因此仍然推荐基于 markdown 格式阅读文档。

文档导航

参赛材料

• 参赛承诺书：承诺书。

• 演示 PPT：KernelScope 项目介绍 及 PDF版

• 设计文档、技术报告：可参考项目说明书。

• 演示视频网盘：阿里云盘下载链接

  使用与复现

• 安装部署与使用说明

• 参数与配置说明

• 测试与复现说明

• Evaluation 运行手册

设计与接口

• 系统设计说明
• 两进程架构与接口规约
• Window Contract v0.1
• RCA Engine 设计说明
• RCA Rules v0.1

评测与适用范围

• Evaluation 模块设计
• 评测报告
• 适用范围与兼容性说明
• 多平台适配与 ARM64 验证说明
• Web 结果查看说明

组件手册

• Collector README
• Collector 代码指南
• Analyzer README