Kausal Linux eBPF 诊断系统

Kausal 是面向 Linux/openKylin 的持续诊断程序：采集 CPU、内存、I/O、系统调用和锁证据，将原始指标经候选、事实、规则、事件和全局 RCA 流水线写成可追溯报告。

快速开始

./build.sh --clean
ctest --test-dir build --output-on-failure
bash demo/一键工程验收.sh

需要内核能力的验收使用 tests/tools/build/ci_local.sh --with-root --with-stress。持续服务安装见 docs/安装部署说明.md，五场景复现入口为 demo/一键五场景复现.sh。

项目目标与职责边界

项目负责本机诊断证据采集、规则判定、生命周期闭环、RCA 报告及安全压力验收。它不替代容量规划、应用业务追踪或跨主机 APM，也不会通过运行时目标注册直接制造异常结论。目标进程身份始终使用 PID + starttime；I/O、锁和 syscall 还验证各自对象身份。

功能概览

长期运行 kausal-diagnose.service，按需注册带 correlation ID 的场景目标并等待 ACK。
WindowSnapshot 汇总窗口原始指标，DomainFrame 描述领域数据质量，trace_reference 回指正式证据。
生命周期采用 START/UPDATE/END，并对拒绝、容量、水位、watchdog 与数据丢失分类观测。
后台自然异常位于 report/normal/<领域>/<日期>/i<incident>-<稳定哈希>/；report.json 按 kausal.diagnosis.report.v4.schema.json 输出精简结构化结果，所有展示时间为北京时间；summary.json 按 kausal.diagnosis.summary.v4.schema.json 只保留“综合分析结论”对象，其子字段和数组在 JSON 文件中直接物理分行；完整审计证据保存在同目录 evidence.json（diagnose.rca.timeline.v1）。
场景复现异常位于 report/scenarios/<场景>/<日期>/<场景运行标识>/i<incident>-<稳定哈希>/，同一运行目录只额外保存 operation.log，不生成 scenario-result.json。
内部 batch 位于 report/_internal/batches/<服务运行标识>/，仅用于服务运行级审计；其中 summary.json 是内部 diagnose.rca.summary.v1，不等同于 incident 摘要。

工程结构

CMakeLists.txt：项目构建入口及测试注册。
src/、src/include/：采集、诊断、生命周期和报告生产代码。
src/config/rule-coverage-manifest.json、src/config/stress-scenarios.json：规则和场景合同。
tests/stress/diag_stress.sh、tests/tools/build/stage12_acceptance.sh：压力复现与真实验收。
tests/python/stage8_perf_contract_test.py、tests/python/stage8_device_topology_contract_test.py、tests/python/timeline_report_validator_test.py：性能、拓扑和正式报告合同测试。

运行与配置

前台运行：sudo -E ./build/diagnose；有限窗口运行：sudo -E ./build/diagnose 10。环境变量的唯一完整清单见 docs/参数配置说明.md，常用项包括 DIAG_TARGET_PID、DIAG_REPORT_DIR、DIAG_INCIDENT_REPORT_UPDATE_MS、DIAG_WINDOW_MS 和 DIAG_GATE_SOFT_N。

真实五场景诊断可执行：

sudo -E ./tests/stress/diag_stress.sh run all --level diagnosis
python3 tests/performance/stage8_perf_harness.py summarize --input-dir /var/tmp/kausal-perf
python3 tests/tools/validation/stage8_device_topology.py --help
python3 tests/tools/validation/platform_capability_matrix.py probe --output report/platform/platform-capability-matrix.json

输出合同

持久化正式报告是 canonical incident 目录中的 diagnose.rca.timeline.v1。START 创建 ongoing revision，内容变化按配置节流更新，END 在同一目录立即写入 closed revision。报告验证 correlation、服务会话、PID/starttime、场景对象、允许规则、时间窗口、结论性、数据质量和 START/END。示例：

{
  "schema": "diagnose.rca.timeline.v1",
  "collector_session_id": 42,
  "report_status": "closed",
  "report_revision": 3,
  "runtime_target": {
    "request_id": "req-1",
    "correlation_id": "corr-1",
    "scenario": "cpu",
    "service_session_id": "boot:123:456",
    "mixed": false
  },
  "lifecycle_complete": true,
  "event_lifecycle": {"start_seen": true, "end_seen": true},
  "is_conclusive": true
}

详细字段、内部 alert 模型与正式落盘边界见 docs/系统设计说明.md；规则输入链见 docs/规则数据合同.md。

权限与安全

eBPF 加载、systemd 安装、内核日志读取和真实压力验收通常需要 root。脚本限制内存分配、保留安全余量且禁止故意 OOM；所有临时进程和运行时目标都必须清理。不要在生产主机上跳过预检或擅自降低阈值。

测试与验收

本地快速检查使用 tests/tools/build/ci_local.sh；完整顺序和真实验收合同见 docs/测试与复现说明.md。报告验证必须使用 tests/tools/validation/validate_timeline_reports.py 并指定目标领域。Python 命令统一设置 PYTHONDONTWRITEBYTECODE=1，避免污染提交。

文档索引

docs/安装部署说明.md
docs/使用说明.md
docs/参数配置说明.md
docs/系统设计说明.md
docs/平台能力矩阵.md
docs/评委可读摘要与因果图.md
docs/限制与已知问题.md
docs/测试与复现说明.md
docs/规则数据合同.md
docs/工程质量评审索引.md
docs/代码规范与贡献指南.md
docs/第三方组件与开源合规说明.md
docs/变更记录.md

限制与故障排查

内核能力、BTF、tracepoint、块设备与 systemd 环境差异可能导致明确跳过或降级；跳过项不计为通过。先查看 canonical report.json/summary.json、服务日志、场景 operation.log 以及数据质量字段；内部运行审计再查看 _internal/batches/<服务运行标识>/run-meta.json，详见 docs/限制与已知问题.md。

开源与第三方声明

项目许可证见 LICENSE。libbpf 等第三方来源、许可证和构建边界见 docs/第三方组件与开源合规说明.md；贡献流程见 docs/代码规范与贡献指南.md。