# 使用 PromQL 查询指标
<a name="CloudWatch-PromQL"></a>

**Topics**
+ [什么是 Prometheus 查询语言（PromQL）？](#CloudWatch-PromQL-WhatIs)
+ [PromQL 限额和限制](#CloudWatch-PromQL-Limits)
+ [支持的 AWS 区域](#CloudWatch-PromQL-Regions)
+ [PromQL的 IAM 权限](#CloudWatch-PromQL-IAM)
+ [PromQL 查询](CloudWatch-PromQL-Querying.md)
+ [在 Query Studio 中运行 PromQL 查询（预览版）](CloudWatch-PromQL-QueryStudio.md)
+ [在警报中使用 PromQL](CloudWatch-PromQL-Alarms.md)

**注意**  
OTLP 指标摄取、PromQL 查询、已出售 AWS 指标的 OTel 补充以及 Query Studio 均为公开预览版，免费提供，并可能会发生变更。

## 什么是 Prometheus 查询语言（PromQL）？
<a name="CloudWatch-PromQL-WhatIs"></a>

Prometheus 查询语言（PromQL）是一种功能性查询语言，可让您实时选择、聚合与转换时间序列数据。PromQL 最初是为 Prometheus 设计，现已成为一种流行的指标查询语言。

Amazon CloudWatch 支持使用 PromQL 来查询指标，包括通过 OpenTelemetry Line Protocol（OTLP）摄取的指标和 [AWS 补充的已出售指标](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html)。您摄取 OTLP 指标时，CloudWatch 会保留遥测数据的完整语义结构，包括资源属性、埋点范围、数据点属性和特定于 AWS 的元数据，并将它们显示为可查询的 PromQL 标签。

借助 PromQL，您可以执行以下操作：
+ 按指标名称和标签匹配器选择时间序列。
+ 跨时间序列应用数学函数和运算符。
+ 跨服务、区域或账户等维度聚合指标。
+ 计算费率、直方图、分位数和移动平均值。

您可以在 [在 Query Studio 中运行 PromQL 查询（预览版）](CloudWatch-PromQL-QueryStudio.md) 中以交互方式使用 PromQL 查询，也可以创建 CloudWatch 警报。有关更多信息，请参阅[PromQL 查询](CloudWatch-PromQL-Querying.md)和[在警报中使用 PromQL](CloudWatch-PromQL-Alarms.md)。

**注意**  
CloudWatch 根据 Prometheus 3.0 规范使用 PromQL。这包括对 UTF-8 指标名称和标签名称的支持。

以下概念是在 CloudWatch 中使用 PromQL 的基础。


| 概念 | 说明 | 
| --- | --- | 
| **时间序列** | 由指标名称和一组称为*标签*的键值对标识的带有时间戳的一系列值。指标名称和标签的每个唯一组合构成一个不同的时间序列。 | 
| **即时向量** | 一组时间序列，包含每个序列的单个样本，所有序列共享相同的时间戳。由诸如 `{"http.server.active_requests", "@resource.service.name"="myservice"}` 之类的查询返回。 | 
| **范围向量** | 一组时间序列，包含每个序列随时间变化的一系列数据点。通过在方括号中附加持续时间选择器来创建，例如 `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`。 | 
| **标签** | 附加到时间序列的键值对。在 OTLP 摄取的指标中，标签源自资源属性、埋点范围、数据点属性和特定于 AWS 的元数据。 | 
| **标签匹配器** | 花括号中的表达式，用于按标签值筛选时间序列。支持精确匹配 (`=`)、不等于 (`!=`)、正则表达式匹配 (`=~`) 和负正则表达式匹配 (`!~`)。 | 
| **聚合操作符** | 一种将多个时间序列组合成更少序列的函数。常见的操作符包括 `sum`、`avg`、`min`、`max`、`count` 和 `topk`。 | 

## PromQL 限额和限制
<a name="CloudWatch-PromQL-Limits"></a>

下表列出了 PromQL 的限额和限制：


| 限制 | 值 | 附加信息 | 错误代码 | 
| --- | --- | --- | --- | 
| 每个账户查询请求的最大 TPS | 300 | 每个账户允许的每秒查询请求（/query、/query\$1range）的最大数量。 | 422 | 
| 每个账户的发现请求的最大 TPS | 10 | 每个账户允许的每秒发现请求（/series、/label、/label\$1values）的最大数量。 | 422 | 
| 每个账户的最大并发查询请求数量 | 30 | 一个账户可以同时主动执行的查询（/query、/query\$1range）的最大数量。 | 429 | 
| 每个账户的最大并发发现请求数量 | 30 | 一个账户可以同时主动执行的发现请求（/series、/label\$1values）的最大数量。 | 429 | 
| 每个查询请求返回的最大序列数量 | 500 | 查询请求（/query、/query\$1range）可返回的唯一时间序列的最大数量。 | 200 – 已截断响应 | 
| 每个发现请求返回的最大标签数量 | 10000 | 发现请求（/series、/labels、/label\$1values）可返回的唯一标签的最大数量。 | 200 – 已截断响应 | 
| 每个请求的最大范围 | 7 days | 查询可跨越的最大时间范围，包括范围参数和回顾期。 | 422 | 
| 每 24 小时时段扫描的最大序列数量 | 100000 | 每 24 小时时段查询执行可扫描的唯一时间序列的最大数量。 | 422 | 
| 每 24 小时时段扫描的最大样本数量 | 3 亿 | 每 24 小时时段查询执行可扫描的最大样本数量。 | 422 | 
| 每 24 小时时段处理的最大样本数量 | 30 亿 | 每 24 小时时段查询执行可处理的最大样本数量。 | 422 | 
| Execution timeout (执行超时) | 20 秒 | 引擎可花费在评估查询上的最长时间，不包括排队和从存储中提取数据所花费的时间。 | 422 | 

## 支持的 AWS 区域
<a name="CloudWatch-PromQL-Regions"></a>

下表列出了提供 OTLP 指标摄取、PromQL 查询和 Query Studio 的 AWS 区域。


|  区域名称 | 区域代码 | IVS 指标摄取 | PromQL 查询 | Query Studio | 
| --- | --- | --- | --- | --- | 
| 美国东部（弗吉尼亚州北部） | us-east-1 | ✓ | ✓ | ✓ | 
| 美国西部（俄勒冈州） | us-west-2 | ✓ | ✓ | ✓ | 
| 欧洲地区（爱尔兰） | eu-west-1 | ✓ | ✓ | ✓ | 
| 亚太地区（新加坡） | ap-southeast-1 | ✓ | ✓ | ✓ | 
| 亚太地区（悉尼） | ap-southeast-2 | ✓ | ✓ | ✓ | 

## PromQL的 IAM 权限
<a name="CloudWatch-PromQL-IAM"></a>

要执行 PromQL 查询，您需要同时具有 `cloudwatch:ListMetrics` 和 `cloudwatch:GetMetricData` 权限。下表列出了新的 PromQL API 操作及其所需 IAM 操作：


| API 操作 | 所需的操作 | 
| --- | --- | 
| ExecuteMetricQueryPost | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| ExecuteMetricQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| ExecuteMetricRangeQuery | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| ExecuteMetricRangeQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| ExecuteMetricSeriesPost | `cloudwatch:ListMetrics` | 
| ExecuteMetricSeriesGet | `cloudwatch:ListMetrics` | 
| ExecuteMetricLabelsPost | `cloudwatch:ListMetrics` | 
| ExecuteMetricLabelsGet | `cloudwatch:ListMetrics` | 
| ExecuteMetricLabelValuesGet | `cloudwatch:ListMetrics` |