Metrics

GET/api/v1/metrics

读取单个 Rust Agent 的最新状态与历史指标。历史优先来自 R2，按请求上限降采样；接口不返回无限原始历史。

查询参数

参数	必填	默认	说明
agent_id	是	部署默认 Agent（若配置）	通常与 VPS 目标 ID 对应
hours	否	24	默认最大 72 小时，部署可在 1–168 调整
max_points	否	按窗口计算	返回点数；非有限、0 或负数回到安全默认，最终至少 60
history	否	1	0 时只读取最新值
format	否	行格式	columns 返回紧凑列式序列
metric / fields	否	全部	限制历史指标组或字段

curl -fsSL 'https://YOUR-API/api/v1/metrics?agent_id=vps-a&hours=6&max_points=360'

可选指标

组名：cpu、mem、disk、load、net、conns、diskio、temp、gpu。也可以用逗号分隔字段：

cpu,mem,disk,load1,net_rx,net_tx,tcp_conns,udp_conns,
disk_read,disk_write,cpu_temp,gpu_temp,gpu_util,
motherboard_temp,disk_temp,chipset_temp

curl -fsSL 'https://YOUR-API/api/v1/metrics?agent_id=vps-a&hours=1&fields=cpu,mem,cpu_temp'

响应字段

字段	说明
latest	最新 Agent 摘要；尚未上报时为 null
history[]	升序行格式历史；列式格式时为空
series	format=columns 时的 t0、dt、字段与值数组
history_raw_count	降采样前点数
history_downsampled	是否已降采样
source	r2、r2+d1-fallback、d1 等实际来源
traffic	当前计费周期流量汇总
warnings[]	最新状态或可选历史读取的非阻断警告

列式格式

{
  "series": {
    "t0": 1760000000,
    "dt": [0, 10, 20],
    "fields": ["cpu", "mem"],
    "values": {
      "cpu": [8.4, 9.1, 7.8],
      "mem": [42.0, 42.1, 42.1]
    }
  }
}

每个时间戳等于 t0 + dt[index]。客户端必须检查所有值数组长度，不要假设第三方代理永远返回完整列。

history=0 不读历史，适合只展示最新状态。format=columns 时 history 为空，数据在 series，不要同时消费两套字段。服务端规范化 Agent ID、窗口、点数、格式与字段后构造缓存键。

单位与空值

指标单位以当前前端展示与响应语义为准。温度、GPU、主板与磁盘传感器在多数虚拟化环境不可用，UI 应隐藏缺失系列，而不是显示 0°C。

latest.vps_info.total_disk_gb 是系统根文件系统容量。网络与磁盘 IO 是速率字段；计费流量来自持久化周期账本，不能用单次 net_rx/net_tx 速率反推月流量。