KOSMOS：基于 eBPF 的系统异常观测与根因定位工具

从一次短暂的系统抖动出发，沿着时间窗口、进程线程和资源对象还原证据链，给出可复核的根因判断。

KOSMOS 是一套基于 eBPF 的系统异常观测与根因定位工具，覆盖 CPU、I/O、内存、锁竞争和系统调用热点 5 类异常。项目除了识别异常指标，还会继续回答“异常发生在哪个窗口、影响哪个进程或线程、由哪些指标共同证明、当前证据是否足以形成结论”。

场景覆盖	观测能力	诊断方式	运行与适配
5 类标准异常	14 个观测子系统	版本化规则 + 可选 AI 第二意见	Linux 6.6+、eBPF CO-RE
系统级到线程级	聚合、目标跟踪、短时明细	JSON 结构化报告与前端展示	amd64、ARM64 构建检查

项目定位

传统监控通常止步于 CPU 使用率、磁盘时延或可用内存等单点指标。真实故障却往往跨越多个内核子系统：CPU 占用升高可能是用户态计算热点，也可能是运行队列拥堵；I/O 时延升高可能来自设备服务时间，也可能由写回压力或调度阻塞放大。

KOSMOS 将一次诊断组织为完整链路：

异常症状
  └─> 同一时间窗口内的多子系统指标
       └─> PID / TID / 设备 / 文件 / 锁实例
            └─> 症状、机制、根因、佐证四类证据
                 └─> 可回溯的诊断结论与处理建议

例如面对“CPU 持续高于 90%”，系统会继续关联运行队列、线程调度等待、上下文切换和热点采样，区分用户态计算热点、内核热点、多线程饱和与调度竞争，并把命中的窗口、阈值和关联线程写入报告。

项目亮点

1. 从单项指标扩展到跨子系统关联

5 类场景通过共享场景契约组织为关联分析链路：

• CPU 场景联合 cpu、sched、runq 和 profiling，定位饱和核心、热点线程与函数；
• I/O 场景贯通块层、VFS、页缓存、内存 PSI 和调度证据，区分队列拥堵、设备服务异常与热点文件；
• 内存场景关联容量、进程内存、缺页、直接回收、kswapd、OOM 和线程停顿；
• 锁竞争场景关联 mutex/futex 生命周期、锁地址、等待者、持有者和调度影响；
• 系统调用场景从频率、错误率和时延下钻到进程、线程，并用调度或热点栈补充解释。

每条诊断发现都携带异常窗口、关联实体、实际值、阈值、单位和因果角色。系统完整保留每个窗口的规则条件、评估结果和判定原因，便于复核阈值、解释误报和重放分析过程。

2. 规则与 AI 协同，形成证据驱动的可信诊断

规则引擎负责可重复的异常判定，AI Service 基于 Backend 生成的受控证据包提供第二诊断意见。系统会校验 AI 返回的证据 ID、PID 和 TID，只有能够对应真实观测数据的结果才会进入融合流程。

最终结论由确定性状态机裁决：

对比状态	融合状态	最终处理
两类诊断结论一致	confirmed	采用共同结论
一方需要更多证据	partial	保留已确认的异常，或给出待补充证据结论
规则确认异常，AI 判断正常	conflict	保留异常结论并进入人工复核
规则判断正常，AI 提示潜在异常	conflict	输出 inconclusive 并进入人工复核

这种设计兼顾大模型的归纳解释能力与规则诊断的可重复性，保证最终根因能够对应实际观测证据。

3. 面向目标机开销设计的分层采集

KOSMOS 优先在内核侧处理高频信号。调度、缺页、I/O、锁、系统调用和性能采样等事件先在 BPF Map 中完成计数、直方图和 Top-N 聚合，再按窗口向用户态输出摘要。

• aggregate 用于默认持续观测；
• target_trace 只跟踪指定目标及必要上下文；
• system_trace 用于受时长限制的全系统调度分析；
• raw_debug 用于短时、限量的原始事件排查。

Agent 侧进一步使用目标过滤、按需采样、有界队列、元数据缓存和 PostgreSQL 批量写入控制放大效应。事件丢失、Map 压力和写入状态统一进入数据质量信息，供后续窗口处理和诊断裁决使用。

