feat: 新增 memory checker，支持系统级内存和交换空间检测
This commit is contained in:
@@ -6,18 +6,19 @@ Checker 是 DiAL 的拨测执行单元。每个 target 通过 `type` 选择一
|
||||
|
||||
## 支持的类型
|
||||
|
||||
| 类型 | 用途 | 文档 |
|
||||
| ------ | -------------------------------------- | --------------- |
|
||||
| `http` | HTTP/HTTPS 应用层健康检查 | [HTTP](http.md) |
|
||||
| `cmd` | 执行本地命令或脚本 | [Cmd](cmd.md) |
|
||||
| `db` | PostgreSQL/MySQL/SQLite 连接和查询检查 | [DB](db.md) |
|
||||
| `tcp` | TCP 端口可达性和 banner 探测 | [TCP](tcp.md) |
|
||||
| `udp` | UDP payload 请求-响应检查 | [UDP](udp.md) |
|
||||
| `icmp` | 基于系统 `ping` 的存活、延迟、丢包检查 | [ICMP](icmp.md) |
|
||||
| `dns` | 本机解析或指定 DNS server 协议级检查 | [DNS](dns.md) |
|
||||
| `llm` | 大模型服务应用层健康检查 | [LLM](llm.md) |
|
||||
| `ws` | WebSocket 可达性和消息交互检查 | [WS](ws.md) |
|
||||
| `cpu` | 本机 CPU 使用率健康检查 | [CPU](cpu.md) |
|
||||
| 类型 | 用途 | 文档 |
|
||||
| -------- | -------------------------------------- | ------------------- |
|
||||
| `http` | HTTP/HTTPS 应用层健康检查 | [HTTP](http.md) |
|
||||
| `cmd` | 执行本地命令或脚本 | [Cmd](cmd.md) |
|
||||
| `db` | PostgreSQL/MySQL/SQLite 连接和查询检查 | [DB](db.md) |
|
||||
| `tcp` | TCP 端口可达性和 banner 探测 | [TCP](tcp.md) |
|
||||
| `udp` | UDP payload 请求-响应检查 | [UDP](udp.md) |
|
||||
| `icmp` | 基于系统 `ping` 的存活、延迟、丢包检查 | [ICMP](icmp.md) |
|
||||
| `dns` | 本机解析或指定 DNS server 协议级检查 | [DNS](dns.md) |
|
||||
| `llm` | 大模型服务应用层健康检查 | [LLM](llm.md) |
|
||||
| `ws` | WebSocket 可达性和消息交互检查 | [WS](ws.md) |
|
||||
| `cpu` | 本机 CPU 使用率健康检查 | [CPU](cpu.md) |
|
||||
| `memory` | 本机系统内存使用状况检查 | [Memory](memory.md) |
|
||||
|
||||
## 选择建议
|
||||
|
||||
@@ -33,6 +34,7 @@ Checker 是 DiAL 的拨测执行单元。每个 target 通过 `type` 选择一
|
||||
| LLM API 是否可用、输出是否符合预期 | `llm` |
|
||||
| WebSocket 可达性或消息交互验证 | `ws` |
|
||||
| 本机 CPU 使用率健康检查 | `cpu` |
|
||||
| 本机系统内存使用状况检查 | `memory` |
|
||||
|
||||
## 通用字段
|
||||
|
||||
|
||||
119
docs/user/checkers/memory.md
Normal file
119
docs/user/checkers/memory.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 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。
|
||||
|
||||
## 跨平台注意事项
|
||||
|
||||
- Windows 环境依赖 PowerShell 5+ 获取部分内存指标
|
||||
- `buffcacheBytes` 在非 Linux 平台上可能返回 `null`
|
||||
- 容器环境中内存数据可能不反映 cgroup 内存限制
|
||||
|
||||
## 不支持的功能
|
||||
|
||||
- 进程级内存使用（如 RSS、VSZ）
|
||||
- cgroup/container 内存限制精度
|
||||
- 内存趋势采样和历史记录
|
||||
- 内存条物理布局信息
|
||||
- 详细内存分类（slab、reclaimable、dirty 等）作为 expect 字段
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改 Memory checker 配置、expect 字段、行为或语义时，必须更新本文档。
|
||||
Reference in New Issue
Block a user