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