Exemples de règles au format JSON

Ce document fournit des exemples de règles d'alerte. Les exemples sont écrits en JSON et utilisent des filtres de surveillance. Vous pouvez créer des règles au format JSON ou YAML, que vous définissiez la règle à l'aide de filtres Monitoring ou du langage MQL (Monitoring Query Language). La Google Cloud CLI peut lire et écrire à la fois JSON et YAML, tandis que l'API REST peut lire JSON.

Pour obtenir des exemples de règles d'alerte qui utilisent MQL, consultez les documents suivants:

Pour savoir comment configurer les champs des règles d'alerte, consultez les ressources suivantes:

Générer du code YAML pour les règles existantes

Pour générer des représentations YAML de vos règles d'alerte existantes, utilisez la commande gcloud alpha monitoring policies list pour lister vos règles et la commande gcloud alpha monitoring policies describe pour les imprimer.

Pour générer des représentations YAML de vos canaux de notification existants, utilisez la commande gcloud alpha monitoring channels list pour lister vos canaux et la commande gcloud alpha monitoring channels describe pour imprimer la configuration des canaux.

Si vous n'incluez pas l'option --format dans les commandes Google Cloud CLI, le format par défaut est YAML pour les deux commandes gcloud ... describe.

Par exemple, la commande gcloud alpha monitoring policies describe suivante récupère une seule stratégie nommée projects/a-gcp-project/alertPolicies/12669073143329903307, et la redirection (>) copie la sortie dans le fichier test-policy.yaml:

gcloud alpha monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307 > test-policy.yaml

Générer du code JSON pour les règles existantes

Pour générer des représentations JSON de vos règles d'alerte et de vos canaux de notification existants, procédez comme suit:

Exemples de règles

Comme le montre l'exemple de sauvegarde/restauration, vous pouvez vous servir de règles enregistrées pour créer des copies de ces règles.

Vous pouvez utiliser une règle enregistrée dans un projet pour créer une autre règle dans ce même projet, ou une règle similaire dans un autre projet. Toutefois, vous devez d'abord apporter les modifications suivantes à la copie de la règle enregistrée :

  • Supprimez les champs suivants des canaux de notification :
    • name
    • verificationStatus
  • Créez les canaux de notification avant d'y faire référence dans les règles d'alerte (les nouveaux identifiants des canaux sont nécessaires).
  • Supprimez les champs suivants de toute règle d'alerte que vous recréez :
    • name
    • condition.name
    • creationRecord
    • mutationRecord

Les règles de ce document sont organisées selon la même terminologie que sur Monitoring dans la console Google Cloud, par exemple "règle de taux d'évolution". Il existe deux types de conditions:

  • Une condition de seuil (presque tous les types de règles mentionnés dans l'interface utilisateur sont des variantes d'une condition de seuil)
  • Une condition d'absence

Dans les exemples suivants, ces conditions correspondent à conditionThreshold et conditionAbsent. Pour en savoir plus, consultez la page de référence sur Condition.

Vous pouvez créer un grand nombre de ces règles manuellement à l'aide de Google Cloud Console, mais certaines ne peuvent être créées qu'à l'aide de l'API Monitoring. Pour en savoir plus, consultez les sections Créer une règle d'alerte ou Créer des règles d'alerte à l'aide de l'API.

Règle de seuil de métrique

Une règle de seuil de métrique détecte le moment où une valeur dépasse une limite prédéterminée. Les règles de seuil vous informent qu'un élément s'approche d'un point important afin que vous puissiez prendre les mesures requises. Par exemple, la condition d'une règle de seuil de métrique est remplie lorsque l'espace disque disponible est inférieur à 10 % de l'espace disque total.

La règle d'alerte suivante utilise l'utilisation moyenne du processeur comme indicateur de l'état de santé d'un groupe de VM. La condition de la règle est remplie lorsque l'utilisation moyenne du processeur des VM d'un projet, mesurée sur des intervalles de 60 secondes, dépasse le seuil de 90 % pendant 15 minutes (900 secondes):

{
    "displayName": "Very high CPU usage",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "CPU usage is extremely high",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                            "project"
                        ],
                        "perSeriesAligner": "ALIGN_MAX"
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "900s",
                "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
                          AND resource.type=\"gce_instance\"",
                "thresholdValue": 0.9,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

Règle d'absence de métrique

