KernelScope

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

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

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

核心能力

覆盖五类典型异常。 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

Collector 以 root 运行，负责：

加载和挂载 eBPF 程序；
读取 eBPF Map、/proc 和系统接口；
计算窗口增量、速率、延迟分布和热点对象；
将统一的 Metric Record 同时写入 CSV 和 Unix Socket。

Analyzer

Analyzer 不加载 eBPF，可使用普通用户权限运行。它负责：

校验并组装完整的 Begin/Chunk/Commit 窗口；
维护连续窗口状态并识别异常；
固定基线窗口、异常区间和触发窗口；
执行确定性 RCA 规则和候选评分；
聚合相关异常并输出结构化 Event Log。

这种两进程设计将高权限采集与诊断规则隔离，采集、检测和 RCA 可以分别验证和演进。

关键设计

统一指标口径：CSV 与在线分析消费同一份类型化 Metric Record，避免重复解析产生口径差异。
完整窗口提交：只有通过身份、顺序、字段和计数校验的窗口才能进入 Detector。
规则与代码分离：通用 Feature、算子和评分由 C++ Engine 实现，候选根因、阈值和权重由 JSON Rule Pack 管理。
证据优先：证据不足时输出 insufficient_evidence，不补造确定性主因。
关联而非简单合并：Incident 依据实体关系和因果事实聚合，时间接近本身不构成同一根因。

支持的五类场景

场景	主要观测	可定位对象	主要诊断方向
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

根因诊断原理

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

$R(C) = G(C)\times \left[ \sum_i w_i E_i - \lambda\sum_j p_j X_j \right]^+$

具体评分逻辑参考参数与配置说明

每个完成态 Cause 必须引用同一结果中的 Evidence。Evidence 至少包含：

run_id
window_id
domain / record_type
selector
observed

规则包在 Analyzer 启动时完成 schema 校验、兼容性检查和 SHA-256 摘要计算，并冻结为不可变 RuleSnapshot。结果 Envelope 保存 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

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

命令	作用
`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/`

3. 启动在线诊断

终端 A，先启动 Analyzer：

./build/bin/kernelscope-analyzer \
  --listen /tmp/kernelscope-window-v01.sock \
  --config analyzer/detector/detector.conf \
  --rca-rule-pack rules/rca/v1/pack.json \
  --output results/analyzer

终端 B，再启动 Collector：

sudo ./build/bin/sys_monitor \
  -o results/collector/run-001 \
  -i 1 \
  -s /tmp/kernelscope-window-v01.sock

运行被测负载并保留足够的基线、注入和恢复窗口。停止 Collector 后，Analyzer 会刷新仍开放的 Incident。

4. 查看结果

Collector 原始数据：

results/collector/run-001/
├── cpu.csv
├── cpu_hotspot.csv
├── io.csv
├── io_latency.csv
├── io_hotspot.csv
├── memory.csv
├── lock.csv
├── syscall.csv
└── syscall_error.csv

Analyzer 结构化结果：

results/analyzer/
└── rca-events.jsonl

查看最近一条完整结果：

tail -n 1 results/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
}' results/analyzer/rca-events.jsonl

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

可选 Web 页面用于浏览 Run、异常和报告。页面是展示入口，正式评测仍以原始 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 格式管理文档，为保证通用性，使用 CI/CD 在提交关键文档变更时自动转化为 docx 格式。不过，受限于 docx 文档能力，部分格式转换可能出错，也不支持跨文档引用，因此仍然推荐基于 markdown 格式阅读文档。