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:
74
docs/user/checkers/cpu.md
Normal file
74
docs/user/checkers/cpu.md
Normal 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 字段、行为或语义时,必须更新本文档。
|
||||
Reference in New Issue
Block a user