Files

lanyuanxiaoyao c2dcfab80c 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

2026-05-26 22:34:57 +08:00

2.8 KiB

Raw Blame History

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"。

示例

- id: "local-cpu"
  name: "本机 CPU"
  type: cpu
  interval: "30s"
  timeout: "5s"
  cpu:
    sampleDuration: "1s"
  expect:
    usagePercent:
      lte: 85
    maxCoreUsagePercent:
      lte: 95

输出每核心使用率：

- 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 字段、行为或语义时，必须更新本文档。

2.8 KiB Raw Blame History Unescape Escape