麒麟脉镜（OAS）

项目简介

机器变慢时，CPU、I/O 和内存指标往往一起变化。麒麟脉镜从内核事件入手，沿着“异常发生了什么、影响了谁、依据是什么”这条线索，把诊断结果落到具体的线程、进程或资源上。排查人员可以从根因候选回看窗口统计，再找到支持判断的事件和探针来源。

项目面向 openKylin，观察 CPU、I/O、Memory、Lock 和 Syscall 五类异常。日常运行可以保持较轻的采集范围；出现可疑活动后，自适应运行时围绕目标加深诊断，再逐步回到常态观测。

先看哪里

想了解的内容	入口
系统设计、实现与实验	项目说明书
主要技术贡献与对应代码	项目创新说明
决赛讲解与画面	演示 PPT、PDF 预览、演示视频
从源码跑一遍	演示脚本、下文的构建与运行步骤
测试入口和样本	tests/

应用场景与主要功能

传统监控擅长画出整机指标曲线，但曲线升高之后，仍需在多个工具之间寻找进程、内核事件和异常机制的联系。OAS 把采集、窗口聚合、异常判断、实体归因和根因排序放进同一条诊断链。报告不仅给出结果，还记录指标、测量方式、阈值来源、候选实体和证据状态。

领域	主要观察内容	常见定位对象
CPU	运行时间、调度等待、唤醒到运行的时延	线程、进程、cgroup
I/O	请求发出与完成、吞吐、尾部时延	设备、请求及提交进程候选
Memory	缺页、回收、写回与内存压力	进程、cgroup、系统回收线程
Lock	futex 等待与唤醒、等待次数和时长	等待线程、持有者候选、锁地址
Syscall	调用次数、错误、时延和短时热点	系统调用号、线程与进程

五类事件使用统一的时间与身份字段。遇到异步 I/O 或后台回收一类难以精确归属的活动，报告会保留候选和证据边界，让目标进程与外部系统活动分开呈现。

总体架构

麒麟脉镜总体架构图

架构图中的 A 到 D 是数据路径，E、F 分别管理采集深度和平台能力；蓝色实线表示数据流，橙色虚线表示控制流。

内核采集（A）：五类 eBPF 探针从 tracepoint、kprobe 等挂接点取得事件，借助 BPF map 保存必要状态，通过 ring buffer 把需要逐条解释的记录送到用户态。
传输与整理（B）：libbpf 会话接收事件，统一时间、身份、采样和测量字段。事件存储与窗口聚合生成统计快照，保留诊断所需的实体和事件引用。
分析与定位（C）：检测器识别异常，系统按线程、进程、cgroup 或资源生成候选实体。C Runtime 排序器结合偏离程度与证据质量，给出根因候选及排序理由。
证据与报告（D）：finding 关联到窗口快照、原始事件和 probe/hook 来源。命令行输出 JSON、YAML 或 Markdown，也可导出 Prometheus 指标。
自适应运行（E）：运行时根据可疑活动调整目标范围、采样和采集预算，在低开销观测、定向诊断、深度诊断及冷却阶段之间转换。
平台适配（F）：启动时探测内核挂接点、BTF 等能力，选择可用的探针路径，并将降级状态写入报告。配置、规则、Schema 和测试工具为整条链路提供支撑（G）。

从内核事件到诊断报告

内核态到用户态的数据流

从探针捕获事件到生成报告，数据依次经过内核态状态维护、ring buffer 传输、用户态规范化、事件存储、窗口聚合与分析。需要逐条解释的记录会进入事件存储；高频指标可以先在内核侧聚合。图中的每一步都对应一次明确的数据处理，便于从最终报告回看采集来源。

异常检测与根因定位

多检测器融合流程

OAS 将 event、窗口聚合快照、finding 和最终 report 分开建模。高频事件可以先聚合，但聚合结果不会被写成一条不存在的原始事件。这样一来，报告里的引用可以回到实际保存的事件或快照。

检测层结合固定阈值、Z-score、中位数绝对偏差（MAD）、CUSUM 等方法。每种方法先检查输入是否有效，再记录自己在本次判断中的贡献：使用了什么基线、触发了什么条件、为何跳过或使用后备方法。根因排序先生成与异常类型相符的实体候选，再结合证据完整性、关联关系与可追溯性给出稳定的 Top-1、Top-3 结果。

端到端证据链

Memory 定向诊断还检查当前访问窗口中的新鲜证据。报告能区分这次访问真正采到的事件与先前窗口留下的记录。沿着一条 finding，可以查到其证据状态、窗口快照、原始事件与探针来源；图中最后的记录环节对应本次运行及交付文件的身份校验。

自适应运行

自适应运行时状态机

不同任务需要不同的采集深度。长期观测优先控制事件量；短时取证则可以围绕可疑实体提高细节。运行时从 LOW_OVERHEAD 出发，在分数与停留时间达到条件时自然进入 TARGETED，必要时继续进入 EXHAUSTIVE。回落受 hysteresis、cooldown 和资源预算约束；运行时通过控制映射调整作用域，并复用已加载的采集会话。