Une condition d'absence de métrique est remplie lorsqu'aucune donnée n'est écrite dans une métrique au cours de la période définie par le champ duration.

Une façon d'illustrer une telle règle consiste à créer une métrique personnalisée.

Voici un exemple de descripteur pour une métrique personnalisée. Vous pouvez la créer à l'aide de l'explorateur d'API.

{
  "description": "Number of times the pipeline has run",
  "displayName": "Pipeline runs",
  "metricKind": "GAUGE",
  "type": "custom.googleapis.com/pipeline_runs",
  "labels": [
    {
      "description": "The name of the pipeline",
      "key": "pipeline_name",
      "valueType": "STRING"
    },
  ],
  "unit": "1",
  "valueType": "INT64"
}

Pour en savoir plus, consultez la section Présentation des métriques définies par l'utilisateur.

La condition de la règle d'alerte suivante est remplie lorsque les données cessent d'être écrites dans la métrique pendant une période d'environ une heure. Cela signifie que l'exécution de votre pipeline horaire n'a pas abouti. Notez que la condition utilisée ici est conditionAbsent.

{
    "displayName": "Data ingestion functioning",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Hourly pipeline is up",
            "conditionAbsent": {
                "duration": "3900s",
                "filter": "resource.type=\"global\"
                          AND metric.type=\"custom.googleapis.com/pipeline_runs\"
                          AND metric.label.pipeline_name=\"hourly\"",
            }
        }
    ],
}

Règle de prévision

Une condition de prévision est remplie lorsque les conditions suivantes sont remplies:

  • Toutes les prévisions d'une série temporelle sont identiques dans la période définie par le champ duration.
  • Cloud Monitoring prévoit que la série temporelle dépassera le seuil au cours de l'horizon de prévision.

Une condition de prévision est une condition de seuil de métrique configurée pour utiliser la prévision. Comme illustré dans l'exemple suivant, ces conditions incluent un champ forecastOptions qui permet les prévisions et spécifie l'horizon de prévision. Dans l'exemple suivant, l'horizon de prévision est défini sur une heure, ce qui correspond à la valeur minimale:

{
    "displayName": "NFS free bytes alert",
    "combiner": "OR",
    "conditions": [
      {
        "displayName": "Filestore Instance - Free disk space percent",
        "conditionThreshold": {
          "aggregations": [
            {
              "alignmentPeriod": "300s",
              "perSeriesAligner": "ALIGN_MEAN"
            }
          ],
          "comparison": "COMPARISON_LT",
          "duration": "900s",
          "filter": "resource.type = \"filestore_instance\" AND metric.type = \"file.googleapis.com/nfs/server/free_bytes_percent\"",
          "forecastOptions": {
            "forecastHorizon": "3600s"
          },
          "thresholdValue": 20,
          "trigger": {
            "count": 1
          }
        }
      }
    ],
}

Règle de taux d'évolution

Les conditions de taux de variation sont remplies lorsque les valeurs d'une série temporelle augmentent ou diminuent d'au moins le pourcentage spécifié par le seuil. Lorsque vous créez ce type de condition, un calcul de pourcentage de changement est appliqué à la série temporelle avant la comparaison avec le seuil.

La condition calcule la moyenne des valeurs de la métrique lors des 10 dernières minutes, puis compare ce résultat à la moyenne sur 10 minutes mesurée juste avant le début de la période d'alignement. Vous ne pouvez pas modifier la période de 10 minutes utilisée pour les comparaisons dans une règle d'alerte de taux de changement. Cependant, c'est vous qui spécifiez la période d'alignement lorsque vous créez la condition.

Cette règle d'alerte surveille si l'utilisation du processeur augmente rapidement:

{
  "displayName": "High CPU rate of change",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "CPU usage is increasing at a high rate",
      "conditionThreshold": {
         "aggregations": [
           {
             "alignmentPeriod": "900s",
             "perSeriesAligner": "ALIGN_PERCENT_CHANGE",
           }],
        "comparison": "COMPARISON_GT",
        "duration": "180s",
        "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.type=\"gce_instance\"",
        "thresholdValue": 0.5,
        "trigger": {
          "count": 1
         }
      }
    }
  ],
}

Règle d'agrégat de groupe

Cette règle d'alerte vérifie si l'utilisation moyenne du processeur sur un cluster Google Kubernetes Engine dépasse un certain seuil:

