本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 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 查詢、OTel 擴充已取代的 AWS 指標，以及 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，您可以執行下列動作：
+ 依指標名稱和標籤比對器選取時間序列。
+ 跨時間序列套用數學函數和運算子。
+ 跨維度彙總指標，例如服務、區域或帳戶。
+ 運算速率、長條圖、分位數和移動平均值。

您可以在 中以互動方式使用 PromQL 查詢[在 Query Studio 中執行 PromQL 查詢 （預覽）](CloudWatch-PromQL-QueryStudio.md)，也可以建立 CloudWatch 警示。如需詳細資訊，請參閱[PromQL 查詢](CloudWatch-PromQL-Querying.md)及[在警示中使用 PromQL](CloudWatch-PromQL-Alarms.md)。

**注意**  
CloudWatch 根據 Prometheus 3.0 規格使用 PromQL。這包括支援 UTF-8 指標名稱和標籤名稱。

下列概念對於在 CloudWatch 中使用 PromQL 至關重要。


| 概念 | Description | 
| --- | --- | 
| **時間序列** | 由指標名稱和一組稱為*標籤*的鍵值對識別的時間戳記值串流。指標名稱和標籤的每個唯一組合都會形成不同的時間序列。 | 
| **即時向量** | 一組時間序列，其中包含每個序列的單一範例，全部共用相同的時間戳記。由類似 的查詢傳回`{"http.server.active_requests", "@resource.service.name"="myservice"}`。 | 
| **範圍向量** | 一組時間序列，其中包含每個序列隨時間變化的資料點範圍。透過在括號中附加持續時間選擇器來建立，例如 `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`。 | 
| **標籤** | 連接到時間序列的鍵/值對。在 OTLP 擷取指標中，標籤衍生自資源屬性、檢測範圍、資料點屬性和 AWS特定中繼資料。 | 
| **標籤比對器** | 大括號中的表達式，可依標籤值篩選時間序列。支援完全比對 (`=`)、不等於 (`!=`)、regex 比對 (`=~`) 和負 regex 比對 (`!~`)。 | 
| **彙總運算子** | 將多個時間序列合併為較少序列的函數。常見的運算子包括 `sum`、`avg`、`min`、`count`、 `max`和 `topk`。 | 

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

下表列出 PromQL 的限制：


| 限制 | Value | 其他資訊 | 錯誤碼 | 
| --- | --- | --- | --- | 
| 每個帳戶查詢請求的最大 TPS | 300 | 每個帳戶每秒允許的查詢請求數目上限 (/query， /query\$1range)。 | 422 | 
| 每個帳戶的探索請求最大 TPS | 10 | 每個帳戶每秒允許的探索請求數上限 (/series、/label、/label\$1values)。 | 422 | 
| 每個帳戶的並行查詢請求上限 | 30 | 帳戶可同時主動執行的查詢數量上限 (/query、/query\$1range)。 | 429 | 
| 每個帳戶的並行探索請求上限 | 30 | 帳戶可同時主動執行的探索請求數目上限 (/系列、/標籤、/label\$1values)。 | 429 | 
| 每個查詢請求傳回的最大序列數 | 500 | 查詢請求 (/query、/query\$1range) 可以傳回的唯一時間序列數目上限。 | 200 - 截斷的回應 | 
| 每個探索請求傳回的最大標籤數 | 10,000 | 探索請求 (/系列、/標籤、/label\$1values) 可傳回的唯一標籤數量上限。 | 200 - 截斷的回應 | 
| 每個請求的最大範圍 | 7 天 | 查詢可以跨越的時間範圍上限，包括範圍參數和回顧期間。 | 422 | 
| 每個 24 小時時段掃描的最大序列數 | 100,000 | 每個 24 小時查詢執行時段可掃描的唯一時間序列數目上限。 | 422 | 
| 每個 24 小時時段掃描的樣本上限 | 300，000，000 | 每個 24 小時查詢執行時段可掃描的樣本數量上限。 | 422 | 
| 每個 24 小時時段處理的樣本上限 | 3，000，000，000 | 每個 24 小時查詢執行時段可處理的樣本數量上限。 | 422 | 
| Execution timeout (執行逾時) | 20 秒 | 引擎可以評估查詢的時間上限，不包括在佇列中花費的時間，以及從儲存體擷取資料的時間。 | 422 | 

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

下表列出可使用 OTLP 指標擷取、PromQL 查詢和 Query Studio AWS 的區域。


| 區域名稱 | 區域代碼 | OTLP 指標擷取 | PromQL 查詢 | 查詢 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:GetMetricData`和 `cloudwatch:ListMetrics`許可。下表列出新的 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` |