Criar políticas de alertas com uma condição baseada em PromQL (API)

Nesta página, descrevemos como criar uma política de alertas com uma condição baseada em PromQL usando a API Cloud Monitoring. É possível usar consultas PromQL nas políticas de alertas para criar condições complexas com recursos como proporções, limites dinâmicos e avaliação de métricas.

Para informações gerais, consulte Políticas de alertas com PromQL.

Se você trabalhar em um ambiente do Prometheus fora do Cloud Monitoring e tiver regras de alerta do Prometheus, poderá usar a Google Cloud CLI para migrá-las para as políticas de alertas do Monitoring com uma consulta PromQL. Para mais informações, consulte Migrar regras de alerta e receptores do Prometheus.

Criar políticas de alertas com consultas PromQL

Use o método alertPolicies.create para criar políticas de alerta programaticamente.

A única diferença entre a criação de políticas de alertas com condições baseadas em PromQL e outras políticas de alertas é que seu tipo Condition precisa ser PrometheusQueryLanguageCondition. Esse tipo de condição permite definir políticas de alertas com o PromQL.

Veja a seguir uma consulta do PromQL para uma condição de política de alertas que usa uma métrica do exportador kube-state para encontrar o número de vezes que um contêiner foi reiniciado nos últimos 30 minutos:

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

Como criar a política de alertas

Para criar uma política de alertas com uma condição baseada em PromQL, use o tipo de condição AlertPolicy PrometheusQueryLanguageCondition. O PrometheusQueryLanguageCondition tem a seguinte estrutura:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

Os campos PrometheusQueryLanguageCondition têm as seguintes definições:

  • query: a expressão PromQL a ser avaliada. Equivalente ao campo expr de uma regra de alertas padrão do Prometheus.
  • duration: especifica o período em que cada avaliação da consulta precisa gerar um valor true antes que a política de alertas seja acionada. O valor precisa ser um número de minutos, expresso em segundos. Por exemplo, 600s para uma duração de 10 minutos. Para mais informações, consulte Comportamento de políticas de alertas baseadas em métricas.

  • evaluationInterval: o intervalo de tempo, em segundos, entre as avaliações de PromQL da consulta. O valor padrão é de 30 segundos. Se o PrometheusQueryLanguageCondition tiver sido criado migrando uma regra de alerta do Prometheus, esse valor será proveniente do grupo de regras do Prometheus que continha a regra de alerta do Prometheus.

  • labels: uma maneira opcional de adicionar ou substituir rótulos no resultado da expressão PromQL.

  • ruleGroup: se a política de alertas tiver sido migrada de um arquivo de configuração do Prometheus, esse campo conterá o valor do campo name do grupo de regras no arquivo de configuração do Prometheus. Esse campo não é obrigatório quando você cria uma política de alertas do PromQL na API Cloud Monitoring.

  • alertRule: se a política de alertas tiver sido migrada de um arquivo de configuração do Prometheus, esse campo conterá o valor do campo alert da regra de alerta no arquivo de configuração do Prometheus. Esse campo não é obrigatório quando você cria uma política de alertas do PromQL na API Cloud Monitoring.

Por exemplo, a condição a seguir usa uma consulta PromQL para encontrar o número de vezes que um contêiner foi reiniciado nos últimos 30 minutos:

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

Use essa estrutura como o valor de um campo conditionPrometheusQueryLanguage em uma condição que, por sua vez, é incorporada em uma estrutura de política de alertas. Para mais informações sobre essas estruturas, consulte AlertPolicy.

Veja a seguir uma política completa com uma condição PrometheusQueryLanguageCondition em JSON:

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

Criar uma política de alertas

Para criar a política de alertas, coloque o JSON da política de alertas em um arquivo chamado POLICY_NAME.json e execute o seguinte comando:

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

Para mais informações sobre a API Monitoring para políticas de alertas, consulte Como gerenciar políticas de alertas por API.

Para ver mais informações sobre o uso de curl, consulte Como invocar curl.

Usando o Terraform

Para instruções sobre como configurar políticas de alertas baseadas em PromQL usando o Terraform, consulte a seção condition_prometheus_query_language do registro google_monitoring_alert_policy do Terraform (em inglês).

Para informações gerais sobre como usar o Google Cloud com o Terraform, consulte Terraform com o Google Cloud.

Como invocar o curl

Cada invocação curl inclui um conjunto de argumentos, seguido pelo URL de um recurso da API. Os argumentos comuns incluem um código de projeto do Google Cloud e um token de autenticação. Esses valores são representados aqui pelas variáveis de ambiente PROJECT_ID e TOKEN.

Talvez você também precise especificar outros argumentos para elementos diferentes, como o tipo da solicitação HTTP. Por exemplo, -X DELETE. Como a solicitação padrão é GET, os exemplos não fazem essa especificação.

Cada invocação do curl tem esta estrutura geral:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Para usar curl, especifique o código do projeto e um token de acesso. Para reduzir a digitação e os erros, é possível colocá-los em variáveis de ambiente e passá-los para curl dessa maneira.

Para definir essas variáveis, faça o seguinte:

  1. Crie uma variável de ambiente para manter o ID do projeto de escopo de um escopo de métricas. Estas etapas chamam a variável PROJECT_ID:

    PROJECT_ID=a-sample-project

  2. Faça a autenticação na Google Cloud CLI:

    gcloud auth login

  3. Opcional. Para não precisar especificar o ID do projeto em cada comando gcloud, defina o ID do projeto como padrão usando a CLI gcloud:

    gcloud config set project ${PROJECT_ID}

  4. Crie um token de autorização e colete-o em uma variável de ambiente. Estas etapas chamam a variável TOKEN:

    TOKEN=`gcloud auth print-access-token`

    É necessário atualizar o token de acesso periodicamente. Se algum comando parar de funcionar com um erro de falta de autenticação, será necessário emiti-lo novamente.

  5. Para verificar se você recebeu um token de acesso, faça o echo da variável TOKEN:

    echo ${TOKEN}
ya29.GluiBj8o....