lanyuanxiaoyao
3390eb5e8d
- Memory checker: reader 与 ctx.signal race，abort 返回 memory/timeout，reject 保持 memory/snapshot - CPU checker: 第二次快照异常返回 cpu/snapshot，计算前校验空数组/核心数不一致/非有限值/负 delta - CPU 计算: 零 delta 安全处理，observation 不含 NaN/Infinity - 文档: CPU 互补描述修正，Memory timeout 约束说明 - 测试: +18 覆盖 timeout、异常和边界输入
120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# Memory Checker
|
||
|
||
`type: memory` 用于检查本机系统级内存使用状况，包括物理内存和交换空间的使用率及字节数。
|
||
|
||
## 配置项
|
||
|
||
Memory checker 配置为空对象，无需额外参数：
|
||
|
||
```yaml
|
||
memory: {}
|
||
```
|
||
|
||
## expect 校验项
|
||
|
||
### 百分比字段
|
||
|
||
| 字段 | 说明 | 必填 | 默认值 |
|
||
| ------------------ | -------------------------------------------------------------------------- | ---- | ------ |
|
||
| `usagePercent` | 真实内存使用率 = `activeBytes / totalBytes × 100`，不含 buffers/cache 假象 | 否 | 无 |
|
||
| `usedPercent` | 原始已用百分比 = `usedBytes / totalBytes × 100`，包含 buffers/cache | 否 | 无 |
|
||
| `freePercent` | 空闲百分比 = `freeBytes / totalBytes × 100` | 否 | 无 |
|
||
| `activePercent` | 活跃内存百分比 = `activeBytes / totalBytes × 100` | 否 | 无 |
|
||
| `availablePercent` | 可用内存百分比 = `availableBytes / totalBytes × 100` | 否 | 无 |
|
||
| `swapUsagePercent` | 交换空间使用率，当系统无交换分区时为 `null` | 否 | 无 |
|
||
|
||
所有百分比字段范围为 `0-100`，使用 `ValueMatcher`。
|
||
|
||
### 字节字段
|
||
|
||
| 字段 | 说明 | 必填 | 默认值 |
|
||
| ---------------- | ----------------------------------------- | ---- | ------ |
|
||
| `activeBytes` | 活跃内存字节数 | 否 | 无 |
|
||
| `usedBytes` | 已用内存字节数（含 buffers/cache） | 否 | 无 |
|
||
| `freeBytes` | 空闲内存字节数 | 否 | 无 |
|
||
| `availableBytes` | 可用内存字节数 | 否 | 无 |
|
||
| `totalBytes` | 物理内存总字节数 | 否 | 无 |
|
||
| `swapUsedBytes` | 交换空间已用字节数，无交换分区时为 `null` | 否 | 无 |
|
||
| `swapFreeBytes` | 交换空间空闲字节数，无交换分区时为 `null` | 否 | 无 |
|
||
| `swapTotalBytes` | 交换空间总字节数，无交换分区时为 `0` | 否 | 无 |
|
||
| `buffcacheBytes` | 缓冲缓存字节数，部分平台可能为 `null` | 否 | 无 |
|
||
|
||
字节字段支持数字（字节数）或大小字符串（如 `"512MB"`、`"1GB"`），使用 `ValueMatcher`。
|
||
|
||
### 通用字段
|
||
|
||
| 字段 | 说明 | 必填 | 默认值 |
|
||
| ------------ | ------------------------------------- | ---- | ------ |
|
||
| `durationMs` | 完整执行耗时校验，使用 `ValueMatcher` | 否 | 无 |
|
||
|
||
## 示例
|
||
|
||
检查内存使用率不超过 85%：
|
||
|
||
```yaml
|
||
- id: "local-memory"
|
||
name: "本机内存"
|
||
type: memory
|
||
interval: "30s"
|
||
timeout: "5s"
|
||
memory: {}
|
||
expect:
|
||
usagePercent:
|
||
lte: 85
|
||
```
|
||
|
||
检查可用内存不低于 4GB：
|
||
|
||
```yaml
|
||
- id: "local-memory-available"
|
||
name: "可用内存检查"
|
||
type: memory
|
||
memory: {}
|
||
expect:
|
||
availableBytes:
|
||
gte: "4GB"
|
||
```
|
||
|
||
同时检查内存和交换空间：
|
||
|
||
```yaml
|
||
- id: "local-memory-swap"
|
||
name: "内存和交换空间"
|
||
type: memory
|
||
memory: {}
|
||
expect:
|
||
usagePercent:
|
||
lte: 80
|
||
swapUsagePercent:
|
||
lte: 50
|
||
```
|
||
|
||
## 语义说明
|
||
|
||
Memory checker 通过 `systeminformation` 库读取系统内存数据，在 Linux、macOS 和 Windows 上均可运行。
|
||
|
||
- **`usagePercent`** 使用 `activeBytes / totalBytes` 计算，反映真实的内存压力，不受 Linux buffers/cache 缓存影响。推荐使用此字段进行内存健康检查。
|
||
- **`usedPercent`** 使用 `usedBytes / totalBytes` 计算，包含 buffers/cache。在 Linux 上此值通常高于 `usagePercent`。
|
||
- **Swap 字段**：当系统未配置交换分区时，`swapTotalBytes` 为 `0`，`swapUsagePercent` 为 `null`（非 `0`）。
|
||
- **`buffcacheBytes`**：反映 Linux 的 buffers + cache 用量，在其他平台上可能为 `null`。
|
||
|
||
Memory checker 是即时读取（非采样），无需 `sampleDuration`，执行速度远快于 CPU checker。虽然读取本身很快，但仍受 target `timeout` 约束——若底层系统调用悬挂或阻塞超过 `timeout`，checker 会返回 `memory/timeout` failure。
|
||
|
||
## 跨平台注意事项
|
||
|
||
- Windows 环境依赖 PowerShell 5+ 获取部分内存指标
|
||
- `buffcacheBytes` 在非 Linux 平台上可能返回 `null`
|
||
- 容器环境中内存数据可能不反映 cgroup 内存限制
|
||
|
||
## 不支持的功能
|
||
|
||
- 进程级内存使用（如 RSS、VSZ）
|
||
- cgroup/container 内存限制精度
|
||
- 内存趋势采样和历史记录
|
||
- 内存条物理布局信息
|
||
- 详细内存分类（slab、reclaimable、dirty 等）作为 expect 字段
|
||
|
||
## 更新触发条件
|
||
|
||
修改 Memory checker 配置、expect 字段、行为或语义时，必须更新本文档。
|