host-metrics-collector/README.md

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 入口

快速开始

构建

go build ./cmd/agent
go build ./cmd/gateway

运行 Gateway（4318）

HMS_AGENT_TOKEN=dev-token ./gateway

运行 Agent（采集 + 上报）

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	跨主机日志检索

测试

go test ./...