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

# 使用 PromQL 查詢建立警示
<a name="Create_PromQL_Alarm"></a>

您可以建立 CloudWatch 警示，該警示使用 PromQL 即時查詢來監控透過 CloudWatch OTLP 端點擷取的指標。查詢傳回的所有相符時間序列都視為違規，警示會將每個違規時間序列追蹤為貢獻者。如需 PromQL 警示如何運作的詳細資訊，請參閱 [PromQL 警示](alarm-promql.md)。

## 使用 建立 PromQL 警示 AWS 管理主控台
<a name="promql-alarm-create-console"></a>

此範例說明如何建立警示來監控指標，並在其值低於 20 時提醒您。

**建立 PromQL 警示**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽窗格中，選擇 **Alarms** (警示)、**All alarms** (所有警示)。

1. 選擇 **Create alarm** (建立警示)。

1. 為指標類型選擇 **PromQL**。

1. 在**編輯器**模式中，輸入 PromQL 查詢：

   ```
   my_gauge_metric < 20
   ```

1. 在 **Conditions (條件)** 下，指定以下內容：
   + 針對**評估間隔**，選擇 **1 minute**，以定義 PromQL 查詢的評估頻率。
   + 對於**待定期間**，輸入 **120**，在進入 ALARM 狀態之前，參與者必須違反的持續時間，以秒為單位。
   + 對於**復原期間**，輸入 **300**，在進入 OK 狀態之前，參與者不得違反持續時間，以秒為單位。

1. 視需要設定通知和動作。

1. 輸入警示的名稱和說明。

1. 選擇**下一步**。

1. 選擇 **Create alarm** (建立警示)。

## 建立 PromQL 警示 (AWS CLI)
<a name="promql-alarm-create-cli"></a>

使用 [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) API 動作來建立 PromQL 警示。

**Example 建立 PromQL 警示，在指標低於 20 時觸發**  

```
aws cloudwatch put-metric-alarm \
  --alarm-name MyPromQLAlarm \
  --evaluation-criteria '{"PromQLCriteria":{"Query":"my_gauge_metric < 20"}}' \
  --evaluation-interval 60
```

**Example 建立具有擱置期間的 PromQL 警示**  
此警示會等待 300 秒 (5 分鐘） 再轉換為 `ALARM` 狀態，並等待 600 秒 (10 分鐘） 再復原。  

```
aws cloudwatch put-metric-alarm \
  --alarm-name HighLatencyAlarm \
  --evaluation-criteria '{"PromQLCriteria":{"Query":"histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 0.5","PendingPeriod":300,"RecoveryPeriod":600}}' \
  --evaluation-interval 60
```

**Example 使用 SNS 通知動作建立 PromQL 警示**  

```
aws cloudwatch put-metric-alarm \
  --alarm-name MyPromQLAlarmWithAction \
  --evaluation-criteria '{"PromQLCriteria":{"Query":"my_gauge_metric < 20","PendingPeriod":0,"RecoveryPeriod":0}}' \
  --evaluation-interval 60 \
  --alarm-actions arn:aws:sns:us-east-1:123456789012:MyTopic
```

## 從 Query Studio 建立 PromQL 警示
<a name="promql-alarm-create-query-studio"></a>

此範例示範如何從 Query Studio 建立 PromQL 警示，在服務的平均 HTTP 請求持續時間超過 500 毫秒時提醒您。

與閾值設定為個別步驟的標準 CloudWatch 警示不同，PromQL 警示會將警示條件 （閾值） 定義為查詢本身的一部分。例如，比較運算子 (`>`) 和閾值 (`0.5`) 會直接內嵌在 PromQL 表達式中。

**從 Query Studio 建立 PromQL 警示**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在**指標**下方的導覽窗格中，選擇**查詢 Studio （預覽）**。

1. 從查詢語言下拉式功能表中選取 **PromQL**。

1. 使用下列其中一種模式建置查詢：
   + 在**建置器**模式中，從指標欄位選取**指標**名稱 （例如，`http.server.request.duration`)。視需要新增標籤篩選條件 （例如 `@resource.service.name` = `my-api`)。若要定義警示閾值，請選取**基本操作** （例如，`>`)，然後輸入**數字** （例如，`0.5`)。
   + 在**程式碼**模式中，直接輸入 PromQL 表達式，例如：

     ```
     histogram_avg({"http.server.request.duration", "@resource.service.name"="my-api"}) > 0.5
     ```

1. 選擇**執行**以執行查詢，並確認它傳回預期的結果。

1. 從動作功能表中選擇**建立警示**。

1. 系統會將您重新導向至預先填入 PromQL 查詢的 CloudWatch 警示建立頁面。

1. 在 **Conditions (條件)** 下，指定以下內容：
   + 針對**評估間隔**，選擇 **1 minute**，以定義 PromQL 查詢的評估頻率。
   + 對於**待定期間**，輸入 **60**，查詢在進入 ALARM 狀態之前必須違反的持續時間，以秒為單位。這表示延遲必須超過閾值至少 60 秒，警示才會觸發。
   + 針對**復原期間**，輸入 **120**，在進入 OK 狀態之前，查詢不得違反的持續時間，以秒為單位。這表示延遲必須低於閾值至少 120 秒，警示才會復原。

1. 視需要設定通知和動作。

1. 輸入警示的名稱和說明。

1. 選擇**下一步**。

1. 選擇 **Create alarm** (建立警示)。

**注意**  
PromQL 查詢必須傳回單一時間序列才能建立警示。如果您的查詢傳回多個時間序列，請在建立警示之前使用彙總函數`topk`，例如 `sum`、 `avg`或 ，將結果減少為單一序列。