EulerPilot：面向 openEuler 的自适应资源管控 Agent

EulerPilot 是一个可运行、可扩展、可审计的参赛实现。它用用户态 Agent 感知 cgroup workload、PSI 与可选业务 SLO，通过 Unix socket 动态更新 sched_ext/eBPF 调度数据面；同一框架还提供 cgroup v2 资源控制、cgroup_skb 网络 Hook、标准化 Tools/Skill 接口和成对性能测试工具。

当前版本：0.1.0。默认配置是 dry_run=true，不会修改调度或 cgroup。

核心能力

workload 感知：从 cpu.stat、cgroup.threads、CPU/内存/IO PSI 和 Prometheus 文本指标采样，不依赖第三方 Python 包。
自适应策略：按 latency/throughput/batch/auto 目标分类，使用 EWMA 的底层 PSI 信号、迟滞、冷却和紧急旁路，避免策略抖动。
sched_ext 数据面：加权虚拟时间队列、可配置 task slice、有限的 latency wake-up credit；仍然 work-conserving，避免严格优先级饿死 batch。
安全回退：sched_ext 自带异常卸载并恢复默认调度器；Agent 还对 cgroup 原值做日志化，可执行 eulerpilot restore。
标准化扩展：版本化 JSON Schema、tools/list / tools/call JSON-RPC 接口和可复用 SKILL.md；eBPF Hook 例子可观察或阻断指定 cgroup 网络。
可复现实验：CFS/EulerPilot 交替成对运行，保存逐次原始数据、主机信息、调度器计数并生成 Markdown 报告；仓库不包含伪造的性能数字。

架构