配置	用途
low_overhead.yaml	长时间低开销观测
openkylin.yaml	openKylin 上的综合观测
full_diagnosis_controlled.yaml	已知目标的短时受控诊断
full_diagnosis_progressive.yaml	根据证据逐步加深或退出诊断
full_diagnosis_exhaustive.yaml	明确时间范围内的深度取证

系统环境与依赖

项目主要在 Linux/openKylin 上构建和运行。平台能力矩阵记录了 x86_64、ARM64、RISC-V 的已验证范围；实际可挂接的探针还取决于当前内核提供的 BTF、tracepoint 和 kprobe 等能力。

基础构建与测试需要 GCC、Make、pkg-config、Python 3 和 Bash。
实时 eBPF 构建还需要 Clang/LLVM、libbpf、libelf、zlib、zstd 及其开发头文件；bpftool 可生成匹配当前内核的类型头文件。
实时采集需要支持 BPF 的 Linux 内核和相应加载权限。确定性演示不加载 BPF，可以先用于熟悉报告格式。

在使用 apt 的 openKylin 环境，可以先安装常用开发包；包名如随发行版变化，以本机软件源为准：

sudo apt update
sudo apt install build-essential pkg-config python3 clang llvm \
  libbpf-dev libelf-dev zlib1g-dev libzstd-dev

bpftool 可单独安装；缺少它时，构建脚本会按仓库中的 min_core.h 路径处理。检查工具链和头文件：

make check-deps

安装与构建

克隆仓库后，在项目根目录执行：

make -j2

项目不要求安装到系统目录；构建产物放在 src/dist/，可直接从这里运行。make 优先构建实时 BPF 程序和用户态程序；如果机器缺少实时构建依赖，它可能只生成演示版，或者在已有受支持产物时使用仓库提供的预构建文件。要明确构建当前源码的普通实时版本，请在依赖齐全时运行：

make -C src build
ls src/dist/oas src/dist/bpf/*.bpf.o

应得到用户态程序和五个 BPF 对象。编译和运行发生在同一目标机时，BPF 架构参数由构建脚本依据 uname -m 选择。

运行方法

先看命令行选项，再用确定性演示熟悉报告：

./src/dist/oas --help
make demo
# 或
bash demo/run.sh

演示约运行 5 秒，在终端输出 JSON 报告；它不加载 BPF。需要观察当前机器的真实内核活动时，请使用 live 模式：

sudo ./src/dist/oas --mode live --duration 30 --format json \
  --config src/configs/openkylin.yaml \
  --bpf-dir src/dist/bpf --out /tmp/oas-report.json

JSON 报告写入 /tmp/oas-report.json，相邻的 /tmp/oas-report.raw-events.ndjson 保存本次原始事件。看一条 finding 时，可以依次核对异常类型与时间窗口、实体身份、测量和阈值来源、根因候选，以及 trace_refs 和 evidence_chain 中的引用。

只读 Web 面板

页面源码位于 src/web/。它展示已有的验证摘要和平台能力，不会从浏览器启动 live 任务。完整证据数据在位的工作树可从项目根目录启动：

python3 src/web/serve.py --host 127.0.0.1 --port 4173

浏览器访问 http://127.0.0.1:4173/。当前精简提交主要保留页面、接口和验证工具；页面所读取的冻结证据 JSON 需与 src/web/serve.py 中的路径一同提供。

测试方法与验证材料

make test

在项目根目录运行此命令。测试包括 C 单元逻辑、事件 ABI、状态转换、负载协议、测量语义及报告校验。想先确认基本演示入口，可运行 make demo；要验证真实内核采集，则需要在具备 BPF 权限和相应内核能力的 Linux 主机上运行前述 live 命令，检查输出报告及原始事件。需要查看输出字段时，可从诊断报告 Schema 和根因排序 Schema 入手；规则与阈值配置在 src/rules/ 和 src/configs/。

决赛阶段的系统设计、实验口径和结果写在项目说明书，主要创新与对应代码、验证依据写在项目创新说明。不同架构的实际挂接能力以平台矩阵和运行报告为准。

项目文件

README.md        项目介绍、环境依赖、安装、构建、运行与测试入口
src/             用户态程序、五类 BPF 探针、配置、规则、Schema 和 Web 页面
tests/           单元测试、协议测试、测试输入和场景脚本
demo/            一键演示脚本与说明
docs/            项目说明书、创新与分工材料、工具声明及架构图
presentation/    决赛演示 PPT、PDF 和 MP4 视频

已知限制

内核版本与架构提供的挂接点并不完全相同。ARM64 的部分 Memory 路径会标记为 PARTIAL_FALLBACK；RISC-V 的部分 Syscall 兼容入口只记录活动，不提供返回值与时延测量。
事件密集时，要结合报告中的采样、丢失和降级字段解读结果。异步 I/O、后台回收、短生命周期进程及符号化结果也受现场证据和权限条件影响。
深度诊断适合短时取证；持续观测可选用 low_overhead 或 balanced 配置。

许可证

项目许可证见 LICENSE，第三方组件及使用边界见 THIRD_PARTY_NOTICES.md。