# PromQL 쿼리를 사용하여 경보 생성
<a name="Create_PromQL_Alarm"></a>

PromQL 인스턴트 쿼리를 사용하여 CloudWatch OTLP 엔드포인트를 통해 수집된 지표를 모니터링하는 CloudWatch 경보를 생성할 수 있습니다. 쿼리에서 반환하는 일치하는 모든 시계열은 위반으로 간주되며, 경보는 각 위반 시계열을 기고자로 추적합니다. PromQL 경보의 작동 방식에 대한 자세한 내용은 [PromQL 경보](alarm-promql.md) 섹션을 참조하세요.

## AWS Management Console을 사용하여 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. **경보 생성**을 선택하세요.

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 게이지 지표가 20 미만으로 떨어질 때 트리거되는 PromQL 경보 생성**  

```
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>

이 예제는 서비스의 평균 HTTP 요청 기간이 500밀리초를 초과할 때 이를 알리는 PromQL 경보를 Query Studio에서 생성하는 방법을 보여줍니다.

임계값이 별도의 단계로 구성된 표준 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. PromQL 쿼리가 미리 채워진 CloudWatch 경보 생성 페이지로 리디렉션됩니다.

1. **조건**에서 다음을 지정합니다.
   + **평가 간격**에서 **1 minute**을 선택하여 PromQL 쿼리가 평가되는 빈도를 정의합니다.
   + **보류 기간**에 **60**을 입력합니다. 이 값은 ALARM 상태가 되기 전에 쿼리가 위반해야 하는 기간을 초 단위로 입력한 값입니다. 즉, 경보가 실행되기 전에 지연 시간이 최소 60초 동안 임계값을 초과해야 합니다.
   + **복구 기간**에 **120**을 입력합니다. 이 값은 OK 상태가 되기 전에 쿼리가 위반하지 않아야 하는 기간을 초 단위로 입력한 값입니다. 즉, 경보가 복구되기 전에 지연 시간이 최소 120초 동안 임계값 미만을 유지해야 합니다.

1. 필요에 따라 알림 및 작업을 구성하세요.

1. 경보에 이름과 설명(선택 사항)을 추가하세요.

1. **다음**을 선택합니다.

1. **경보 생성**을 선택하세요.

**참고**  
경보를 생성하려면 PromQL 쿼리가 단일 시계열을 반환해야 합니다. 쿼리가 여러 시계열을 반환하는 경우 경보 생성 전에 집계 함수(예: `sum`, `avg`, `topk`)를 사용하여 결과를 단일 시리즈로 줄입니다.