flowchart LR
    W["cgroup workloads"] --> S["Sensors
cpu.stat · PSI · SLO"]
    S --> P["Adaptive policy
hysteresis · cooldown · guardrails"]
    P --> A["Actuators"]
    A --> U["scx Unix socket"]
    U --> B["sched_ext BPF
weighted vtime DSQ"]
    A --> C["cgroup v2
cpu.weight"]
    P --> T["Audit / status / Prometheus"]
    X["Tools & Skills"] --> S
    H["eBPF Hook SDK"] --> N["cgroup_skb network policy"]

详细设计见 docs/ARCHITECTURE.md。

openEuler 兼容性说明

openEuler 24.03 LTS SP3 的发行内核基于 Linux 6.6，而 sched_ext 在上游 Linux 6.12 才正式进入内核。openEuler 社区提供了 OLK-6.6 回移 PR，本项目固定到已审阅的回移提交，并在构建时检查 helper 代际。也就是说：

Python Agent、cgroup 控制和通用 eBPF Hook 可直接在 SP3 发行内核运行；
sched_ext 功能要求 SP3 用户态搭配启用 CONFIG_SCHED_CLASS_EXT 的内核；
scripts/prepare-sched-ext-kernel.sh 可复现该内核，不会默认安装或重启。

依据：openEuler SP3 特性/6.6 内核、 openEuler OLK-6.6 sched_ext 回移、 Linux sched_ext 文档。完整矩阵见 docs/COMPATIBILITY.md。

快速开始

1. 构建 sched_ext 内核

在 openEuler 24.03 LTS SP3 上：

bash scripts/prepare-sched-ext-kernel.sh --workdir /var/tmp/eulerpilot-kernel
# 检查构建产物后，确需安装时：
bash scripts/prepare-sched-ext-kernel.sh \
  --workdir /var/tmp/eulerpilot-kernel --install
sudo reboot

重启后确认：

uname -r
test -e /sys/kernel/sched_ext/state
grep CONFIG_SCHED_CLASS_EXT /boot/config-$(uname -r)

2. 构建和安装 EulerPilot

cd EulerPilot
bash scripts/bootstrap-openeuler.sh /var/tmp/eulerpilot-kernel/kernel
sudo eulerpilot doctor --config /etc/eulerpilot/eulerpilot.toml

3. 配置 workload

先创建或使用现有 cgroup，将 /etc/eulerpilot/eulerpilot.toml 中的 [[workloads]] 指向它。首次只做观测：

sudo eulerpilot once --config /etc/eulerpilot/eulerpilot.toml
curl http://127.0.0.1:9876/metrics

确认决策和审计记录后再开启数据面：

sudo systemctl enable --now eulerpilot-scx
sudo eulerpilot run --config /etc/eulerpilot/eulerpilot.toml --apply

生产使用时可将配置中的 dry_run 改成 false，再启动 eulerpilot.service。完整步骤、回滚方法和预期输出见 docs/REPRODUCE.md。

Tools 和 Skill

eulerpilot tool --config config/eulerpilot.toml list
eulerpilot tool --config config/eulerpilot.toml \
  call policy.plan --arguments '{"name":"latency-service"}'
eulerpilot tools-server --config config/eulerpilot.toml

stdio 服务接受逐行 JSON-RPC 2.0：

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"agent.status","arguments":{}}}

工具描述遵循 schemas/tool.schema.json；Skill 位于 skills/cpu-scheduling/。唯一的变更型 Tool policy.apply 同时要求已审阅配置中的 dry_run=false 和调用参数 confirm=true；常规运行仍走显式 --apply 路径。API 细节见 docs/API.md。

eBPF Hook 扩展

网络 Hook 默认只计数，不丢包：

sudo bash scripts/network-hook.sh attach /sys/fs/cgroup/my-service
sudo bash scripts/network-hook.sh stats /sys/fs/cgroup/my-service
sudo bash scripts/network-hook.sh policy /sys/fs/cgroup/my-service observe
sudo bash scripts/network-hook.sh detach /sys/fs/cgroup/my-service

阻断动作需要额外的 --confirm-block。同样的 hook 生命周期和 map 控制面可用于 security audit、socket policy 或 resource telemetry Agent。

性能测试

sudo python3 benchmarks/run.py --yes --repetitions 7 --duration 30

测试将一条 1 kHz 周期性任务与每逻辑 CPU 一个 batch 计算任务混部，交替运行 CFS 和 EulerPilot，输出：

p99/p99.9 wake-up latency；
batch aggregate ops/s；
每次 trial 的原始 JSON；
eBPF 调度计数、OS、内核、CPU 和实验参数；
自动生成的 REPORT.md。

协议和数据解读见 benchmarks/README.md。当前工作区是 Windows，不能加载 Linux sched_ext，因此没有冒充 openEuler 实测的数字；在目标机执行一条命令即可生成正式报告。

测试

make check

当前测试覆盖配置拒错、路径逃逸、cgroup/PSI 采样、Prometheus 解析、策略迟滞/紧急旁路、调度命令边界、cgroup 回滚、指标导出和 JSON-RPC。

bpf/          sched_ext 调度器、loader、network Hook
src/          Python Agent、感知、策略、控制、Tools/API
config/       示例配置和 systemd unit
environment/  官方 SP3 qcow2 校验、overlay 和 QEMU 启动脚本
benchmarks/   原生 workload、成对实验与报告生成
scripts/      openEuler 内核、安装、Hook 和演示脚本
schemas/      Tool/Skill JSON Schema
skills/       可复用 CPU scheduling Skill
tests/        无特权单元测试
docs/         架构、兼容性、复现、API、演示说明

评分点映射

评分项	对应实现
创新性 30	用户态闭环 + bounded-credit weighted-vtime scx；Tools/Skill/Hook 三层扩展
功能完整性 25	cgroup/PSI/SLO 感知、四类目标、迟滞/冷却/紧急旁路、审计与回滚
性能提升 25	严格成对 benchmark、tail latency + throughput、完整原始数据
代码质量 10	零 Python 运行依赖、类型化模型、严格配置、16+ 测试、安全边界
演示效果 10	doctor → dry-run 决策 → live scx → Prometheus → paired report

许可证

控制面采用 Apache-2.0；bpf/ 中与内核交互的程序按文件标注 GPL-2.0。