View a markdown version of this page

QueryMetrics - Amazon CloudWatch
URL 查询参数所需的 IAM 权限结果限制示例请求示例响应

QueryMetrics

QueryMetrics 操作会在单个时间点评估 PromQL 即时查询，或在一段时间范围内评估查询。

有效的 HTTP 动词

GET, POST

有效的 URI

/api/v1/query：在单个时间点评估即时查询。

/api/v1/query_range：在一段时间范围内评估查询。

完整的请求 URL 由 AWS 区域的 CloudWatch 监控主机与操作路径组合而成，例如 https://monitoring.AWS Region.amazonaws.com/api/v1/query。有关端点、签名和所需 IAM 权限的信息，请参阅 PromQL 查询。

URL 查询参数

以下参数在 GET 请求的 URL 查询字符串中传递，或在 POST 请求中作为表单编码的请求体字段传递。

参数 适用于 说明

query

二者

必需。要评估的 PromQL 表达式字符串。表达式必须按名称选择指标，例如 {"http.server.active_requests"} 或 {__name__="http.server.active_requests"}。不支持仅按标签选择序列而不带指标名称。

time

/api/v1/query

可选。评估时间戳，格式为 RFC 3339 时间戳或 Unix 时间戳。默认为当前服务器时间。

start

/api/v1/query_range

必需。时间范围的开始时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

end

/api/v1/query_range

必需。时间范围的结束时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

step

/api/v1/query_range

必需。查询解析步长，格式为 duration 或以秒为单位的浮点数。

limit

二者

可选。要返回的唯一时间序列的数量上限，范围为 1 到 500。如果未指定 limit，CloudWatch 将返回数量上限（500）。请参阅结果限制。

Duration

与 Prometheus 兼容的 API 中的 duration 是一个数值，后面紧跟以下单位之一：

  • ms 毫秒

  • s 秒

  • m 分钟

  • h 小时

  • d 天，假设一天始终是 24 小时

  • w 周，假设一周总始终是 7 天

  • y 年，假设一年始终是 365 天

所需的 IAM 权限

要调用 QueryMetrics，调用身份必须同时具有以下 IAM 操作：

  • cloudwatch:GetMetricData

  • cloudwatch:ListMetrics

有关所有 PromQL 操作的完整 IAM 操作映射，请参阅 PromQL的 IAM 权限。

结果限制

单个 /api/v1/query 或 /api/v1/query_range 响应最多可返回 500 个唯一时间序列。要请求更少的结果，请传递 limit 参数，其值范围为 1 到 500。如果未指定 limit，CloudWatch 会返回数量上限。

如果匹配的系列超出上限，响应会被截断，并在标准的 Prometheus warnings 字段中包含一条消息。HTTP 状态码保持为 200。

有关 PromQL 限制的完整列表，包括 TPS、并发和 24 小时扫描窗口，请参阅 PromQL 限额和限制。

示例请求

以下 POST 请求在表单编码的请求体中传递 PromQL 表达式。{、} 和 " 等特殊字符采用百分比编码。

POST /api/v1/query HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

query=sum(%7B%22http.server.active_requests%22%7D)

使用 awscurl 进行相同的调用：

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'query=sum({"http.server.active_requests"})'

示例响应

成功的响应使用标准的 Prometheus JSON 信封格式：

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1780000000.000,
                    "42"
                ]
            }
        ]
    }
}

如果结果集超出每次调用的上限，CloudWatch 会返回被截断的 result 数组，并在 warnings 字段中包含一条消息：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [ ... up to 500 series ... ]
    },
    "warnings": [
        "result truncated to the maximum of 500 series; refine the query or use the limit parameter"
    ]
}