Migre regras de alerta e recetores do Prometheus

Esta página descreve como migrar regras de alerta do Prometheus para políticas de alerta baseadas em PromQL no Cloud Monitoring. O processo de migração é útil se usar o PromQL em ambientes externos Google Cloud. Ao migrar as regras de alerta do Prometheus para o Cloud Monitoring, pode gerir todas as políticas de alerta num único ambiente.

Para informações gerais sobre políticas de alerta baseadas em PromQL, consulte a vista geral de alertas do PromQL.

Também pode importar painéis de controlo do Grafana. Para mais informações, consulte o artigo Importe painéis de controlo do Grafana para o Cloud Monitoring.

Como funciona a migração

Na CLI gcloud, pode migrar as regras de alerta e os destinatários existentes para criar políticas de alerta e canais de notificação do Cloud Monitoring. A CLI gcloud pode realizar os seguintes tipos de migração:

  • Se fornecer um ficheiro de configuração do Prometheus com uma regra de alerta, a CLI gcloud cria uma política de alerta baseada em PromQL.

    Pode fornecer vários ficheiros de configuração do Prometheus ao mesmo tempo para criar várias políticas de alerta baseadas em PromQL.

  • Se fornecer um ficheiro do Prometheus Alertmanager com, pelo menos, um destinatário, a CLI gcloud converte cada destinatário num canal de notificação equivalente no Monitoring.

  • Se fornecer um ficheiro do Prometheus Alertmanager e um ficheiro de configuração do Prometheus ao mesmo tempo, a CLI gcloud cria a política de alertas e os canais de notificação e, em seguida, associa cada novo canal de notificação à nova política de alertas.

    Se fornecer vários ficheiros de configuração com regras de alerta, a CLI gcloud atribui todos os canais de notificação do ficheiro do Alertmanager a cada nova política de alerta.

Se a sua regra de alerta do Prometheus fizer referência a uma métrica personalizada, a CLI gcloud requer um descritor de métrica equivalente para criar a política de alerta.

Os ficheiros de configuração do Prometheus e os ficheiros do Prometheus Alertmanager têm de estar formatados como ficheiros de regras válidos do Prometheus em YAML ou JSON.

Mapeamento de campos

A CLI gcloud mapeia os campos entre uma regra de alerta do Prometheus e uma política de alerta do Cloud Monitoring da seguinte forma:

Regra de alerta do Prometheus Política de alertas do Cloud Monitoring
alert conditionPrometheusQueryLanguage.alertRule
expr conditionPrometheusQueryLanguage.query
for conditionPrometheusQueryLanguage.duration
labels conditionPrometheusQueryLanguage.labels
annotations: "summary" documentation.subject
annotations: "description" documentation.content

Google Cloud variáveis de documentação em regras de alerta do Prometheus migradas

O Prometheus usa modelos de campos de alerta para configurar variáveis em anotações e etiquetas de regras de alerta. Quando migra regras de alerta do Prometheus que têm modelos de campos de alerta, o Cloud Monitoring converte os modelos em variáveis de documentação do Cloud Monitoring da seguinte forma:

Modelo de campo de alerta do Prometheus Variável de documentação do Cloud Monitoring
{{$value}}

${metric.label.value}

Esta variável é uma implementação de ${metric.label.KEY}, em que value contém o valor da consulta PromQL.
{{humanize $value}}

${metric.label.value}

Esta variável é uma implementação de ${metric.label.KEY}, em que value contém o valor da consulta PromQL.
{{$labels}} ${metric_or_resource.labels}
{{humanize $labels}} ${metric_or_resource.labels}
{{$labels.key}}

Aparece como ${metric_or_resource.label.KEY} na configuração da documentação da política de alertas.

  • Se KEY for uma etiqueta válida, esta variável é renderizada na notificação como o valor de ${metric.label.KEY}.
  • Se KEY for um recurso válido, esta variável é renderizada na notificação como o valor de ${resource.label.KEY}.
  • Se KEY não for uma etiqueta nem um recurso válido, esta variável é renderizada na notificação como uma string vazia.
{{humanize $labels.<key>}}

