目录
- .github增加质量门禁和发布自检1个月前
- anomdiag优化参赛展示与诊断结果页面3天前
- bpftrace适配Debian内核OOM观测事件1个月前
- docs说明高分冲刺轻量模式边界1个月前
- examples补强诊断低开销契约1个月前
- platforms增强调用栈证据覆盖矩阵1个月前
- plugins完善插件扩展模板1个月前
- schemas补强诊断低开销契约1个月前
- scripts集成参赛量化评测与提交校验3天前
- tests集成参赛量化评测与提交校验3天前
- .gitattributes完善跨系统换行策略1个月前
- .gitignore初始化异常根因诊断项目结构2个月前
- LICENSEInitial commit2个月前
- README.en.md初始化异常根因诊断项目结构2个月前
- README.md提交初赛作品材料2天前
- install-and-run.sh完善真实模式一键依赖准备1个月前
- install.sh统一安装后的轻量跑通提示1个月前
- pyproject.toml初始化异常根因诊断项目结构2个月前
- run.sh集成参赛量化评测与提交校验3天前
- 操作系统开源创新大赛 作品原创承诺书.jpg提交初赛作品材料2天前
- 操作系统开源创新大赛项目说明书-AnomDiag.docx提交初赛作品材料2天前
- 演示ppt.pptx提交初赛作品材料2天前
邀请码
版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9
京公网安备 11010802047560号
ebpf-anomaly-rootcause
ebpf-anomaly-rootcause是一个面向 Linux/openKylin/openEuler 的系统异常观测与根因定位工具。项目用 Python 组织诊断流程，结合 procfs 与 bpftrace/eBPF 采集 CPU、I/O、内存、锁竞争和系统调用信号，并输出 JSON、完整 Markdown 报告和更容易阅读的中文摘要报告。参赛快速入口
已有项目目录：一条命令完成真实测试并启动报告服务
项目已经下载到 Linux 服务器时，使用下面这一条命令。
--skip-install表示复用当前目录，不会再次克隆仓库；脚本会检查环境、复用已经安装的依赖，只补充缺少的运行条件，然后执行真实 Linux 主机闭环并生成报告。运行完成后，主要产物位于：
直接在 Linux 终端查看摘要：
云服务器没有桌面：在 Windows 浏览器查看报告
报告生成和测试都在 Linux 云服务器上进行，Windows 只负责通过 SSH 安全通道显示报告。报告服务只监听服务器的
127.0.0.1，不需要开放云服务器的18081安全组端口。在 Windows PowerShell 执行（不要在 Linux 服务器终端执行）：
输入密码或使用 SSH 私钥后，窗口保持不动表示通道正在工作。保持 PowerShell 窗口开启，在 Windows 浏览器访问：
查看结束后，在 PowerShell 中按
Ctrl+C关闭通道。如果服务器重装后出现
REMOTE HOST IDENTIFICATION HAS CHANGED，先通过云平台控制台核对服务器当前 SSH 指纹；确认服务器身份无误后再执行：随后重新建立 SSH 通道。不要在未核对指纹时直接忽略该安全警告。
真实运行结果解读
一次完整报告不是只输出“发现异常”，而是按照“结果摘要 → 异常排序 → 主因排序 → 诊断详情 → 证据链 → 优化建议”组织。当前归档的真实运行结果展示了以下诊断闭环：
1. 先给出主因，再展示多异常排序
futex/互斥锁竞争，综合置信度为0.95。562.0，高于 CPU 和系统调用候选；排序同时考虑严重程度、置信度、证据丰富度和因果支持，不只依赖单项指标。2. 锁竞争定位到进程、线程和资源对象
lock_contention。hbrclient / PID 552 / TID 594。bpftrace。futex_wait_queue关联，并保留候选线程、等待次数、热点函数和原始证据字段。0.95综合置信度。3. 系统调用错误模式关联到具体进程
AliYunDunMonito / PID 1352 / TID 1358。read/EAGAIN、futex/ETIMEDOUT等模式按调用次数聚合，同时区分目标进程与背景噪声。4. 与赛题结构化输出要求的对应关系
上述结果来自真实 Linux 主机运行报告。不同主机的进程、线程、指标和根因会随当时负载变化；README 只说明当前归档结果，不把它替代为 openKylin、其他架构或其他内核版本的真机证明。
参赛材料
演示ppt.pptx操作系统开源创新大赛项目说明书-AnomDiag.docx操作系统开源创新大赛 作品原创承诺书.jpgdocs/testing_zh.mddocs/final_delivery_zh.md演示视频及参赛材料网盘下载
GitLink 平台暂不支持在 Web 端解析 Git LFS 大文件，因此演示视频不通过 Git LFS 或普通 Git 提交。完整初赛材料已上传至百度网盘：
第三届中国研究生操作系统开源创新大赛 暨开放原子大赛操作系统专项赛 初赛作品4d17网盘内容包括：
仓库根目录保留 README、源代码、演示 PPT、项目说明书和原创承诺书；演示视频仅通过上述网盘链接提供。
当前能力
anomdiag diagnose：执行采集、规则分析和报告生成，输出结构化根因诊断结果。anomdiag summarize：把 JSON 诊断结果转换成中文可读摘要，方便直接查看和答辩展示。anomdiag doctor：检查 bpftrace、stress-ng、fio、tracefs/procfs 等运行环境。anomdiag install-deps：打印或执行当前 Linux 发行版的依赖安装命令。--dry-run：在没有 eBPF 权限的开发机上验证完整流程。cpu、io、memory、lock、syscall、all。JSON、YAML、Markdown、HTML输出；报告包含异常类型、关联进程/线程、关键指标、时间窗口、疑似根因、证据链、建议结论和主因排序。scripts/acceptance_matrix.py会根据报告和证据目录生成acceptance_matrix.json与acceptance_matrix.md，把评分项拆成“已验证 / 部分验证 / 待真机 / 未通过”。procfs基线模式，在没有 bpftrace 时也能给出诊断结果。目录结构
安装
各系统一键安装、运行并生成报告
脚本会先检查
git、Python、虚拟环境等基础工具；已安装的工具会直接复用，只安装缺少的依赖。随后自动运行 CPU、I/O、内存、锁竞争和系统调用诊断，并生成 HTML、Markdown、JSON 和 YAML 报告。Ubuntu / Debian / apt 系统
查看结果：
openKylin
查看结果：
openEuler / Anolis / Fedora / RHEL / Rocky / AlmaLinux
查看结果：
openSUSE / SUSE
查看结果：
已经下载源码
查看结果：
报告默认位于
/opt/anomdiag/reports/one-command-real/，优先查看：图形桌面中可以直接打开完整 HTML 报告：
无图形桌面时，建议只在服务器回环地址启动报告服务：
随后按照前文“云服务器没有桌面”的方法建立 SSH 通道并访问报告，不需要对公网开放报告端口。
通用安装入口
刚初始化好的 Linux 云服务器也可以用一条命令只部署代码和依赖：
如果希望新系统从零安装并立刻跑出一份验证结果，使用一条完整命令：
该命令会拉取项目、安装系统依赖、准备 Python 环境、尽量安装 bpftrace/stress-ng/fio 和 Docker/Podman，然后运行真实 Linux 主机闭环。报告输出到
reports/one-command-real。如果项目代码已经在当前目录，只想运行轻量验证：
可选模式：
如果系统还没有
curl，先装curl，或用：默认安装到
/root/ebpf-anomaly-rootcause-gitlink，会拉取master分支并执行bash run.sh init --yes。需要改目录时：最简方式只需要记住根目录的
run.sh：参赛量化评测使用统一入口：
默认对五类标准场景重复运行 3 轮，输出异常识别准确率、精确率、召回率、误报率、漏报率、根因 Top-1 命中率、进程/资源对象命中率、证据链覆盖率，以及 CPU、内存、平均时延、P99 和吞吐影响。结果位于：
只验证评测程序和报告结构时使用：
如果只想先确认项目能不能跑起来，优先执行：
它会生成
reports/smoke/打开报告.html、结构化诊断结果和 schema 校验摘要，适合 2C2G 云服务器或刚换系统时先看闭环。等环境稳定后，再运行：这一步用于补真实 Linux 主机证据，包括真实采集、业务影响、调用栈、容器边界和验收矩阵。
新 Linux 机器上推荐先使用一键初始化入口：
默认只打印系统依赖安装计划，并自动创建
.venv、安装 Python 包、运行基础自测和 dry-run 验证。如果确认允许脚本安装系统依赖：也可以手动安装：
在 openKylin/openEuler/Ubuntu 真机或云服务器上采集 eBPF 信号时，建议先检查环境：
如果想先看“当前机器下一步该跑什么”，生成环境指纹：
其中
startup_plan会给出就绪等级、推荐命令、阻塞项、缺失工具、容器就绪状态、缺失 tracepoint 数量和可安全宣称边界。如果确认要自动安装依赖：
容器真测需要 Docker 或 Podman。默认先生成安装计划，不会改系统：
确认要安装并启动运行时时再执行：
已有 Docker/Podman 后可直接跑容器闭环：
生成可迁移源码包：
打包产物会放在
dist/，解压后执行bash run.sh init即可在新系统初始化。不同系统的真机验证接口已预留在
platforms/目录。后续重置服务器或切换到 openKylin、openEuler、Debian、Anolis、ARM64、RISC-V、Kernel 6.6+ 环境时，只需要在目标系统运行：再把
doctor.txt、acceptance_matrix.md、latest_summary.md等结果放到对应平台目录即可。评分项完成度与证据边界
install-and-run.sh、run.sh real、五类 demo、平台和容器验证脚本docs/testing.md、docs/testing_zh.md、自动化测试和示例输出当前代码和报告链路可以复现与评审，但“代码能力已实现”不等于“对应平台或量化分值已经取得”。提交前优先补 openKylin Kernel 6.6+ 真实闭环、准确率统计和长时间性能开销三类证据。
快速看到结果
如果只是想快速看到一组可展示产物：
它会调用轻量
quick流程，生成 5 类异常 dry-run 诊断、JSON/YAML/Markdown/HTML 输出、中文摘要、验收矩阵和schema_check.md/json。最适合刚迁移到新系统、2C2G 云服务器先跑通、或给评委快速复核入口。如果想直接生成默认快速演示目录：
它会生成 dry-run 诊断、scheduler 快速演示、中文摘要、HTML 报告、验收矩阵和一个统一索引，适合开发机或刚迁移到新系统时先验流程。若当前系统不支持真实 scheduler 采集，索引会保留缺失/待验证状态。
生成后最方便查看的是：
在云服务器或真实 Linux 主机上跑完整闭环：
该命令会执行 5 类基础异常、调度链路、业务影响测量、结构化总报告和验收矩阵，并生成
reports/real-host/打开报告.html。这是后续把 dry-run 证据替换成真实主机证据的主入口。高分冲刺自测入口：
默认使用轻量 quick 模式，适合 2C2G 服务器先验证完整链路；最终答辩机器上建议运行：
默认命令会串联快速五类异常、低开销业务压测、容器补测入口和平台补测入口，并输出
reports/score-sprint/score_sprint.md、reports/score-sprint/score_sprint.json、reports/score-sprint/score_sprint_schema_check.md与reports/score-sprint/score_sprint_schema_check.json。--full才会额外重跑最终 review/提交材料链路。container_retest在没有 Docker/Podman 的环境中可能显示needs_review，这表示容器真测待 Linux 容器环境补证，不代表轻量链路失败。score_sprint摘要会同步读取reports/showcase/evidence_maturity.json，显示证据成熟度、弱项数量和下一步真机补证动作。最适合演示的一条命令：
脚本会自动制造一个 CPU 压力场景，运行 CPU 诊断，并在终端打印
reports/latest_summary.md的中文可读摘要。输出文件包括：内存压力演示：
默认参数会使用较保守的内存压力，适合 2 核 2G 云服务器先跑通。输出文件包括：
I/O 延迟抖动演示：
脚本会启动随机读写压力，运行 I/O 诊断，并生成中文可读摘要：
如果已经有 JSON 诊断结果，也可以单独生成摘要：
调度延迟 / 运行队列压力演示：
输出文件包括：
常用命令
查看支持的诊断目标：
在任意开发环境验证流程：
采集 CPU 异常信号并输出 JSON：
采集内存压力信号并输出 JSON：
采集 I/O 延迟信号并输出 JSON：
输出完整 Markdown 报告：
输出 YAML 结构化报告：
输出 HTML 报告：
结构化诊断字段
diagnose输出会保留原始metrics和findings，同时增加diagnosis顶层字段，便于机器解析和人工复核：每条 finding 也会补充：
当前 CPU、内存、I/O 已能稳定形成真实闭环；CPU 已补线程级热点、热点函数和用户态栈样本，I/O 已补文件路径，锁竞争已补线程等待、wchan/futex 热点和 futex 栈样本，syscall 已补具体调用、错误码和慢调用栈样本；容器/cgroup 上下文、插件清单和 HTML 报告也已接入。
平台适配说明：当前已归档 Ubuntu x86_64 与 Debian x86_64 真实证据，其中 Debian 归档覆盖 Kernel 6.6+ 环境；openKylin、openEuler、Anolis、ARM64、RISC-V 走 procfs 基线兼容设计，eBPF 路径需要目标系统提供 tracefs/debugfs 与 bpftrace tracepoints。
anomdiag doctor会输出当前机器的架构、发行版、内核和兼容矩阵。旧命令
anomdiag run --target cpu仍然可用，diagnose是更适合比赛演示的别名。兼容性
procfs基线模式通常可用。--dry-run做流程开发；真实 eBPF 采集应放在 Linux 机器或云服务器上。异常复现
建议先启动对应复现脚本，再运行
anomdiag diagnose <target>采集诊断结果。锁竞争诊断示例：
开发
质量门禁一键复核：
该命令会串联 Bash 语法检查、pytest、ruff、轻量跑通、发布自检、最终评审链路和提交包复核，并生成
reports/ci-check/quality_gate_summary.md与reports/ci-check/submission_check.md/json，适合作为提交前的标准自测入口。CI 内部仍使用scripts/ci_check.sh。开销测量：
更多开发说明见 docs/development.md，测试与复现说明见 docs/testing.md。
答辩看板
比赛展示时建议优先运行：
它会基于 quick 证据生成一个中文最终演示页面，把五类异常定位、关键证据、验收矩阵、真实平台归档和现场复测命令汇总到一个入口。生成后优先打开：
其中
one_minute_review.md/json是评委一分钟摘要，快速展示结论、主因排序、评分点和必看材料；requirements_audit.md/json是最终要求逐项审计表，逐条说明完成状态、证据和待真机项；showcase_summary.json适合机器解析和复核，包含五类异常、主因排序、复核路径、评分点映射、业务影响、平台归档、关键产物和复现命令；showcase_check.md是最终演示材料完整性校验，要求未通过项为 0；schema_check.md/json是核心诊断 JSON 与演示交付 JSON 的 Schema 契约校验结果；submission_boundary.md/json用于解释“当前包可提交”与“仍有待真机补证项”之间的边界，列出可安全宣称和不应夸大的内容；scorecard.md/json是高分证据卡，汇总评分项证据强度、待真机项和复测命令；platform_test_plan.md/json是跨平台真机补测计划，列出 openKylin、openEuler、Anolis、Debian、ARM64、RISC-V、Kernel 6.6+ 的复测命令和归档目录；gap_audit.md/json是最终差距审计，集中展示已验证项、待真机项、不能夸大宣称和下一步冲刺命令；score_review.md/json是最终评分预审，按评分维度给出保守自评分、冲刺上限、扣分原因和满分条件；evidence_maturity.md/json是证据成熟度分级，按高分项标出可展示、当前系统较完整、真机可复核、跨平台增强和待补证状态；overhead_budget.md/json是低开销预算审计，集中复核平均延迟、P99、吞吐、CPU 和 RSS 是否在阈值内；provenance_audit.md/json是提交溯源审计，记录 git 版本、提交包 SHA256、关键报告哈希和新鲜度风险；evidence_timeline.md/json按 rank 汇总时间窗口、目标对象、关键指标、证据链和建议，便于复核“为什么这么判断”；final_runbook.md/json是最终答辩运行手册，包含 10 分钟演示流程、预期结果、证据路径和现场兜底；defense_script.md是答辩讲解稿，按演示顺序列出该说什么、打开哪些产物；evidence_manifest.json/md是带 SHA256 的证据清单；final_acceptance.json/md是最终提交验收结论；submission_index.json/md是提交包索引，说明每个关键文件的用途和查看顺序。container/container_readiness.md/json用于说明容器观测是否已经完成真实闭环。如果当前服务器没有 Docker/Podman/containerd，它会明确标记为待真机项，并列出通过标准和复测命令；只有目标容器进程、线程、cgroup CPU/memory 和证据链都命中时，才会标记为可以宣称真实容器闭环通过。生成最终比赛提交 zip：
产物会放在
dist/anomdiag-submission-<commit>.zip，包含最终看板、验收结论、提交索引、证据清单、讲解稿、结构化诊断报告和source/源码快照；同时生成*.check.md/json自检结果。提交包自检会复核 manifest、SHA256、源码快照、一键脚本、shell 便携性和source/.gitattributes换行策略。