Migrer les règles d'alerte et les récepteurs à partir de Prometheus

Cette page explique comment migrer des règles d'alerte Prometheus vers des règles d'alerte Cloud Monitoring avec une condition basée sur PromQL. Le processus de migration est utile si vous utilisez PromQL dans des environnements extérieurs à Google Cloud. En migrant vos règles d'alerte Prometheus vers Cloud Monitoring, vous pouvez gérer toutes vos règles d'alerte dans un seul environnement.

Pour obtenir des informations générales sur les règles d'alerte avec des conditions basées sur PromQL, consultez la section Règles d'alerte avec PromQL.

Vous pouvez également importer des tableaux de bord Grafana. Pour en savoir plus, consultez la page Importer des tableaux de bord Grafana dans Cloud Monitoring.

Fonctionnement de la migration

Dans la gcloud CLI, vous pouvez migrer vos règles d'alerte et vos destinataires existants pour créer des règles d'alerte et des canaux de notification Cloud Monitoring. La gcloud CLI peut effectuer les types de migration suivants:

  • Si vous fournissez un fichier de configuration Prometheus avec une règle d'alerte, la gcloud CLI crée une règle d'alerte avec une condition basée sur PromQL.

    Vous pouvez fournir plusieurs fichiers de configuration Prometheus en même temps pour créer plusieurs règles d'alerte avec une condition basée sur PromQL.

  • Si vous fournissez un fichier Alertmanager Prometheus avec au moins un récepteur, gcloud CLI convertit chaque destinataire vers un canal de notification équivalent dans Monitoring.

  • Si vous fournissez simultanément un fichier Prometheus Alertmanager et un fichier de configuration Prometheus, gcloud CLI crée la règle d'alerte et les canaux de notification, puis associe chaque nouveau canal de notification à la nouvelle règle d'alerte.

    Si vous fournissez plusieurs fichiers de configuration avec des règles d'alerte, la gcloud CLI attribue chaque canal de notification du fichier Alertmanager à chaque nouvelle règle d'alerte.

Si votre règle d'alerte Prometheus fait référence à une métrique personnalisée, gcloud CLI nécessite un descripteur de la métrique équivalent pour créer la règle d'alerte.

Les fichiers de configuration Prometheus et les fichiers Prometheus Alertmanager doivent être mis en forme en tant que fichiers de règles Prometheus valides, au format YAML ou JSON.

Mappage de champ

La gcloud CLI mappe les champs entre une règle d'alerte Prometheus et une règle d'alerte Cloud Monitoring comme suit:

Règle d'alerte Prometheus Règle d'alerte Cloud Monitoring
alert conditionPrometheusQueryLanguage.alertRule
expr conditionPrometheusQueryLanguage.query
for conditionPrometheusQueryLanguage.duration
labels conditionPrometheusQueryLanguage.labels
annotations: "summary" documentation.subject
annotations: "description" documentation.content

Variables de la documentation Google Cloud dans les règles d'alerte Prometheus migrées

Prometheus utilise des modèles de champ d'alerte pour configurer les variables dans les annotations et les étiquettes des règles d'alerte. Lorsque vous migrez des règles d'alerte Prometheus comportant des modèles de champ d'alerte, Cloud Monitoring convertit les modèles en variables de documentation Cloud Monitoring comme suit:

Modèle de champ d'alerte Prometheus Variable de documentation Cloud Monitoring
{{$value}}

${metric.label.value}

Cette variable est une implémentation de ${metric.label.KEY}, où value contient la valeur de la requête PromQL.

{{humanize $value}}

${metric.label.value}

Cette variable est une implémentation de ${metric.label.KEY}, où value contient la valeur de la requête PromQL.

{{$labels}} ${metric_or_resource.labels}
{{humanize $labels}} ${metric_or_resource.labels}
{{$labels.key}}

Apparaît sous la forme ${metric_or_resource.label.KEY} dans la configuration de la documentation de la règle d'alerte.

  • Si KEY est un libellé valide, cette variable s'affiche dans la notification en tant que valeur de ${metric.label.KEY}.
  • Si KEY est une ressource valide, cette variable s'affiche dans la notification en tant que valeur de ${resource.label.KEY}.
  • Si KEY n'est ni un libellé ni une ressource valides, cette variable s'affiche dans la notification sous la forme d'une chaîne vide.
{{humanize $labels.<key>}}

Apparaît sous la forme ${metric_or_resource.label.KEY} dans la configuration de la documentation de la règle d'alerte.

  • Si KEY est un libellé valide, cette variable s'affiche dans la notification en tant que valeur de ${metric.label.KEY}.
  • Si KEY est une ressource valide, cette variable s'affiche dans la notification en tant que valeur de ${resource.label.KEY}.
  • Si KEY n'est ni un libellé ni une ressource valides, cette variable s'affiche dans la notification sous la forme d'une chaîne vide.

Migrer les règles d'alerte et les récepteurs à partir de Prometheus