{
    "displayName": "CPU utilization across GKE cluster exceeds 10 percent",
    "combiner": "OR",
    "conditions": [
         {
            "displayName": "Group Aggregate Threshold across All Instances in Group GKE cluster",
            "conditionThreshold": {
                "filter": "group.id=\"3691870619975147604\" AND metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.1,
                "duration": "300s",
                "trigger": {
                    "count": 1
                },
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_MEAN",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                              "project"
                        ]
                    },
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_SUM",
                        "crossSeriesReducer": "REDUCE_MEAN"
                    }
                ]
            },
        }
    ],
}

Cette règle suppose l'existence du groupe suivant :

    {
        "name": "projects/a-gcp-project/groups/3691870619975147604",
        "displayName": "GKE cluster",
        "filter": "resource.metadata.name=starts_with(\"gke-kuber-cluster-default-pool-6fe301a0-\")"
    }

Pour identifier les champs équivalents pour vos groupes, répertoriez les détails de votre groupe en utilisant APIs Explorer sur la page de référence concernant la méthode project.groups.list.

Règle de test de disponibilité

Bien que l'état des tests de disponibilité soit affiché sur la page Tests de disponibilité, vous pouvez configurer une règle d'alerte afin que Cloud Monitoring vous envoie une notification en cas d'échec d'un tel test.

Par exemple, l'exemple JSON suivant décrit un test de disponibilité HTTPS sur le site Google Cloud. La règle d'alerte vérifie la disponibilité toutes les cinq minutes.

Le test de disponibilité a été créé via la console Google Cloud. La représentation JSON ci-dessous a été créée en répertoriant les tests de disponibilité du projet à l'aide de l'API Monitoring (voir la page uptimeCheckConfigs.list). Vous pouvez également créer des tests de disponibilité à l'aide de l'API Monitoring.

{
    "name": "projects/a-gcp-project/uptimeCheckConfigs/uptime-check-for-google-cloud-site",
    "displayName": "Uptime check for Google Cloud site",
    "monitoredResource": {
        "type": "uptime_url",
        "labels": {
            "host": "cloud.google.com"
      }
    },
    "httpCheck": {
        "path": "/index.html",
        "useSsl": true,
        "port": 443,
        "authInfo": {}
    },
    "period": "300s",
    "timeout": "10s",
    "contentMatchers": [
        {}
    ]
}

Pour créer une règle d'alerte portant sur un test de disponibilité, désignez ce test via son ID UPTIME_CHECK_ID. Cet ID est défini lors de la création du test. Il correspond au dernier composant du champ name et est visible dans l'interface utilisateur en tant que Check ID dans le résumé de la configuration. Si vous utilisez l'API Monitoring, la méthode uptimeCheckConfigs.create affiche l'ID.

L'ID est dérivé de la variable displayName, définie dans le cas présent via l'interface utilisateur. Il est possible de le valider en répertoriant les tests de disponibilité et en examinant la valeur name.

L'ID du test de disponibilité mentionné précédemment est uptime-check-for-google-cloud-site.

La condition de la règle d'alerte suivante est remplie si le test de disponibilité échoue ou si le certificat SSL sur le site Google Cloud arrive à expiration dans moins de 15 jours. Si l'une de ces conditions est remplie, Monitoring envoie une notification au canal de notification spécifié:

{
    "displayName": "Google Cloud site uptime failure",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Failure of uptime check_id uptime-check-for-google-cloud-site",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_COUNT_FALSE",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/check_passed\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 1,
                "trigger": {
                    "count": 1
                }
            }
        },
        {
            "displayName": "SSL Certificate for google-cloud-site expiring soon",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_LT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 15,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

Le filtre de la condition spécifie la métrique surveillée par son type et son libellé. Les types de métriques sont les suivants : monitoring.googleapis.com/uptime_check/check_passed et monitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires. Le libellé de métrique identifie le test de disponibilité spécifiquement surveillé. Dans cet exemple, le champ de libellé check_id contient l'ID du test de disponibilité.

AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"

Pour en savoir plus, consultez la page Filtres de surveillance.

Règle d'état de processus

Une règle d'état de processus peut vous signaler que le nombre de processus correspondant à un modèle déterminé franchit un certain seuil. Une telle règle vous permet par exemple d'être informé qu'un processus a cessé de s'exécuter.

Cette règle d'alerte permet à Monitoring d'envoyer une notification sur le canal de notification spécifié lorsqu'aucun processus correspondant à la chaîne nginx, s'exécutant en tant qu'utilisateur www, n'est disponible depuis plus de cinq minutes:

{
    "displayName": "Server health",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Process 'nginx' is not running",
            "conditionThreshold": {
                "filter": "select_process_count(\"has_substring(\\\"nginx\\\")\", \"www\") AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_LT",
                "thresholdValue": 1,
                "duration": "300s"
            }
        }
    ],
}

