PromQL 查询

您通过 指标端点 将 OpenTelemetry 指标摄取到 CloudWatch 时，分层 OTLP 数据模型会扁平化为与 PromQL 兼容的标签。本节介绍标签结构、用于查询这些标签的 PromQL 语法以及 PromQL 中对 UTF-8 的支持。

在 CloudWatch 中使用 PromQL 时，@ 前缀惯例会将 OTLP 范围的标签与标准 Prometheus 标签区分开来。每个作用域内的字段使用双 @ 前缀（例如 @resource.@schema_url），而属性使用单 @ 作用域前缀，例如 @resource.service.name。数据点属性还支持裸露（无前缀）访问，以向后兼容标准 PromQL 查询，例如 {"http.server.active_requests"} 和 {"@datapoint.@name"="http.server.active_requests"} 等效。

PromQL 表达式用花括号括起来，用于指定指标名称和一组可选的标签匹配器。以下示例选择了 http.server.active_requests 指标的所有时间序列：

{"http.server.active_requests"}

以下示例选择了 http.server.active_requests 指标的所有时间序列，其中 OpenTelemetry 资源属性 service.name 等于 myservice：

{"http.server.active_requests", "@resource.service.name"="myservice"}

您可以在单个查询中组合多个标签匹配器。以下示例选择了 http.server.active_requests 指标的所有时间序列，其中在所有美国区域，OpenTelemetry 资源属性 service.name 等于 myservice：

{"http.server.active_requests",
 "@resource.service.name"="myservice",
 "@aws.region"=~"us-.*"}

以下示例显示了范围查询。该示例计算每个时间序列在指定时间范围内所有数据点的平均值：

avg_over_time(
  {"http.server.active_requests",
   "@resource.service.name"="myservice"}[5m]
)

下表总结了每个 OTLP 范围的前缀惯例：

使用 PromQL 查询 AWS 已出售指标

为了能够在 PromQL 中查询 AWS 已出售指标，您首先需要启用已出售指标的 OTel 补充功能。请参阅：采用 OpenTelemetry 格式的 AWS 已出售指标。

启用 OTel 补充功能后，可通过 PromQL 使用其他标签查询 AWS 已出售指标。指标名称与原始 CloudWatch 指标名称相同，原始 CloudWatch 维度可作为数据点属性提供。以下标签可用（以下示例适用于 EC2 实例）：

以下示例为特定的 Lambda 函数选择了 Invocations：

{Invocations, FunctionName="my-api-handler"}

以下示例为具有特定团队标签的所有函数选择了 Errors Lambda：

{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}

以下示例计算按团队分组的 Invocations Lambda 总数：

sum by ("@aws.tag.Team")(
    {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)

以下示例选择了 EC2 CPUUtilization 指标的所有时间序列。"@instrumentation.@name"="cloudwatch.aws/ec2" 的用法是为了专门匹配来自 EC2 的 CPUUtilization，而不是来自其他 AWS 服务（例如 Amazon Relational Database Service）的 CPUUtilization：

histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})

从 Grafana 查询

您可以通过添加 Amazon Managed Service for Prometheus 数据来源插件并将其指向 CloudWatch 监控端点，从 Grafana 查询 CloudWatch PromQL 数据。该插件内置了 SigV4 签名，且始终处于启用状态，因此无需打开开关。该插件发布在 grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/；在添加数据来源之前，请先从 Grafana 插件目录中安装它。AMP 插件 v3.0.0 需要 Grafana >=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5。

IAM 先决条件：Grafana 所使用的凭证对应的 IAM 主体必须同时拥有 cloudwatch:GetMetricData（即时查询和范围查询所需）和 cloudwatch:ListMetrics（序列和标签发现所需）。有关更多信息，请参阅 PromQL的 IAM 权限。

要配置 Grafana，请完成以下步骤：

从 Amazon Managed Grafana 查询

您可以通过添加指向 CloudWatch 监控端点的 Amazon Managed Service for Prometheus 数据来源，从 Amazon Managed Grafana 工作区查询 CloudWatch PromQL 数据。该数据来源插件使用工作区 IAM 角色自动对请求进行 SigV4 签名；SigV4 始终处于启用状态，无需配置开关。该插件在 Amazon Managed Grafana 版本 12 及更高版本中可用。有关更多信息，请参阅《Amazon Managed Grafana 用户指南》中的连接到 Amazon Managed Service for Prometheus 数据来源。

IAM 先决条件：Amazon Managed Grafana 工作区 IAM 角色必须同时拥有 cloudwatch:GetMetricData（即时查询和范围查询所需）和 cloudwatch:ListMetrics（序列和标签发现所需）。有关更多信息，请参阅 PromQL的 IAM 权限。

要配置数据来源，请完成以下步骤：

使用 MCP 工具查询

CloudWatch MCP 服务器提供模型上下文协议（MCP）工具，允许人工智能助手和开发工具代您查询 CloudWatch PromQL 数据。MCP 工具会自动处理身份验证和请求格式化，因此您可以专注于编写 PromQL 查询，而无需管理 HTTP 请求和 SigV4 签名。

CloudWatch MCP 服务器中提供以下 PromQL 工具：

有关参数、配置和设置说明的完整详细信息，请参阅 CloudWatch MCP 服务器文档中的 Tools for CloudWatch PromQL。

使用 HTTP API 查询

您还可以通过直接调用与 Prometheus 兼容的 HTTP 端点，以编程方式查询 CloudWatch PromQL 数据。请求必须使用 monitoring 作为服务名称，通过 AWS 签名版本 4 进行签名。

PromQL 端点遵循模式 https://monitoring.AWS Region.amazonaws.com/api/v1/operation。例如，对于美国东部（弗吉尼亚州北部）（us-east-1）区域，即时查询的端点为 https://monitoring.us-east-1.amazonaws.com/api/v1/query。

有关完整的 API 参考，包括支持的操作、请求参数和响应格式，请参阅与 Prometheus 兼容的 API。有关支持 PromQL 查询的 AWS 区域列表，请参阅支持的 AWS 区域。有关每个操作所需的 IAM 操作，请参阅 PromQL的 IAM 权限。