一、接口介绍

/ws/v1/timeline/metrics 是 Ambari-Metrics Collector 中最常用的接口，用于查询监控指标的时序数据。
通过该接口，用户可以灵活地按 指标名、应用 ID、主机名、时间窗口 等条件，获取所需的指标序列。

接口特点：

• 支持 多值查询：metricNames、hostname 可一次传多个值；
• 所有参数均为可选（源码注释明确说明），但如果不传 metricNames，查询结果通常无意义；
• 提供 TopN、BottomN、聚合函数 等高级用法；
• 返回 JSON 结构，易于和 Grafana、前端看板集成。

二、参数说明

参数	是否必填	示例值	说明
metricNames	必须	cpu_user	指标名，支持多个，逗号分隔
appId	否	HOST / ams-hbase	指标所属的应用或子系统
instanceId	否	instance-1	实例 ID（可区分不同进程/角色）
hostname	否	dev1 / dev1,dev2	主机过滤条件
startTime	必须	1757640582000	查询起始时间（epoch 毫秒）
endTime	必须	1757662182000	查询结束时间（epoch 毫秒）
precision	否	minutes	时间粒度：seconds / minutes / hours
limit	否	10	单序列返回点数上限
grouped	否	true	是否分组返回，缺省为 true
topN	否	5	Top-N 个数
topNFunction	否	max	Top-N 函数：max/min/avg/sum
isBottomN	否	true	是否取 Bottom-N
seriesAggregateFunction	否	avg	跨序列聚合函数：avg/sum/min/max

使用建议

• 时间戳必须是毫秒，误传为秒将可能导致无数据，且两个参数都必须输入；
• 大窗口查询建议指定 precision，减少结果点数；
• TopN 与 BottomN 参数互斥，注意区分使用；
• 实际调用时，推荐至少传入：metricNames + startTime + endTime。

三、最小请求示例

下面我们通过一个最小可运行的 demo 来演示 /metrics 接口的使用。

3.1 输入参数

我们选择查询主机的 CPU 用户态使用率：

• metricNames=cpu_user
• appId=HOST
• startTime=1757640600000
• endTime=1757640900000
• limit=5

3.2 执行请求

通过 cURL 命令行发起请求：

curl "http://dev1:6188/ws/v1/timeline/metrics?\
metricNames=cpu_user \
&appId=HOST \
&startTime=1757640600000 \
&endTime=1757640900000 \
&limit=5"

3.3 返回结果

接口返回的 JSON 数据如下（节选）：

{
  "metrics": [
    {
      "metricname": "cpu_user",
      "appid": "HOST",
      "hostname": "dev1",
      "timestamp": 0,
      "starttime": 1757640600000,
      "metrics": {
        "1757640600000": 0.15,
        "1757640630000": 0.18,
        "1757640660000": 0.21,
        "1757640690000": 0.25,
        "1757640720000": 0.27
      },
      "metadata": {}
    }
  ]
}

3.4 结果解析

• metricname：返回的指标名，与请求参数一致；
• appid：指标所属的应用 ID；
• metrics：核心数据，时间戳 → 值 的映射；
• starttime：序列起点时间；
• metadata：扩展信息（若 Collector 配置了单位/来源则写入）。

四、配合 APIFOX 可视化调试

通过 APIFOX 导入 openapi.json 文件 (opens new window)，即可方便调试。

操作流程：

1. 打开 /ws/v1/timeline/metrics；
2. 填写 metricNames、appId、时间窗口；
3. 点击运行，得到 JSON；
4. 前端渲染生成曲线图。

调试截图

如图所示：

• 输入参数为 metricNames、appId、时间范围；
• 返回结果按时间戳对应数值；
• 渲染后即可得到时序曲线。

后续内容

我们将从代码阶段给大家解读，不同参数的组合查询实战