Pour en savoir plus, consultez la section État de processus.

Ratio de métriques

Nous vous recommandons d'utiliser le langage MQL (Monitoring Query Language) pour créer des règles d'alerte basées sur un ratio. Bien que l'API Cloud Monitoring accepte la construction de certains ratios basés sur des filtres, MQL fournit une solution plus flexible et plus robuste:

Cette section décrit un ratio basé sur des filtres. Avec l'API, vous pouvez créer et afficher une règle qui calcule le ratio de deux métriques associées et se déclenche lorsque ce ratio dépasse un certain seuil. Les métriques associées doivent avoir le même MetricKind. Par exemple, vous pouvez créer une règle d'alerte basée sur un ratio si les deux métriques sont des métriques de jauge. Pour déterminer le MetricKind d'un type de métrique, consultez la liste des métriques.

Une condition de ratio est une variante d'une condition de seuil de métrique, où la condition d'une règle de ratio utilise deux filtres: filter et denominatorFilter, qui servent respectivement de numérateur et de dénominateur du ratio.

Les séries temporelles des deux filtres doivent être agrégées de la même façon, pour que le calcul du ratio des valeurs soit pertinent. La condition de la règle d'alerte est remplie lorsque le ratio des filtres ne respecte pas une valeur de seuil pour la période définie par le champ duration.

La section suivante décrit comment configurer une règle d'alerte permettant de surveiller le ratio entre les réponses d'erreur HTTP et toutes les réponses HTTP.

Ratio des erreurs HTTP

La règle d'alerte suivante comporte une condition de seuil basée sur le ratio entre le nombre de réponses d'erreur HTTP et le nombre total de réponses HTTP.

{
    "displayName": "HTTP error count exceeds 50 percent for App Engine apps",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Ratio: HTTP 500s error-response counts / All HTTP response counts",
            "conditionThreshold": {
                 "filter": "metric.label.response_code>=\"500\" AND
                            metric.label.response_code<\"600\" AND
                            metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                            project=\"a-gcp-project\" AND
                            resource.type=\"gae_app\"",
                 "aggregations": [
                    {
                        "alignmentPeriod": "300s",
                        "crossSeriesReducer": "REDUCE_SUM",
                        "groupByFields": [
                          "project",
                          "resource.label.module_id",
                          "resource.label.version_id"
                        ],
                        "perSeriesAligner": "ALIGN_DELTA"
                    }
                ],
                "denominatorFilter": "metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                                      project=\"a-gcp-project\" AND
                                      resource.type=\"gae_app\"",
                "denominatorAggregations": [
                   {
                      "alignmentPeriod": "300s",
                      "crossSeriesReducer": "REDUCE_SUM",
                      "groupByFields": [
                        "project",
                        "resource.label.module_id",
                        "resource.label.version_id"
                       ],
                      "perSeriesAligner": "ALIGN_DELTA",
                    }
                ],
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.5,
                "duration": "0s",
                "trigger": {
                    "count": 1
                }
            }
        }
    ]
}

Types de métriques et de ressources

Le type de métrique pour cette règle est appengine.googleapis.com/http/server/response_count, qui possède deux libellés :

  • response_code, un entier de 64 bits représentant le code d'état HTTP de la requête. Comme cette règle permet de filtrer les données de séries temporelles sur ce libellé, elle permet de déterminer les valeurs suivantes :
    • Le nombre de réponses reçues
    • Le nombre de réponses d'erreur reçues
    • Le ratio entre les réponses d'erreur et toutes les réponses
  • loading, une valeur booléenne qui indique si la requête était en cours de chargement. Le libellé loading n'est pas pertinent dans cette règle d'alerte.

La règle d'alerte évalue les données de réponse des applications App Engine, c'est-à-dire celles provenant du type de ressource surveillée gae_app. Cette ressource surveillée possède trois libellés :

  • project_id, l'ID du projet Google Cloud
  • module_id, le nom du service ou du module dans l'application
  • version_id, la version de l'application

