【Ambari监控】监控数据接口查询方法-EW帮帮网

附录：完整内容和源代码下载请参照

https://doc.janettr.com/

在这里插入图片描述

一、接口介绍

/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 文件，即可方便调试。

操作流程：

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

调试截图

如图所示：

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

【Ambari监控】监控数据接口查询方法