Pour migrer vos règles d'alerte Prometheus vers des règles d'alerte Cloud Monitoring avec des conditions basées sur PromQL, utilisez la commande gcloud alpha monitoring policies migrate. Cette commande vous permet également de migrer vos récepteurs Prometheus vers les canaux de notification Cloud Monitoring.

  • Pour migrer une règle d'alerte, vous devez disposer d'un fichier de règles Prometheus YAML ou JSON contenant la règle d'alerte.
  • Pour migrer un récepteur, vous devez disposer d'un fichier Alertmanager Prometheus YAML ou JSON contenant le récepteur.

Google Cloud n'est pas compatible avec la migration des règles d'enregistrement Prometheus. Pour utiliser des règles d'enregistrement, nous vous recommandons d'utiliser un évaluateur de règle autodéployé.

Créer une règle d'alerte à partir d'un fichier de configuration Prometheus

Pour créer une règle d'alerte à partir d'un fichier de configuration Prometheus, exécutez la commande suivante. Vous pouvez créer plusieurs règles d'alerte en fournissant plusieurs chemins d'accès aux fichiers:

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

Créer des canaux de notification à partir d'un fichier de configuration Prometheus Alertmanager

Pour créer des canaux de notification à partir d'un fichier de configuration Prometheus Alertmanager, exécutez la commande suivante:

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

Créer simultanément des règles d'alerte et des canaux de notification

Pour créer des règles d'alerte à partir de fichiers de configuration Prometheus et pour créer simultanément des canaux de notification à partir d'un fichier de configuration Prometheus Alertmanager, exécutez la commande suivante:

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

Exemple

Vous disposez d'un fichier de configuration Prometheus avec une règle d'alerte qui envoie une alerte lorsque l'utilisation du processeur reste supérieure à 75% pendant une minute. La règle d'alerte est configurée comme suit:

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%"

Vous disposez également d'un fichier Prometheus AlertManager contenant des e-mails, des PagerDuty et des récepteurs de webhooks.

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

Pour créer la règle d'alerte et le canal de notification, exécutez la commande suivante:

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

La gcloud CLI crée ensuite une règle d'alerte semblable à l'exemple suivant:

  {
  "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"
  ]
}

Migrer des règles d'alerte depuis Managed Service pour Prometheus

Google Cloud configure l'évaluation des règles gérées pour Managed Service pour Prometheus à l'aide des ressources personnalisées Rules, ClusterRules et GlobalRules.

Pour migrer ces ressources vers une règle d'alerte Google Cloud avec une condition basée sur PromQL, procédez comme suit:

  1. Copiez la section groups de la ressource personnalisée dans un nouveau fichier de règles Prometheus.

  2. Migrez le fichier de règles à l'aide de la gcloud CLI.

Par exemple, vous disposez de la ressource personnalisée "Rules" (Règles) suivante:

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

Le fichier de règles Prometheus créé en copiant groups à partir de la ressource personnalisée "Rules" (Règles) précédente ressemblerait à ceci:

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

Migrer plusieurs ressources personnalisées de règles

Si vous souhaitez migrer plusieurs règles, règles personnalisées ou règles globales, nous vous recommandons de créer et de migrer un fichier de règles distinct pour chaque ressource. Pour en savoir plus, consultez la documentation Prometheus.

Gérer les expressions de filtre et d'agrégation

Les règles et ClusterRules filtrent automatiquement leurs expressions d'alerte Prometheus en fonction de certaines étiquettes. Pour conserver ce comportement dans la requête d'une règle d'alerte migrée, vous devez explicitement inclure ces étiquettes dans un filtre ou une expression d'agrégation de votre fichier de règles Prometheus avant de migrer le fichier.

Par exemple, l'évaluateur de règles gérées pour Managed Service pour Prometheus exécute l'expression sum(up) < 10 comme suit:

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

Toutefois, si une règle d'alerte a la requête PromQL sum(up) < 10, Cloud Monitoring exécute la requête avec sum(up) < 10 uniquement. Cette requête est appliquée à chaque projet, cluster et espace de noms Google Cloud de votre champ d'application des métriques. Pour éviter ce comportement, nous vous recommandons d'effectuer une agrégation par libellé dans votre requête afin de vous assurer que Cloud Monitoring exécute votre requête comme prévu. Par exemple, lorsque vous créez un fichier de règles à partir de la ressource personnalisée "Rules" (Règles), vous pouvez remplacer sum(up) < 10 par l'expression suivante:

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

L'expression précédente génère une série temporelle distincte pour chaque projet, cluster et espace de noms Google Cloud, puis compare chaque série temporelle au seuil d'alerte de <10.

Le tableau suivant indique l'ordre d'évaluation des filtres d'expression d'alerte pour les règles et les règles de cluster:

Type de ressource de règle Filtrer les étiquettes
Règle
  1. project_id
  2. cluster
  3. namespace
ClusterRule
  1. project_id
  2. cluster

Pour en savoir plus sur le comportement du filtrage dans les expressions Prometheus, consultez la section Sélecteurs de vecteurs instantanés.