系统核心能力

能力	当前实现
eBPF 深度观测	统一管理 14 个观测子系统，覆盖调度、运行队列、性能采样、块 I/O、VFS、页缓存、内存、回收、缺页、锁和系统调用等信号
5 类场景观测编排	按场景声明必要数据源和增强数据源，统一创建、停止并关联多个子系统任务
时间窗口处理	Processor 支持任务结束后的批处理和采集期间的流处理，复用同一套窗口处理接口
根因分析	子系统规则先识别局部异常，场景规则再关联不同信号，并处理连续异常、恢复和规则覆盖关系
证据回溯	保存窗口、指标、实际值、阈值、单位、因果角色和全部条件评估
数据质量判断	统一评估观测完整度、事件状态、Map 压力、运行时能力和处理状态
可信辅助诊断	将规则报告转换为受控证据包，校验 AI 引用的证据和关联实体，再进行确定性融合
工程化交付	提供单机与 C/S 部署、统一配置、5 类场景脚本、架构检查和前端工作台

系统架构

flowchart TB
    subgraph Client["C 端 · 被观测主机"]
        direction LR
        Kernel["Linux Kernel / procfs"]
        Agent["Agent
能力探测 · eBPF 采集 · 预聚合"]
        Kernel --> Agent
    end

    subgraph Server["S 端 · 控制与分析服务"]
        direction TB

        subgraph Storage["PostgreSQL · 持久化与异步边界"]
            direction TB
            Raw["采集任务
原始记录 · 聚合快照"]
            Result["分析结果
窗口摘要 · 语义时间线"]
        end

        Processor["Processor
窗口聚合 · 时间线 · 质量评估"]
        Backend["Backend
任务编排 · 规则诊断 · 报告"]
        Frontend["Frontend
观测工作台"]
        AI["AI Service（可选）
证据驱动的第二意见"]

        Raw --> Processor
        Processor --> Result
        Result --> Backend
        Frontend <--> Backend
        Backend -->|"受控证据包"| AI
        AI -->|"独立诊断意见"| Backend
    end

    Backend -.->|HTTP 任务控制| Agent
    Agent -->|"PostgreSQL 数据写入"| Raw

C/S 模式下，C 端是被观测主机，只运行 Agent；S 端集中运行 PostgreSQL、Processor、Backend、Frontend 和可选 AI Service。Backend 通过 HTTP 控制 Agent 的采集任务，Agent 将采集记录和聚合快照写入 S 端 PostgreSQL。单机模式将两个区域部署在同一主机，复用相同的能力、事件和摘要契约。

5 类异常场景

异常场景	观测与关联	根因定位
CPU 异常占用与调度延迟	CPU 使用率、运行队列、调度时延、上下文切换与热点栈	定位高占用进程、热点线程和函数，区分计算热点、内核热点与调度竞争
I/O 延迟抖动	块层与 VFS 时延、队列深度、吞吐、缓存写回、I/O PSI	定位异常设备、热点文件和关联进程，区分队列拥堵、设备服务异常与缓存压力
内存抖动与 OOM 风险	可用内存、进程内存、内存 PSI、缺页、回收与 OOM 事件	定位内存增长进程与高缺页线程，识别回收抖动、缺页风暴和 OOM 风险
锁竞争	等待与持锁时长、竞争次数、futex、锁地址和调度压力	定位热点锁、持有者和等待者，识别集中争用与长临界区
系统调用热点	调用频率、错误率、调用时延、调度等待与用户态热点栈	定位高频、高耗时或高错误率系统调用及其来源线程

KOSMOS 将观测完整度纳入诊断结论，并通过以下状态明确表达窗口的数据质量：

• observed=true, no_events=true：观测完整，窗口内确实没有事件；
• observed=false, incomplete=true：当前窗口需要补充观测证据。

赛题完成情况

赛题要求	指标描述	完成情况
场景覆盖	至少支持 4 类标准异常，完整支持 5 类可获得更高评分	已覆盖 CPU、I/O、内存、锁竞争和系统调用热点 5 类异常场景
结构化输出	包含异常类型、关联对象、关键指标、时间窗口、疑似根因、证据链和建议	已支持版本化 JSON 诊断结果、证据链、质量说明和前端展示
多平台适配	在 openKylin 稳定运行，并鼓励支持不同内核和处理器架构	已采用 eBPF CO-RE，并提供 amd64、ARM64 编译与重定位检查
诊断准确性	考察异常识别、根因定位、误报漏报和证据链一致性	已实现版本化规则、跨窗口关联、进程线程定位和逐条件评估
性能开销	考察 CPU、内存、平均/P99 时延和业务吞吐变化	已采用内核聚合、目标过滤、按需采样、有界队列和批量写入
工程质量	要求代码规范、文档完整、复现脚本和测试说明	已提供统一构建检查、模块文档、部署说明、5 类场景复现脚本和评测指南

诊断结果示例

以下示例用于展示结构化字段关系：

{
  "overall_severity": "high",
  "summary": "检测到用户态计算热点",
  "findings": [
    {
      "rule": "cpu_user_compute_hotspot",
      "rule_version": "competition-v1",
      "anomaly_type": "cpu_user_compute_hotspot",
      "suspected_root_cause": "目标线程长期占用 CPU，用户态热点样本集中",
      "related_pids": [1234],
      "related_tids": [1235],
      "evidence_chain": [
        {
          "window_start_ns": 1000000000,
          "window_end_ns": 11000000000,
          "subsystem": "cpu",
          "metric": "cpu_usage_pct",
          "value": 9200,
          "threshold": 9000,
          "unit": "basis_points",
          "causal_role": "symptom"
        }
      ],
      "suggestions": ["检查热点线程及其调用栈"]
    }
  ],
  "limitations": []
}

报告可以继续下钻到逐窗口规则条件、跨子系统证据和线程级语义时间线，并可从工作台导出为 JSON。

工程设计

项目通过共享契约和显式注册保持模块解耦：

• contracts 是跨组件能力、事件、场景和摘要结构的唯一事实来源；
• 每个 Observability 子系统自包含采集器、eBPF 对象、解码、处理和测试；
• Processor 依赖统一处理接口，与具体 eBPF 实现保持解耦；
• Backend 的子系统规则与场景规则独立注册，HTTP、持久化和诊断策略职责清晰；
• Frontend 通过适配层消费版本化结构，与数据库访问保持隔离；
• 架构检查同时校验 amd64/ARM64 CO-RE 重定位、能力契约、运行时注册表和前端适配器。

新增观测子系统时，可以沿着“共享契约 → Collector → Processor Handler → Diagnosis Handler → Frontend Adapter”的扩展链路接入，通用流水线能够保持稳定。

快速开始

基础环境为 openKylin 或其他 Linux 发行版、Kernel 6.6+、PostgreSQL、Go、Clang/LLVM、Node.js；Agent 需要 root 或等效的 eBPF、perf 和内核跟踪权限。

# 检查文档、契约、注册表和 CO-RE 构建
make test-architecture

# 构建 Go 服务与前端
make build

# 构建 Agent 分发包与 eBPF 对象
make build-ebpf

# 启动本地完整栈
make run

部署前请阅读部署指南。规则引擎可以独立完成诊断，AI Service 可按需提供第二诊断意见。单机与 C/S 拆分部署的地址、权限和 PostgreSQL 配置以部署指南为准。

复现与验证

5 类标准场景均提供脚本入口：

make scenario-cpu
make scenario-io
make scenario-memory
make scenario-lock
make scenario-syscall

验证目标	入口
全部单元与静态检查	make test
架构契约与多架构 CO-RE 检查	make test-architecture
eBPF 对象编译与重定位	make test-core
当前内核 verifier load	make test-core-load
5 类场景复现步骤	场景复现
准确性与性能评测方法	评测指南

项目导航

模块或文档	说明
系统设计文档	总体架构、模块边界、关键流程、状态机和质量约束
Observability	Agent、Processor、eBPF 子系统与扩展方式
Backend	API、任务编排、规则诊断、可信融合与报告
Contracts	能力、事件、场景和摘要的版本化契约
Frontend	观测工作台、页面结构和数据适配
AI Service	证据受限的 AI 第二诊断意见
Scripts	构建、部署、检查、复现和性能脚本
文档中心	需求背景、技术设计、配置、测试和运行适配说明