Pour plus d'informations sur ces types de métriques et de ressources surveillées, consultez les métriques App Engine dans la liste des métriques et l'entrée gae_app dans la liste des ressources surveillées.

En quoi consiste cette règle ?

Cette condition calcule le ratio entre les réponses d'erreur et le nombre total de réponses. La condition est remplie si le ratio est supérieur à 50 % (c'est-à-dire, s'il est supérieur à 0,5) pendant la période d'alignement de cinq minutes.

Elle détermine le module et la version de l'application qui ne respectent pas la condition en regroupant les séries temporelles de chaque filtre en fonction des valeurs de ces libellés.

  • Le filtre de la condition examine les réponses HTTP d'une application App Engine et sélectionne celles comprises dans la plage d'erreurs 5xx. Il s'agit du numérateur du ratio.
  • Le filtre de dénominateur de la condition examine toutes les réponses HTTP d'une application App Engine.

La condition est remplie et Monitoring envoie immédiatement une notification pour le nouvel incident. La plage temporelle autorisée du champ duration dans la condition est de zéro seconde. Cette condition utilise un nombre trigger de un, ce qui correspond au nombre de séries temporelles qui doivent enfreindre la condition pour que l'incident se produise. Pour une application App Engine avec un seul service, un nombre de trigger de 1 est suffisant. Si vous disposez d'une application avec 20 services et que vous souhaitez déclencher un incident si au moins trois d'entre eux ne respectent pas la condition, utilisez un nombre de trigger défini sur 3.

Configurer un ratio

Les filtres de numérateur et de dénominateur sont exactement les mêmes, à la différence près que le filtre de condition du numérateur correspond aux codes de réponse dans la plage d'erreurs et que le filtre de condition du dénominateur correspond à tous les codes de réponse. Les clauses suivantes n'apparaissent que dans la condition du numérateur :

      metric.label.response_code>=\"500\" AND
      metric.label.response_code<\"600\"

Sinon, les filtres de numérateur et de dénominateur sont identiques.

Les séries temporelles sélectionnées par chaque filtre doivent être agrégées de la même manière pour que le calcul du ratio soit valide. Chaque filtre peut collecter plusieurs séries temporelles, car il existe une série temporelle différente pour chaque combinaison de valeurs des libellés. Cette règle regroupe l'ensemble de séries temporelles en fonction des libellés de ressources spécifiés, ce qui partitionne cet ensemble de séries temporelles en un ensemble de groupes. Certaines séries temporelles dans chaque groupe correspondent au filtre de numérateur. Le reste correspond au filtre de dénominateur.

Pour calculer un ratio, l'ensemble de séries temporelles correspondant à chaque filtre doit être agrégé en une seule série temporelle. Chaque groupe comporte alors deux séries temporelles, une pour le numérateur et l'autre pour le dénominateur. Ensuite, il est possible de calculer le ratio entre les points des séries temporelles du numérateur et du dénominateur dans chaque groupe.

Dans cette règle, les séries temporelles des deux filtres sont agrégées comme suit :

  • Chaque filtre crée un certain nombre de séries temporelles alignées toutes les cinq minutes, les valeurs représentées calculant ALIGN_DELTA sur les valeurs dans cet intervalle d'alignement de cinq minutes. Cet aligneur affiche le nombre de réponses correspondantes dans cette période d'alignement sous la forme d'un entier de 64 bits.

  • Les séries temporelles de chaque filtre sont également regroupées en fonction des valeurs de libellés de ressources pour le module et la version. Chaque groupe contient donc deux ensembles de séries temporelles alignées, l'un correspondant au filtre de numérateur et l'autre correspondant au filtre de dénominateur.

  • Les séries temporelles de chaque groupe correspondant au filtre de numérateur ou de dénominateur sont agrégées en une seule fois, en additionnant les valeurs de chaque série temporelle à l'aide du réducteur interséries REDUCER_SUM. Cela génère une série temporelle pour le numérateur et une pour le dénominateur, chacune indiquant le nombre de réponses pour toutes les séries temporelles correspondantes dans la période d'alignement.

La règle calcule ensuite, pour les séries temporelles du numérateur et du dénominateur représentant chaque groupe, le ratio des valeurs. La condition de la règle d'alerte est remplie lorsque le ratio est supérieur à 50 %.