View a markdown version of this page

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

GetLabels

GetLabels 操作会返回指标存储中存在的标签名称，或返回特定标签名称的值。

有效的 HTTP 动词

GET、POST（对于 /api/v1/labels）。

用于 /api/v1/label/label_name/values 的 GET。

有效的 URI

/api/v1/labels：返回标签名称列表。

/api/v1/label/label_name/values：返回指定标签的值列表。

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

URL 查询参数

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

参数 适用于 说明

match[]

二者

可选。一个序列选择器，用于限制在计算结果时要考虑的序列。选择器支持精确匹配 (=)、不等于 (!=)、正则表达式匹配 (=~) 和正则表达式否定匹配 (!~)。可以一次或多次指定 match[] 来组合选择器。有关选择器语法的更多信息，请参阅 PromQL 查询。

start

二者

可选。要考虑的时间范围的开始时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

end

二者

可选。要考虑的时间范围的结束时间，格式为 RFC 3339 时间戳或 Unix 时间戳。

limit

二者

可选。要返回的唯一标签的数量上限，范围为 1 到 10000。如果未指定 limit，CloudWatch 将返回数量上限（10,000）。请参阅结果限制。

所需的 IAM 权限

要在任一路径上调用 GetLabels，调用身份必须具有以下 IAM 操作：

  • cloudwatch:ListMetrics

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

结果限制

单个 /api/v1/labels 或 /api/v1/label/label_name/values 响应最多可以返回 10,000 个标签。要请求更少的结果，请传递 limit 参数，其值范围为 1 到 10000。如果未指定 limit，CloudWatch 会返回数量上限。

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

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

示例请求

使用 POST 请求和空请求体列出所有标签名称：

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

使用 awscurl 进行相同的调用：

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/labels' \
    -H 'Content-Type: application/x-www-form-urlencoded'

列出匹配选择器的标签名称。选择器和时间范围作为表单编码字段在请求体中传递：

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/labels' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'match[]={"http.server.active_requests","@aws.region"=~"us-.*"}&start=1780662000&end=1780665600'

列出 @resource.service.name 标签的值。标签名称是 URL 路径的一部分，采用百分比编码 (@ → %40)。此路径仅支持 GET：

GET /api/v1/label/%40resource.service.name/values HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

使用 awscurl 进行相同的调用：

awscurl --service monitoring --region us-east-1 \
    'https://monitoring.us-east-1.amazonaws.com/api/v1/label/@resource.service.name/values'

示例响应

成功的响应使用标准的 Prometheus JSON 信封格式。data 字段是一个字符串数组。

/api/v1/labels 的响应：

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

{
    "status": "success",
    "data": [
        "__name__",
        "@aws.account",
        "@aws.region",
        "@resource.service.name",
        "@resource.cloud.region",
        "InstanceId"
    ]
}

/api/v1/label/label_name/values 的响应：

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

{
    "status": "success",
    "data": [
        "myservice",
        "checkout-api",
        "billing-worker"
    ]
}