Criar políticas de alertas baseadas em PromQL (API)

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

Para informações gerais, consulte Visão geral dos alertas com base em PromQL.

Se você trabalha em um ambiente do Prometheus fora do Cloud Monitoring e tem regras de alerta do Prometheus, use a Google Cloud CLI para migrá-las para políticas de alertas baseadas em PromQL no Monitoring. 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 baseadas em PromQL e outras políticas de alerta é que o tipo Condition precisa ser PrometheusQueryLanguageCondition. Esse tipo de condição permite que as políticas de alerta sejam definidas com o PromQL.

O exemplo a seguir mostra uma consulta PromQL para uma condição 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 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 alerta padrão do Prometheus.
  • duration: especifica o período em que cada avaliação da consulta precisa gerar um valor true antes que a condição da política de alertas seja atendida. 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 das políticas de alertas com base em métricas.

  • evaluationInterval: o intervalo de tempo, em segundos, entre as avaliações do PromQL da consulta. O valor padrão é de 30 segundos. Se o PrometheusQueryLanguageCondition foi criado migrando uma regra de alerta do Prometheus, esse valor vem 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 do PromQL.

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

  • alertRule: se a política de alertas foi migrada de um arquivo de configuração do Prometheus, esse campo contém o valor do campo alert da regra de alerta no arquivo de configuração do Prometheus. Esse campo não é necessá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.

Confira 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
}

Crie 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.

Desativar a verificação de existência de métricas

Quando você cria uma política de alertas baseada em PromQL,o Google Cloud executa uma validação para garantir que as métricas referenciadas na condição já existam no Monitoring. No entanto, é possível substituir essa validação se você precisar criar uma política de alertas antes que as métricas existam. Por exemplo, você pode fazer isso ao usar a automação para criar novos projetos com um conjunto padrão de políticas de alerta predefinidas. Se você não desativar a validação, a criação da política de alertas vai falhar até que as métricas subjacentes sejam criadas.

Para desativar a verificação de existência de métricas, adicione o campo "disableMetricValidation": true ao PrometheusQueryLanguageCondition:

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

Se a condição de uma política de alertas referenciar uma métrica que não existe, ela ainda será executada de acordo com o intervalo de avaliação. No entanto, o resultado da consulta está sempre vazio. Depois que a métrica subjacente existe, a consulta retorna dados.

Usar o Terraform

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

Para informações gerais sobre como usar o Google Cloud com o Terraform, consulte Terraform com 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 ID 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 evitar a necessidade de especificar o ID do projeto com 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....