Aparece como ${metric_or_resource.label.KEY} na configuração da documentação da política de alertas.

  • Se KEY for uma etiqueta válida, esta variável é renderizada na notificação como o valor de ${metric.label.KEY}.
  • Se KEY for um recurso válido, esta variável é renderizada na notificação como o valor de ${resource.label.KEY}.
  • Se KEY não for uma etiqueta nem um recurso válido, esta variável é renderizada na notificação como uma string vazia.

Migre regras de alerta e recetores do Prometheus

Para migrar as suas regras de alerta do Prometheus para políticas de alerta baseadas em PromQL do Cloud Monitoring, use o comando gcloud alpha monitoring policies migrate. Este comando também lhe permite migrar os seus recetores do Prometheus para os canais de notificação do Cloud Monitoring.

  • Para migrar uma regra de alerta, tem de ter um ficheiro YAML ou JSON Prometheus rule file que contenha a regra de alerta.

  • Para migrar um destinatário, tem de ter um ficheiro YAML ou JSON do Prometheus Alertmanager que contenha o destinatário.

OGoogle Cloud não suporta a migração de regras de gravação do Prometheus. Para usar regras de gravação, recomendamos que use um avaliador de regras implementado automaticamente.

Crie uma política de alerta a partir de um ficheiro de configuração do Prometheus

Para criar uma política de alerta a partir de um ficheiro de configuração do Prometheus, execute o seguinte comando. Pode criar várias políticas de alerta indicando vários caminhos de ficheiros:

gcloud alpha monitoring policies migrate \
--policies-from-prometheus-alert-rules-yaml=PATH_TO_FILE_1,PATH_TO_FILE_2

Crie canais de notificação a partir de um ficheiro de configuração do Prometheus Alertmanager

Para criar canais de notificação a partir de um ficheiro de configuração do Prometheus Alertmanager, execute o seguinte comando:

gcloud alpha monitoring policies migrate \
--channels-from-prometheus-alertmanager-yaml=PATH_TO_FILE

Crie políticas de alerta e canais de notificação em simultâneo

Para criar políticas de alerta a partir de ficheiros de configuração do Prometheus e criar canais de notificação a partir de um ficheiro de configuração do Prometheus Alertmanager ao mesmo tempo, execute o seguinte comando:

gcloud alpha monitoring policies migrate \
--policies-from-prometheus-alert-rules-yaml=PATH_TO_FILE_1,PATH_TO_FILE_2 \
--channels-from-prometheus-alertmanager-yaml=PATH_TO_FILE

Exemplo

Tem um ficheiro de configuração do Prometheus com uma regra de alerta que envia um alerta quando a utilização da CPU permanece superior a 75% durante um minuto. A regra de alerta está configurada da seguinte forma:

groups:
- name: Utilization_Alerts
  interval: 30s
  rules:
  - alert: CPU_Utilization_Over_75
    expr: compute_googleapis_com:instance_cpu_utilization > 75
    for: 60s
    labels:
      severity: page
    annotations:
      subject: "Subject: ${metric.label.value}"
      description: "CPU utilization is over 75%"

Também tem um ficheiro do Prometheus AlertManager que contém destinatários de email, PagerDuty e webhook.

receivers:
- name: 'team-emails'
  email_configs:
  - to: EMAIL_ADDRESS
- name: 'team-pager'
  pagerduty_configs:
  - service_key: SERVICE_KEY
- name: 'team-webhook'
  webhook_configs:
  - url: WEBHOOK_ADDRESS

Para criar a política de alertas e o canal de notificação, execute o seguinte comando:

gcloud alpha monitoring policies migrate \
--policies-from-prometheus-alert-rules-yaml=PATH_TO_CONFIG_FILE \
--channels-from-prometheus-alertmanager-yaml=PATH_TO_ALERTMANAGER_FILE

