110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# 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 ./...
|
||
```
|