# Criar um alarme usando uma consulta em PromQL
<a name="Create_PromQL_Alarm"></a>

Você pode criar um alarme do CloudWatch que usa uma consulta instantânea do PromQL para monitorar métricas ingeridas por meio do endpoint do OTLP do CloudWatch. Todas as séries temporais correspondentes retornadas pela consulta são consideradas violações, e o alarme rastreia cada série temporal de violação como colaborador. Para obter mais informações sobre como os alarmes do PromQL funcionam, consulte [Alarmes do PromQL](alarm-promql.md).

## Criação de um alarme do PromQL usando o Console de gerenciamento da AWS
<a name="promql-alarm-create-console"></a>

Este exemplo mostra como criar um alarme que monitora uma métrica de medidor, e alerta você quando seu valor cai abaixo de 20.

**Para criar um alarme do PromQL**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, escolha **Alarms** (Alarmes), **All alarms** (Todos os alarmes).

1. Selecione **Criar alarme**.

1. Escolha **PromQL** para o tipo de métrica.

1. No modo **Editor**, insira a consulta do PromQL:

   ```
   my_gauge_metric < 20
   ```

1. Em **Conditions (Condições)**, especifique o seguinte:
   + Em **Intervalo de avaliação**, escolha **1 minute** para definir com que frequência a consulta do PromQL é avaliada.
   + Em **Período pendente**, insira **120**, que é a duração em segundos que um contribuidor deve estar em violação antes de entrar no estado de ALERTA.
   + Em **Período de recuperação**, insira **300**, que é a duração em segundos que um contribuidor deve estar em violação antes de entrar no estado de OK.

1. Configure notificações e ações conforme necessário.

1. Adicione um nome e uma descrição para o alarme.

1. Escolha **Próximo**.

1. Selecione **Criar alarme**.

## Criação de um alarme do PromQL (AWS CLI)
<a name="promql-alarm-create-cli"></a>

Use a ação da API [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) para criar um alarme do PromQL.

**Example Criar um alarme do PromQL que é acionado quando uma métrica de medição cai abaixo de 20**  

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

**Example Criar um alarme do PromQL com um período pendente**  
Esse alarme espera 300 segundos (5 minutos) antes de passar para o estado `ALARM`, e espera 600 segundos (10 minutos) antes de se recuperar.  

```
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 Criar um alarme do PromQL com uma ação de notificação do SNS**  

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

## Criação de um alarme do PromQL no Query Studio
<a name="promql-alarm-create-query-studio"></a>

Este exemplo mostra como criar um alarme do PromQL no Query Studio que alerta você quando a duração média da solicitação HTTP para um serviço excede 500 milissegundos.

Diferentemente dos alarmes padrão do CloudWatch, em que o limite é configurado como uma etapa separada, os alarmes do PromQL definem a condição do alarme (limite) como parte da própria consulta. Por exemplo, o operador de comparação (`>`) e o valor limite (`0.5`) são incorporados diretamente na expressão do PromQL.

**Para criar um alarme do PromQL no Query Studio**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação abaixo de **Métricas**, escolha **Query Studio (pré-visualização)**.

1. Selecione **PromQL** no menu suspenso da linguagem de consulta.

1. Criar a consulta usando um dos seguintes modos:
   + No modo **Builder**, selecione um nome de métrica no campo **Métrica** (por exemplo, `http.server.request.duration`). Adicione filtros de rótulos conforme necessário (por exemplo, `@resource.service.name` = `my-api`). Para definir o limite de alarme, selecione uma **Operação básica** (por exemplo, `>`) e insira um **Número** (por exemplo, `0.5`).
   + No modo **Código**, insira a expressão do PromQL diretamente, por exemplo:

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

1. Escolha **Executar** para executar a consulta e verificar se ela retorna os resultados esperados.

1. Escolha **Criar alarme** no menu de ações.

1. Você será redirecionado para a página de criação de alarmes do CloudWatch com sua consulta do PromQL pré-preenchida.

1. Em **Conditions (Condições)**, especifique o seguinte:
   + Em **Intervalo de avaliação**, escolha **1 minute** para definir com que frequência a consulta do PromQL é avaliada.
   + Em **Período pendente**, insira **60**, que é a duração em segundos que uma consulta deve estar em violação antes de entrar no estado de ALARME. Isso significa que a latência deve exceder o limite por pelo menos 60 segundos antes que o alarme seja acionado.
   + Em **Período de recuperação**, insira **120**, que é a duração em segundos que uma consulta deve estar em violação antes de entrar no estado de OK. Isso significa que a latência deve permanecer abaixo do limite por pelo menos 120 segundos antes que o alarme se recupere.

1. Configure notificações e ações conforme necessário.

1. Adicione um nome e uma descrição para o alarme.

1. Escolha **Próximo**.

1. Selecione **Criar alarme**.

**nota**  
A consulta do PromQL deve retornar uma única série temporal para criar um alarme. Se sua consulta retornar várias séries temporais, use funções de agregação como `sum`, `avg` ou `topk` para reduzir o resultado a uma única série antes de criar o alarme.