Em seguida, a CLI gcloud cria uma política de alerta semelhante ao exemplo seguinte:

  {
  "name": "projects/PROJECT_ID/alertPolicies/POLICY_ID",
  "displayName": "Utilization_Alerts/CPU_Utilization_Over_75",
  "documentation": {
    "content": "CPU utilization is over 75%",
    "mimeType": "text/markdown",
    "subject": "Subject: ${metric.label.value}"
  },
  "userLabels": {},
  "conditions": [
    {
      "name": "projects/PROJECT_ID/alertPolicies/POLICY_ID/conditions/CONDITION_ID",
      "displayName": "CPU_Utilization_Over_75"
      "conditionPrometheusQueryLanguage": {
        "alertRule": "CPU_Utilization_Over_75",
        "duration": "60s",
        "evaluationInterval": "30s",
        "labels": {
          "severity": "page"
        },
        "query": "compute_googleapis_com:instance_cpu_utilization > 75",
        "ruleGroup": "Utilization_Alerts"
      }
    }
  ],
  "alertStrategy": {},
  "combiner": "OR",
  "enabled": true,
  "notificationChannels": [
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_1",
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_2",
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_3"
  ]
}

Migre regras de alerta do Managed Service for Prometheus

Google Cloud configura a avaliação de regras geridas para o Managed Service for Prometheus através dos recursos personalizados Rules, ClusterRules e GlobalRules.

Para migrar estes recursos para uma Google Cloud política de alertas baseada em PromQL, faça o seguinte:

  1. Copie a secção groups do recurso personalizado para um novo ficheiro de regras do Prometheus.

  2. Migre o ficheiro de regras através da CLI gcloud.

Por exemplo, tem o seguinte recurso personalizado de regras:

apiVersion: monitoring.googleapis.com/v1
kind: Rules
metadata:
  namespace: NAMESPACE_NAME
  name: example-rules
spec:
  groups:
  - name: example
    interval: 30s
    rules:
    - alert: FewerThanTenInstancesUp
      expr: sum(up) < 10

O ficheiro de regras do Prometheus criado copiando groups do recurso personalizado Rules anterior teria o seguinte aspeto:

  groups:
  - name: example
    interval: 30s
    rules:
    - alert: FewerThanTenInstancesUp
      expr: sum(up) < 10

Migre vários recursos personalizados de regras

Se quiser migrar várias regras, regras personalizadas ou regras globais, recomendamos que crie e migre um ficheiro de regras separado para cada recurso. Para mais informações, consulte a documentação do Prometheus.

Faça a gestão das expressões de filtro e agregação

As regras e as ClusterRules filtram automaticamente as respetivas expressões de alerta do Prometheus com base em determinadas etiquetas. Para preservar este comportamento na consulta de uma política de alertas migrada, tem de incluir explicitamente estas etiquetas numa expressão de filtro ou agregação no ficheiro de regras do Prometheus antes de migrar o ficheiro.

Por exemplo, o avaliador de regras gerido para o Managed Service for Prometheus executa a expressão sum(up) < 10 da seguinte forma:

sum(up{project_id="test-project", cluster="test-cluster", namespace="NAMESPACE_NAME"}) < 10

No entanto, se uma política de alerta tiver a consulta PromQL sum(up) < 10, o Cloud Monitoring executa a consulta como apenas sum(up) < 10. Esta consulta é aplicada a todos os Google Cloud projetos, clusters e namespaces no seu âmbito de métricas. Para evitar este comportamento, recomendamos que agregue por etiquetas na sua consulta para garantir que o Cloud Monitoring executa a consulta conforme previsto. Por exemplo, quando cria o ficheiro de regras a partir do recurso personalizado de regras, pode alterar sum(up) < 10 para a seguinte expressão:

sum (up) by (project_id, cluster, namespace) < 10

A expressão anterior gera uma série cronológica separada para cada Google Cloud projeto, cluster e espaço de nomes e, em seguida, compara cada série cronológica com o limite de alerta de <10.

A tabela seguinte mostra a ordem de avaliação dos filtros de expressão de alerta para regras e regras de agrupamento:

Tipo de recurso da regra Etiquetas de filtro
Regra
  1. project_id
  2. cluster
  3. namespace
ClusterRule
  1. project_id
  2. cluster

Para mais informações sobre o comportamento de filtragem em expressões do Prometheus, consulte Seletores de vetores instantâneos.