1
0

refactor: 将 memory checker 重命名为 mem

- 类型标识符 memory → mem
- 类名 MemoryChecker → MemChecker
- 内部类型名统一 Memory* → Mem*
- 内部函数名统一 *Memory* → *Mem*
- 目录重命名 memory/ → mem/(源码、测试、文档)
- 配置键 memory: → mem:
- 重新生成 probe-config.schema.json
- 保留中文"内存"用户提示

破坏性变更:无向后兼容
This commit is contained in:
2026-05-27 18:16:33 +08:00
parent 3390eb5e8d
commit 2f8fd8bd9c
20 changed files with 194 additions and 196 deletions

119
docs/user/checkers/mem.md Normal file
View File

@@ -0,0 +1,119 @@
# Mem Checker
`type: mem` 用于检查本机系统级内存使用状况,包括物理内存和交换空间的使用率及字节数。
## 配置项
Mem checker 配置为空对象,无需额外参数:
```yaml
mem: {}
```
## 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: mem
interval: "30s"
timeout: "5s"
mem: {}
expect:
usagePercent:
lte: 85
```
检查可用内存不低于 4GB
```yaml
- id: "local-memory-available"
name: "可用内存检查"
type: mem
mem: {}
expect:
availableBytes:
gte: "4GB"
```
同时检查内存和交换空间:
```yaml
- id: "local-memory-swap"
name: "内存和交换空间"
type: mem
mem: {}
expect:
usagePercent:
lte: 80
swapUsagePercent:
lte: 50
```
## 语义说明
Mem 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`
Mem checker 是即时读取(非采样),无需 `sampleDuration`,执行速度远快于 CPU checker。虽然读取本身很快但仍受 target `timeout` 约束——若底层系统调用悬挂或阻塞超过 `timeout`checker 会返回 `mem/timeout` failure。
## 跨平台注意事项
- Windows 环境依赖 PowerShell 5+ 获取部分内存指标
- `buffcacheBytes` 在非 Linux 平台上可能返回 `null`
- 容器环境中内存数据可能不反映 cgroup 内存限制
## 不支持的功能
- 进程级内存使用(如 RSS、VSZ
- cgroup/container 内存限制精度
- 内存趋势采样和历史记录
- 内存条物理布局信息
- 详细内存分类slab、reclaimable、dirty 等)作为 expect 字段
## 更新触发条件
修改 Mem checker 配置、expect 字段、行为或语义时,必须更新本文档。