Metrics

GET/api/v1/metrics

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

查询参数

参数	必填	默认	说明
agent_id	是	部署默认 Agent（若配置）	通常与 VPS 目标 ID 对应
hours	否	24	默认最大 72 小时，部署可在 1–168 内调整
max_points	否	按窗口计算	返回点数，0 或负数会回到安全默认值
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	当前计费周期流量汇总

列式格式

列式格式适合传输大量图表点：

{
  "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]。客户端必须检查所有值数组长度，不要假设第三方代理永远返回完整列。

单位与空值

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