lanyuanxiaoyao
c2dcfab80c
- 新增 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
75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# 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 字段、行为或语义时，必须更新本文档。
|