远程读
更新时间：2026-04-15
接口描述
通过 Remote Read 读取相应监控实例中的监控数据，支持通过 Prometheus 的 /query_range 和 /query 接口查询区间数据或即时数据。
权限说明
使用远程读功能前，需要先在相应的监控实例详情页生成 Token，并在请求头 Authorization 中携带该 Token。按以下步骤获取对应监控实例Token：
- 进入监控实例详情页（步骤参考 查看实例) 。
- 在监控实例页面下方单击生成Token并复制，如果没有则点击【生成token】。
请求
请求结构
使用 Prometheus 的 query_range 查询示例：
Bash
1curl -L -g -X POST '{remoteReadUrl}/prometheus/api/v1/query_range' \
2 -H 'Authorization: Bearer {token}' \
3 -H 'InstanceId: {instanceId}' \
4 -H 'Content-Type: application/x-www-form-urlencoded' \
5 --data-urlencode 'query={query}' \
6 --data-urlencode 'step={step}' \
7 --data-urlencode 'start={start}' \
8 --data-urlencode 'end={end}'说明
- 如果需要调用
/query接口，将 URL 中的query_range替换为query，并去掉step、start、end参数。 POST可以用GET替换。
Bash
1curl -L -g -X GET '{remoteReadUrl}/prometheus/api/v1/query?query={query}' \
2 -H 'Authorization: Bearer {token}' \
3 -H 'InstanceId: {instanceId}' \
4 -H 'Content-Type: application/x-www-form-urlencoded'请求头域
除公共头域外，特殊头域：
| 头域 | 是否必须 | 说明 |
|---|---|---|
| Content-Type | 是 | 请求参数类型，填写 application/x-www-form-urlencoded |
| Authorization | 是 | 监控实例Token，获取方式参考上面的接口描述 |
| InstanceId | 是 | 监控实例ID |
请求参数
| 参数名称 | 类型 | 是否必选 | 参数位置 | 描述 |
|---|---|---|---|---|
| remoteReadUrl | String | 是 | Path 参数 | 监控实例 Remote Read 的公网 URL 前缀。 |
| query | String | 是 | Body 参数 | 查询的指标表达式，支持直接填写指标名，也支持带 Label 选择器的 PromQL 表达式。使用 GET 调用时，将该参数放入 URL 查询串。 |
| step | Int | 是 | Body 参数 | 查询数据步长，单位：秒。仅在 /query_range 请求中必填；使用 GET 调用时，可放入 URL 查询串。 |
| start | Long Int | 是 | Body 参数 | 查询开始时间戳，单位：秒。仅在 /query_range 请求中必填；使用 GET 调用时，可放入 URL 查询串。 |
| end | Long Int | 是 | Body 参数 | 查询结束时间戳，单位：秒。仅在 /query_range 请求中必填；使用 GET 调用时，可放入 URL 查询串。 |
响应头域除公共头域外，无其它特殊头域。
响应参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| status | String | 请求是否成功。 |
| isPartial | Bool | 查询结果是否为部分数据。 |
| data | Object | 返回的数据信息，Prometheus 的相关解释参考 Range queries。 |
| data.resultType | String | 查询结果类型，如 matrix 或 vector。 |
| data.result | List | 查询结果列表，列表项包含 metric 以及 values 或 value 等信息。 |
| data.result[].metric | Map | 查询指标的所有维度。 |
| data.result[].values | List | 区间查询返回的样本点列表，每个元素为 [时间戳, 数值]。 |
| data.result[].value | List | 即时查询返回的单个样本点，格式为 [时间戳, 数值]。 |
请求示例
Bash
1curl -L -g -X POST 'http://cprom.gz.baidubce.com/select/prometheus/api/v1/query_range' \
2 -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lc3BhY2Ui****HJvbS03bjU4NjN3MjEiLCJzZWNyZXROYW1lIjoiYWdlbnQtN2ZzNTNrN2MxIiwiZXhwIjoxNzE4MzM1MTA3LCJpc3MiOiJjcHJvbSJ9.5JJX_gl76aLagz8jpq7PT5AI34jdlC36IwCaYr46qWo' \
3 -H 'InstanceId: cprom-****' \
4 -H 'Content-Type: application/x-www-form-urlencoded' \
5 --data-urlencode 'query=container_cpu_usage_seconds_total{container="nginx", clusterID="cce-****"}' \
6 --data-urlencode 'step=60' \
7 --data-urlencode 'start=1748328897' \
8 --data-urlencode 'end=1748329497'响应示例
Text
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 27 May 2025 03:28:11 GMT
4X-Server-Hostname: vmselect-cprom-****-1
5
6{
7 "status": "success",
8 "isPartial": false,
9 "data": {
10 "resultType": "matrix",
11 "result": [
12 {
13 "metric": {
14 "__name__": "container_cpu_usage_seconds_total",
15 "env": "test"
16 },
17 "values": [
18 [
19 1748328897,
20 "10"
21 ]
22 ]
23 }
24 ]
25 }
26}评价此篇文章