Exemples de règles

Vous trouverez sur cette page un ensemble de règles d'alerte qui peut être utilisé comme source d'inspiration et comme point de départ pour la création de vos propres règles.

Représenter des règles au format JSON ou YAML

Vous pouvez représenter des règles d'alerte dans deux formats de données : JSON et YAML. Le SDK Cloud est capable de lire et d'écrire dans ces deux formats. L'API REST peut lire le format JSON.

Pour générer des représentations YAML (format par défaut) de vos règles d'alerte et de vos canaux de notification existants, utilisez respectivement les commandes gcloud alpha monitoring policies list et describe ou les commandes gcloud alpha monitoring channels list et describe.

Par exemple, cette commande récupère une seule règle et en enregistre le résultat dans le fichier test-policy.yaml :

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

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

Copier des 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 avez également la possibilité de les utiliser comme point de départ pour créer des règles similaires.

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

Exemples de règles

Les règles décrites ici sont organisées selon la même terminologie que sur Monitoring dans Google Cloud Console, par exemple "règle de taux d'évolution", mais il n'existe en réalité que deux types de conditions sous-jacentes à toutes ces classifications :

  • 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 de cette page, ces conditions sont désignées par 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 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 (API).

Règle de seuil de métrique

Une règle de seuil de métrique est une règle conçue pour détecter 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, une telle règle peut vous signaler que l'espace disque disponible est passé en dessous de 10 % de la capacité totale, et que votre système risque donc de se trouver bientôt à court d'espace disque.

La règle suivante traite l'utilisation moyenne du processeur comme un indicateur de l'état de santé d'un groupe de VM. Elle déclenche une alerte lorsque l'utilisation moyenne du processeur par un groupe de VM dans une instance et une zone déterminées, 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",
                            "resource.label.instance_id",
                            "resource.label.zone"
                        ],
                        "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 règle d'absence de métrique se déclenche lorsqu'aucune donnée n'est écrite dans une certaine métrique pendant une durée spécifiée.

Une façon d'illustrer une telle règle consiste à créer une métrique personnalisée qui ne fera jamais l'objet d'aucune écriture. Une métrique personnalisée pour ce genre de règle ne présente aucune utilité pratique. Cependant, à des fins de démonstration, il est aisé de faire en sorte que cette métrique ne soit jamais utilisée.

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

{
  "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 page Utiliser des métriques personnalisées.

La règle d'alerte suivante se déclenche si aucune donnée n'est écrite dans cette métrique pendant une période d'environ une heure, ce qui 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 taux d'évolution

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",
                              "resource.label.instance_id",
                              "resource.label.zone"
                        ]
                    },
                    {
                        "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 à l'aide de l'API Explorer de la page de référence sur 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 Présentation de la surveillance, vous pouvez utiliser une règle d'alerte pour être informé directement en cas d'échec d'un tel test.

L'exemple JSON suivant décrit un test de disponibilité HTTPS sur le site Google Cloud. La disponibilité est testée toutes les 5 minutes.

Le test de disponibilité a été créé via Google Cloud Console. 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 règle d'alerte ci-dessous se déclenche en cas d'échec du test de disponibilité 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, la règle d'alerte envoie une notification au canal de notification indiqué :

{
    "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 règle d'alerte 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.

La règle suivante envoie une notification au 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 un autre exemple, reportez-vous à la section État de processus.

Ratio de métriques

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 règle d'alerte est déclenchée si 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. Pour voir un autre exemple de règle d'alerte basée sur un ratio, consultez la section Alertes sur le ratio entre l'utilisation du quota et la limite de quota.

Ratio des erreurs HTTP

La règle suivante crée 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 concerne 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 règle calcule le ratio entre le nombre de réponses d'erreur et le nombre total de réponses. Elle déclenche une notification d'alerte si le ratio dépasse 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 règle déclenche immédiatement la notification d'alerte. La durée autorisée pour la condition est de zéro seconde. Cette règle utilise un déclencheur défini sur 1, ce qui correspond au nombre de séries temporelles qui doivent enfreindre la condition pour que la notification d'alerte soit déclenchée. Pour une application App Engine avec un seul service, un déclencheur de 1 est suffisant. Si vous disposez d'une application avec 20 services et que vous souhaitez déclencher une alerte si au moins trois d'entre eux ne respectent pas la condition, utilisez un déclencheur 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. La 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 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.