KylinSight

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

当前版本

v0.9.4 - 阻塞异常状态机与页面展示修复版 (2026-07-27)

核心功能

BPF 事件采集：sched_switch 进程切换事件实时采集
阻塞异常检测：自动检测长时间阻塞进程并分类为 resolved/expired/active/pid_reused
REST API 服务：提供完整的监控数据 API，包含异常查询接口
实时 Dashboard：Web 界面展示系统状态和阻塞异常

技术特性

eBPF + libbpf-bootstrap 架构
内核 BTF 支持，自动获取内核数据结构
用户态 Collector + Python API 服务架构
Server-Sent Events (SSE) 实时推送
阻塞异常状态机：active → resolved / expired / pid_reused

环境要求

openKylin / Ubuntu 22.04+
Linux 内核 6.6+
clang, llvm, gcc
libelf-dev, zlib1g-dev, libzstd-dev
libbpf-dev
bpftool

快速开始

1. 安装依赖

sudo apt update
sudo apt install -y \
    clang llvm gcc make cmake \
    libelf-dev zlib1g-dev libzstd-dev \
    bpftool libbpf-dev \
    linux-headers-$(uname -r)

2. 构建

cd kylinsight
chmod +x scripts/*.sh
./scripts/build.sh

3. 运行 API 服务

sudo -E .venv/bin/python3 api/server.py

服务启动后访问 http://localhost:8888/dashboard

4. 运行压力测试验证

# 终端一：启动服务
sudo -E .venv/bin/python3 api/server.py

# 终端二：运行压力测试
stress-ng --cpu 4 --timeout 20s --metrics-brief

# 终端二：查询监控数据
curl http://localhost:8888/api/v1/health
curl http://localhost:8888/api/v1/metrics/summary
curl http://localhost:8888/api/v1/anomalies?limit=100

5. 停止服务

按 Ctrl+C 正常退出，BPF 资源自动清理。

项目结构

kylinsight/
├── bpf/
│   ├── include/
│   │   ├── vmlinux.h          # 内核 BTF 头文件
│   │   └── event.h            # 事件结构定义
│   └── sched_switch.bpf.c     # BPF 程序
├── collector/
│   └── src/
│       └── main.c              # 用户态 Collector (ignored_pid 过滤)
├── api/
│   ├── server.py              # FastAPI 服务
│   └── static/                 # Web Dashboard
├── web/                        # 前端资源
├── analyzer/                  # Python 诊断引擎
├── scripts/
│   ├── build.sh               # 构建脚本
│   └── run.sh                 # 运行脚本
├── tests/
│   └── test_blocking_anomaly.py  # 阻塞异常单元测试
├── configs/                   # 配置文件
├── docs/                      # 文档
├── CMakeLists.txt
├── pyproject.toml
└── README.md

API 端点

端点	说明
`GET /api/v1/health`	健康检查
`GET /api/v1/metrics/summary`	指标汇总
`GET /api/v1/processes/top`	热点进程 Top N
`GET /api/v1/events/recent`	最近事件
`GET /api/v1/events/stream`	SSE 实时事件流
`GET /api/v1/metrics/history`	历史速率
`GET /api/v1/cpus`	CPU 统计
`GET /api/v1/anomalies`	阻塞异常查询
`GET /dashboard`	Web Dashboard

阻塞异常字段说明

resolved（已恢复）

{
  "status": "resolved",
  "resolution_reason": "observed_resume",
  "blocked_start_at": 1234567890.123,
  "blocked_end_at": 1234567895.456,
  "blocked_duration_ms": 5333.0,
  "resumed_cpu": 3,
  "duration_ms": 5333.0,
  "metric_value": 5333.0
}

expired（超时）

{
  "status": "expired",
  "resolution_reason": "timeout_expired",
  "blocked_start_at": 1234567890.123,
  "blocked_end_at": null,
  "blocked_duration_ms": null,
  "tracked_duration_ms": 300000.0,
  "resumed_cpu": null,
  "duration_ms": null
}

active（跟踪中）

{
  "status": "active",
  "blocked_start_at": 1234567890.123,
  "blocked_end_at": null,
  "blocked_duration_ms": null,
  "tracked_duration_ms": 150000.0
}

pid_reused（PID复用）

{
  "status": "pid_reused",
  "resolution_reason": "pid_reused",
  "blocked_start_at": null,
  "blocked_end_at": null,
  "blocked_duration_ms": null,
  "tracked_duration_ms": 5000.0
}

构建流程

clang 编译 sched_switch.bpf.c → sched_switch.bpf.o
bpftool gen skeleton 生成 sched_switch.skel.h
gcc/clang 编译用户态 main.c
链接 libbpf, libelf, zlib

版本历史

v0.9.4 (2026-07-24) - 本次更新（2026-07-27）

修复：阻塞异常状态机字段逻辑，resolved/expired/active/pid_reused 各状态字段正确区分
修复：blocked_duration_ms 从 float = 0.0 改为 Optional[float] = None，支持 null
修复：Dashboard 页面正确区分 expired 和 resolved 的展示内容
新增：单元测试覆盖所有阻塞异常状态转换（17个测试用例）
新增：异常类型过滤 ?type=blocking_observed
新增：异常状态过滤 ?status=resolved
新增：分页支持 ?offset=0&limit=50
修复：高频异常详情字段语义，区分”触发时指标值”、”当前速率”、”峰值速率”
新增：恢复原因中文映射（switch_rate_back_to_normal → 调度速率恢复正常等）
新增：持续时间和统计窗口语义区分（异常持续时间 vs 统计窗口时长）
新增：统一格式化函数（formatRate, formatDurationSeconds, formatDurationMs等）
修复：dropped_events 重复计算问题，拆分为 recent_event_evictions 和 sse_queue_drops
新增：异常缓存字段规范（count, total_in_buffer, anomaly_buffer_count, anomaly_buffer_max）
新增：SSE 订阅者泄漏修复（添加 pagehide 事件监听器）
新增：演示脚本（scripts/demo/）
- demo_high_switch.sh：安全触发高频调度异常
- verify_runtime.sh：运行时验证
- verify_anomalies.py：异常数据验证
- replay_blocking_lifecycle.py：状态机重放测试