Exemples de règles au format JSON

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

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

Pour en savoir plus sur la configuration des champs d'une règle d'alerte, consultez les articles suivants:

Générer du code YAML pour les stratégies 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 répertorier 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 répertorier vos canaux et la commande gcloud alpha monitoring channels describe pour afficher 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 un fichier 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, effectuez l'une des opérations suivantes:

Exemples de règles

Comme indiqué dans l'exemple de sauvegarde/restauration, vous pouvez utiliser des 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 toutes les règles 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 Monitoring dans la console Google Cloud utilise (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 qui suivent, ces conditions correspondent à conditionThreshold et conditionAbsent. Pour en savoir plus, consultez la page de référence de Condition.

Vous pouvez créer un grand nombre de ces règles manuellement à l'aide de la console Google Cloud, mais certaines ne peuvent être créées qu'à l'aide de l'API Monitoring. Pour en savoir plus, consultez Créer une règle d'alerte (UI) 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 lorsqu'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 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 à des intervalles de 60 secondes, dépasse le seuil d'utilisation 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 pendant la durée spécifiée.

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. En d'autres termes, votre pipeline horaire ne s'exécute pas correctement. 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 toutes les prévisions effectuées pour une série temporelle dans une période de temps sont identiques et qu'elles prévoient que la série temporelle dépassera le seuil dans 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 le montre l'exemple suivant, ces conditions incluent un champ forecastOptions qui permet d'activer la prévision et de spécifier 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 changement 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 au cours des 10 dernières minutes, puis compare le résultat à la moyenne sur 10 minutes mesurée juste avant l'intervalle de temps. La période d'analyse de 10 minutes utilisée par une condition de taux de variation d'une métrique est une valeur fixe. Vous ne pouvez pas la modifier. Cependant, vous spécifiez l'intervalle de temps lorsque vous créez une condition.

Cette règle vous alerte lorsque le taux d'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 vous avertit lorsque 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é

L'état des tests de disponibilité apparaît sur la page Tests de disponibilité, mais vous pouvez configurer une règle d'alerte afin que Cloud Monitoring vous envoie une notification en cas d'échec du test.

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 5 minutes.

Le test de disponibilité a été créé avec 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 expire dans moins de 15 jours. Si l'une des 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 oblige Monitoring à envoyer une notification au canal de notification spécifié lorsqu'aucun processus correspondant à la chaîne nginx, exécuté en tant qu'utilisateur www, n'est disponible depuis plus de 5 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 soit compatible avec la construction de certains ratios basés sur des filtres, MQL offre une solution plus flexible et 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 simple, 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 deux filtres ne respecte pas une valeur de seuil pendant la durée spécifiée.

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 les données 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 si le ratio est supérieur à 0, 5) sur la période d'alignement de 5 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 durée autorisée pour la condition est de zéro seconde. Cette condition utilise un décompte trigger égal à un, ce qui correspond au nombre de séries temporelles devant violer la condition pour provoquer l'incident. Pour une application App Engine comportant un seul service, un nombre trigger de 1 suffit. Si vous disposez d'une application avec 20 services et que vous souhaitez provoquer un incident si trois services ou plus ne respectent pas la condition, utilisez un nombre de trigger égal à 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 selon des libellés de ressources spécifiés, ce qui la partitionne 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 ainsi deux séries temporelles, une pour le numérateur et une 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 cet intervalle 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 l'intervalle 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. Une fois le ratio disponible, cette règle est une règle de seuil de métrique simple.