# host-metrics-collector

主机监控系统（HMS）的主机指标与日志采集模块。包含两部分：

- **Agent（`cmd/agent`）**：定时采集 CPU / 内存 / 磁盘 / 网络 / 进程指标，tail 采集文件日志，本地 WAL 断点续传，批量上报。
- **Collector Gateway（`cmd/gateway`）**：在 `4318` 端口接收 Agent 的 protobuf 上报，提供指标 / 日志查询 REST API 与健康检查。

## 目录结构

```
api/collector.proto          # protobuf 数据契约（MetricBatch / LogBatch / Ack 等）
pkg/collectorpb/             # protoc 生成代码（已提交）
pkg/convert/                 # 领域模型 <-> protobuf 转换
internal/model/              # 领域模型与指标命名规范
internal/config/             # 环境变量优先的配置加载
internal/collect/            # gopsutil 系统指标采集 + 文件日志 tail
internal/checkpoint/         # 断点续传检查点（memory / file / redis）
internal/wal/                # Agent 本地 WAL（追加式，按 seq 恢复）
internal/agent/              # Agent 调度、缓冲、上报、心跳
internal/gateway/            # Gateway 存储与 HTTP 处理器（上报 + 查询 API）
cmd/agent/                   # Agent 入口
cmd/gateway/                 # Gateway 入口
```

## 快速开始

### 构建

```bash
go build ./cmd/agent
go build ./cmd/gateway
```

### 运行 Gateway（4318）

```bash
HMS_AGENT_TOKEN=dev-token ./gateway
```

### 运行 Agent（采集 + 上报）

```bash
HMS_HOST_ID=host-001 \
HMS_AGENT_TOKEN=dev-token \
HMS_GATEWAY_URL=http://127.0.0.1:4318 \
HMS_LOG_FILES=/var/log/app.log \
HMS_CHECKPOINT_DRIVER=file \
./agent
```

## 配置（环境变量）

| 变量 | 默认值 | 说明 |
|---|---|---|
| `HMS_HOST_ID` | `host-001` | Agent 主机标识 |
| `HMS_AGENT_VERSION` | `0.1.0` | Agent 版本 |
| `HMS_SERVICE` | `host` | 服务标签 |
| `HMS_GATEWAY_URL` | `http://127.0.0.1:4318` | 上报地址 |
| `HMS_AGENT_TOKEN` | `dev-token` | 上报 Token |
| `HMS_LOG_FILES` | 空 | 逗号分隔的日志文件路径 |
| `HMS_CORE_INTERVAL` | `15s` | 核心指标采集频率 |
| `HMS_DISK_INTERVAL` | `30s` | 磁盘指标采集频率 |
| `HMS_NETWORK_INTERVAL` | `30s` | 网络指标采集频率 |
| `HMS_PROCESS_INTERVAL` | `60s` | 进程指标采集频率 |
| `HMS_BATCH_SIZE` | `128` | 指标批量大小 |
| `HMS_FLUSH_INTERVAL` | `10s` | 上报刷新间隔 |
| `HMS_CHECKPOINT_DRIVER` | `file` | `memory` / `file` / `redis` |
| `HMS_CHECKPOINT_FILE` | `checkpoint.json` | file 驱动检查点文件 |
| `HMS_REDIS_URL` | `redis://127.0.0.1:6379/0` | redis 驱动地址 |
| `HMS_GATEWAY_ADDR` | `0.0.0.0:4318` | Gateway 监听地址 |
| `HMS_MAX_METRICS_PER_HOST` | `20000` | 内存中每主机指标保留上限 |
| `HMS_MAX_LOGS_PER_HOST` | `20000` | 内存中每主机日志保留上限 |

## 断点续传

- 日志文件 offset 与指标 / 日志上报 seq 通过 `checkpoint.Store` 持久化。
- 生产环境使用 `HMS_CHECKPOINT_DRIVER=redis`，Redis 键：
  - 日志 offset：`hms:agent:logoffset:{file}`
  - 已确认 seq：`hms:agent:ackedseq:{host_id}`
- 上报成功收到 `Ack{seq}` 后推进检查点；进程重启后从未确认点继续，保证至少一次投递。

## API

### Agent 上报（protobuf，`X-Agent-Token` 认证）

| Method | Path | 说明 |
|---|---|---|
| POST | `/v1/agent/heartbeat` | 心跳 / 注册 / 配置下发 |
| POST | `/v1/agent/metrics` | 指标批量上报（`MetricBatch` → `Ack`） |
| POST | `/v1/agent/logs` | 日志批量上报（`LogBatch` → `Ack`） |
| GET | `/v1/agent/checkpoint/{host_id}` | 查询已确认序号 |

### 查询 REST API（JSON）

| Method | Path | 说明 |
|---|---|---|
| GET | `/healthz` | 存活探针 |
| GET | `/readyz` | 就绪探针 |
| GET | `/api/v1/hosts/{host_id}/metrics` | 单主机指标时序 |
| GET | `/api/v1/hosts/{host_id}/logs` | 单主机日志 |
| GET | `/api/v1/metrics/query` | 时序范围查询 |
| GET | `/api/v1/metrics/query/instant` | 即时查询 |
| POST | `/api/v1/logs/search` | 跨主机日志检索 |

## 测试

```bash
go test ./...
```