# PromQL 查询
<a name="CloudWatch-PromQL-Querying"></a>

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

**注意**  
Prometheus 3 中的 PromQL 支持在指标名称和标签名称中使用完整的 UTF-8 字符。这对于 OTLP 指标尤其重要，因为 OpenTelemetry 语义惯例在属性名称中使用点号，例如 `service.name`。以前，这些点号在翻译过程中被下划线所取代，这会导致 OTel 惯例中定义的内容与 Prometheus 中可查询的内容之间存在差异。

在 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 范围的前缀惯例：


| OTLP 范围 | 字段前缀 | 属性前缀 | 示例 | 
| --- | --- | --- | --- | 
| 资源 | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` | 
| 埋点作用域 | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` | 
| 数据点 | `@datapoint.@` | `@datapoint.` 或裸露 | `cpu="cpu0"` 或 `@datapoint.cpu="cpu0"` | 
| AWS 保留 | 不适用 | `@aws.` | `@aws.account_id="123456789"` | 

## 使用 PromQL 查询 AWS 已出售指标
<a name="CloudWatch-PromQL-Querying-Vended"></a>

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

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


| PromQL 标签 | 说明 | 示例 | 
| --- | --- | --- | 
| `InstanceId` | 原始 CloudWatch 维度，作为数据点属性 | `i-0123456789abcdef0` | 
| `"@resource.cloud.resource_id"` | 资源的完整 ARN | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` | 
| `"@resource.cloud.provider"` | 云提供商 | `aws` | 
| `"@resource.cloud.region"` | 此指标起源的 AWS 区域 | `us-east-1` | 
| `"@resource.cloud.account.id"` | 此指标起源的 AWS 账户 ID | `123456789012` | 
| `"@instrumentation.@name"` | 标识源服务的埋点作用域名称 | `cloudwatch.aws/ec2` | 
| `"@instrumentation.cloudwatch.source"` | 源服务标识符 | `aws.ec2` | 
| `"@instrumentation.cloudwatch.solution"` | 补充解决方案标识符 | `CloudWatchOTelEnrichment` | 
| `"@aws.tag.Environment"` | AWS 资源标签 | `production` | 
| `"@aws.account"` | 摄取此指标的 AWS 账户（系统标签） | `123456789012` | 
| `"@aws.region"` | 摄取此指标的 AWS 区域（系统标签） | `us-east-1` | 

以下示例为特定的 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 查询
<a name="CloudWatch-PromQL-Querying-Grafana"></a>

您可以通过添加 **Amazon Managed Service for Prometheus** 数据来源插件并将其指向 CloudWatch 监控端点，从 Grafana 查询 CloudWatch PromQL 数据。该插件内置了 SigV4 签名，且始终处于启用状态，因此无需打开开关。该插件发布在 [grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/](https://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 权限](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。

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

1. 从 Grafana 插件目录安装 **Amazon Managed Service for Prometheus** 数据来源插件。

1. 在 Grafana 中，转到**连接** > **数据来源**，选择**添加数据来源**，然后选择 **Amazon Managed Service for Prometheus**。

1. 将数据来源 **URL** 设置为 `https://monitoring.{{AWS Region}}.amazonaws.com`。

1. 将**区域**设置为 AWS 区域。选择适合您环境的**身份验证提供商**（默认凭证链、访问密钥或工作区 IAM 角色）。

1. 选择**保存并测试**。

## 从 Amazon Managed Grafana 查询
<a name="CloudWatch-PromQL-Querying-AMG"></a>

您可以通过添加指向 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 数据来源](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html)。

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

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

1. 在 Amazon Managed Grafana 工作区中，添加 **Amazon Managed Service for Prometheus** 数据来源。

1. 将数据来源 **URL** 设置为 `https://monitoring.{{AWS Region}}.amazonaws.com`。

1. 将**区域**设置为 AWS 区域。Amazon Managed Grafana 会从工作区 IAM 角色自动注入凭证；您无需配置静态密钥。

1. 选择**保存并测试**。

## 使用 MCP 工具查询
<a name="CloudWatch-PromQL-Querying-MCP"></a>

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

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


| 工具 | 说明 | 
| --- | --- | 
| `execute_promql_query` | 运行即时 PromQL 查询，返回单个时间点的指标值。 | 
| `execute_promql_range_query` | 在时间窗口内运行 PromQL 范围查询，返回用于分析趋势和绘制图表的时间序列数据。 | 
| `get_promql_label_values` | 检索特定 PromQL 标签的值，例如用于指标名称的 `__name__` 或用于服务的 `@resource.service.name`。 | 
| `get_promql_series` | 查找匹配 PromQL 标签选择器的时间序列，并返回每个匹配序列的完整标签集。 | 
| `get_promql_labels` | 列出所有可用的 PromQL 标签名称，以便您发现指标的标签结构。 | 

有关参数、配置和设置说明的完整详细信息，请参阅 CloudWatch MCP 服务器文档中的 [Tools for CloudWatch PromQL](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql)。

## 使用 HTTP API 查询
<a name="CloudWatch-PromQL-Querying-API"></a>

您还可以通过直接调用与 Prometheus 兼容的 HTTP 端点，以编程方式查询 CloudWatch PromQL 数据。请求必须使用 `monitoring` 作为服务名称，通过 [AWS 签名版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 进行签名。

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](CloudWatch-PromQL-APIs.md)。有关支持 PromQL 查询的 AWS 区域列表，请参阅[支持的 AWS 区域](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions)。有关每个操作所需的 IAM 操作，请参阅 [PromQL的 IAM 权限](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。