# 使用 PromQL 查询创建警报
<a name="Create_PromQL_Alarm"></a>

您可以创建 CloudWatch 警报，该警报使用 PromQL 即时查询来监控通过 CloudWatch OTLP 端点摄取到的指标。查询返回的所有匹配时间序列都被视为违规，警报会将每个违规的时间序列作为贡献者进行跟踪。有关 PromQL 警报的工作原理的更多信息，请参阅 [PromQL 警报](alarm-promql.md)。

## 使用 AWS 管理控制台 创建 PromQL 警报
<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. 在**条件**下面，指定以下内容：
   + 在**评估间隔**中，选择 **1 minute** 以定义评估 PromQL 查询的频率。
   + 在**待处理周期**中，输入 **120**，这是贡献者进入 ALARM 状态之前必须处于违规状态的持续时间（以秒为单位）。
   + 在**恢复周期**中，输入 **300**，这是贡献者在进入 OK 状态之前不得违规的持续时间（以秒为单位）。

1. 根据需要配置通知和操作。

1. 添加告警的名称和描述。

1. 选择**下一步**。

1. 选择**创建警报**。

## 创建 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 警报**  
此警报在过渡到 `ALARM` 状态之前等待 300 秒（5 分钟），在恢复前等待 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. 在**指标**下方的导航窗格中，选择 **Query 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. 您将被重定向到 CloudWatch 警报创建页面，该页面预先填充了 PromQL 查询。

1. 在**条件**下面，指定以下内容：
   + 在**评估间隔**中，选择 **1 minute** 以定义评估 PromQL 查询的频率。
   + 在**待处理周期**中，输入 **60**，这是查询进入 ALARM 状态之前必须处于违规状态的持续时间（以秒为单位）。这意味着在警报触发之前，延迟必须超过阈值至少 60 秒。
   + 在**恢复周期**中，输入 **120**，这是查询进入 OK 状态之前不得违规的持续时间（以秒为单位）。这意味着在警报恢复之前，延迟必须保持在阈值以下至少 120 秒。

1. 根据需要配置通知和操作。

1. 添加告警的名称和描述。

1. 选择**下一步**。

1. 选择**创建警报**。

**注意**  
PromQL 查询必须返回单个时间序列才能创建警报。如果查询返回多个时间序列，请在创建警报之前使用 `sum`、`avg` 或 `topk` 等聚合函数，将结果简化为单个序列。