1
0

feat: 新增本机 CPU checker

- 新增 type: cpu checker,基于 os.cpus() 两次快照计算 CPU 使用率
- 配置项:sampleDuration(默认 1s)、includePerCore(默认 false)
- expect 字段:usagePercent、idlePercent、maxCoreUsagePercent、minCoreUsagePercent、durationMs
- idlePercent 与 usagePercent 互补恒等于 100,百分比范围 0-100
- logicalCoreCount 仅输出到 observation,不作为 expect 字段
- 不暴露 userPercent / systemPercent
- 语义校验禁止 sampleDuration >= timeout
- 支持 AbortSignal 超时取消
- 完整测试覆盖:schema、validate、normalize、resolve、calculate、execute、expect、config-loader
- 新增用户文档 docs/user/checkers/cpu.md
- 更新 checker 索引、配置类型列表、示例配置和 schema
This commit is contained in:
2026-05-26 22:34:57 +08:00
parent f38286d74d
commit c2dcfab80c
22 changed files with 1839 additions and 3 deletions

74
docs/user/checkers/cpu.md Normal file
View File

@@ -0,0 +1,74 @@
# CPU Checker
`type: cpu` 用于检查本机 CPU 使用率,基于两次系统快照计算总体和每核心的忙碌比例。
## 配置项
| 字段 | 说明 | 必填 | 默认值 |
| -------------------- | -------------------------------- | ---- | ------- |
| `cpu.sampleDuration` | CPU 采样窗口,支持时长格式 | 否 | `1s` |
| `cpu.includePerCore` | 是否在结果中输出每核心使用率数组 | 否 | `false` |
`sampleDuration` 必须小于 target 的 `timeout`
## expect 校验项
| 字段 | 说明 | 必填 | 默认值 |
| --------------------- | ----------------------------------------------------------------------------- | ---- | ------ |
| `usagePercent` | 总体 CPU 使用率,范围 `0-100`,使用 `ValueMatcher` | 否 | 无 |
| `idlePercent` | 总体 CPU 空闲率,与 `usagePercent` 互补(`idlePercent = 100 - usagePercent` | 否 | 无 |
| `maxCoreUsagePercent` | 单核心最高使用率,使用 `ValueMatcher` | 否 | 无 |
| `minCoreUsagePercent` | 单核心最低使用率,使用 `ValueMatcher` | 否 | 无 |
| `durationMs` | 完整执行耗时校验,使用 `ValueMatcher` | 否 | 无 |
所有百分比字段范围为 `0-100`,表示所有可见逻辑 CPU 的总体比例,不是"核心数 × 100"。
## 示例
```yaml
- id: "local-cpu"
name: "本机 CPU"
type: cpu
interval: "30s"
timeout: "5s"
cpu:
sampleDuration: "1s"
expect:
usagePercent:
lte: 85
maxCoreUsagePercent:
lte: 95
```
输出每核心使用率:
```yaml
- id: "local-cpu-detail"
name: "本机 CPU 详细"
type: cpu
cpu:
sampleDuration: "2s"
includePerCore: true
expect:
usagePercent:
lte: 80
```
## 语义说明
CPU checker 采集的是 DiAL 进程运行环境通过系统 API`os.cpus()`)可见的 CPU 视图。在容器中,它可能不等于严格的 cgroup quota 使用率。
`usagePercent``idlePercent` 互补,恒等于 100。`sampleDuration` 决定了两次快照之间的等待时间,窗口越长结果越稳定,但会增加 checker 执行耗时。
## 不支持的功能
- CPU 温度、电源状态、频率
- `userPercent` / `systemPercent`(用户态/系统态占比)
- `loadAverage`(系统负载均值)
- 进程级 CPU 使用率
- Linux cgroup 精确 CPU 计算
- `logicalCoreCount` 作为 expect 字段(仅在 observation 中输出)
## 更新触发条件
修改 CPU checker 配置、expect 字段、行为或语义时,必须更新本文档。