Cette page a été traduite par l'API Cloud Translation.

Annoter les alertes avec la documentation définie par l'utilisateur

Cette page explique comment configurer la documentation de votre règle d'alerte pour personnaliser le corps et l'objet de vos notifications. Les champs de documentation sont compatibles avec le texte brut, Markdown, les variables et les commandes spécifiques aux canaux.

Ajouter des informations à la notification

Vous pouvez fournir à vos équipes de réponse aux alertes des mesures correctives et des informations sur l'incident dans la notification, en spécifiant ce contenu lorsque vous créez la règle d'alerte. Par exemple, vous pouvez configurer la règle d'alerte pour inclure des liens vers un playbook interne dans toutes les notifications.

Pour obtenir un exemple d'implémentation, consultez la section Exemple de cette page.

Configurer l'objet des notifications

Vous pouvez gérer et trier vos notifications en indiquant leur objet. L'objet ne doit pas dépasser 255 caractères. Si vous ne définissez pas d'objet dans votre documentation, Cloud Monitoring détermine la ligne d'objet.

Vous pouvez configurer la ligne d'objet lorsque vous utilisez l'API Cloud Monitoring, Google Cloud CLI ou la console Google Cloud.

Pour obtenir un exemple d'implémentation, consultez la section Exemple de cette page.

Utiliser Markdown

Le champ de documentation accepte le sous-ensemble suivant de tags Markdown :

En-têtes, indiqués par des caractères de hachage initiaux.
Listes à puces, indiquées par les caractères initiaux plus, moins ou astérisque.
Listes numérotées, indiquées par un numéro initial suivi d'un point.
Texte en italique, indiqué par des traits de soulignement ou des astérisques simples autour d'une expression.
Texte en gras, indiqué par des traits de soulignement ou des astérisques doubles autour d'une expression.
Liens, indiqués par la syntaxe [link text](url).

Pour plus d'informations sur l'ajout de tags, consultez la documentation de référence sur Markdown, par exemple le guide Markdown.

Utiliser des variables

Pour personnaliser le texte de votre documentation, vous pouvez utiliser des variables au format ${varname}. Lorsque la documentation est envoyée avec une notification, la chaîne ${varname} est remplacée par une valeur tirée de la ressource Google Cloud correspondante, comme décrit dans le tableau suivant.

Variable	Valeur
`condition.name`	Nom de ressource REST de la condition, par exemple `projects/foo/alertPolicies/1234/conditions/5678`.
`condition.display_name`	Nom à afficher d'une condition, par exemple `CPU usage increasing rapidly`.
`log.extracted_label.KEY`	Valeur de l'étiquette `KEY`, extraite d'une entrée de journal. Pour les alertes basées sur les journaux uniquement. Pour en savoir plus, consultez Créer une alerte basée sur les journaux à l'aide de l'API Monitoring.
`metadata.system_label.KEY`	Valeur du libellé de métadonnée de ressource `KEY` fourni par le système.¹
`metadata.user_label.KEY`	La valeur du libellé des métadonnées de ressources définies par l'utilisateur `KEY`^1,3.
`metric.type`	Type de métrique, par exemple `compute.googleapis.com/instance/cpu/utilization`.
`metric.display_name`	Nom à afficher du type de métrique, par exemple `CPU utilization`.
`metric.label.KEY`	Valeur du libellé de métrique `KEY`.¹ Pour trouver les libellés associés au type de métrique, consultez la page Liste des métriques. Lorsque la valeur de la variable `${metric.label.KEY}` ne commence pas par un chiffre, une lettre, une barre oblique (`/`) ni un signe égal (`=`), Monitoring omet le libellé dans les notifications. Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champs d'alerte Prometheus `{{$value}}` et `{{humanize $value}}` apparaissent sous la forme `${metric.label.VALUE}`, dans la configuration de la documentation des règles d'alerte. Dans ce cas, `VALUE` contient la valeur de la requête PromQL. Vous pouvez également utiliser `${metric.label.VALUE}` lorsque vous créez des requêtes PromQL dans Google Cloud.
`metric_or_resource.labels`	Cette variable affiche toutes les valeurs de métriques et de libellés de ressources sous forme de liste triée de paires `key-value`. Si un libellé de métrique et un libellé de ressource portent le même nom, seul le libellé de métrique s'affiche. Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champs d'alerte Prometheus `{{$labels}}` et `{{humanize $labels}}` apparaissent sous la forme `${metric_or_resource.labels}` dans la configuration de la documentation de la règle d'alerte.
`metric_or_resource.label.KEY`	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é valide, ni une ressource valide, cette variable s'affiche dans la notification sous la forme d'une chaîne vide. Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champs d'alerte Prometheus `{{$labels.KEY}}` et `{{humanize $labels.KEY}}` apparaissent sous la forme `${metric_or_resource.labels.KEY}` dans la configuration de la documentation des règles d'alerte.
`policy.name`	Nom de ressource REST de la règle, par exemple `projects/foo/alertPolicies/1234`.
`policy.display_name`	Nom à afficher d'une règle, par exemple `High CPU rate of change`.
`policy.user_label.KEY`	Valeur du libellé de l'utilisateur `KEY`.¹ Les clés doivent commencer par une lettre minuscule. Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets.
`project`	ID de projet du champ d'application de métriques, tel que `a-gcp-project`.
`resource.type`	Type de ressource surveillée, tel que `gce_instance`.
`resource.project`	ID de projet de la ressource surveillée de la règle d'alerte.
`resource.label.KEY`	Valeur du libellé de ressource `KEY`.^1,2,3 Pour trouver les libellés associés au type de ressource surveillée, consultez la page Liste des ressources.

¹ Par exemple, ${resource.label.zone} est remplacé par la valeur du libellé zone. Les valeurs de ces variables peuvent être regroupées. Pour en savoir plus, consultez la section valeurs null.
² Pour récupérer la valeur du libellé project_id sur une ressource surveillée dans la règle d'alerte, utilisez ${resource.project}.
³ Vous ne pouvez pas accéder aux libellés de métadonnées de ressources définies par l'utilisateur en utilisant resource.label.KEY.. Utilisez metadata.user_label.KEY à la place.

Remarques sur l'utilisation

Seules les variables de la table sont compatibles. Vous ne pouvez pas les combiner en expressions plus complexes, comme ${varname1 + varname2}.
Pour inclure la chaîne littérale ${ dans votre documentation, échappez le symbole $ avec un second symbole $. $${ s'affiche alors sous la forme ${ dans votre documentation.
Ces variables ne sont remplacées par leurs valeurs que dans les notifications envoyées via les canaux de notification. Dans la console Google Cloud, lorsque la documentation est affichée, ce sont les variables, pas les valeurs. Les exemples présentés dans la console incluent les descriptions des incidents et l'aperçu de la documentation lors de la création d'une règle d'alerte.
Assurez-vous que les paramètres d'agrégation de la condition n'éliminent pas l'étiquette. Si le libellé est supprimé, sa valeur dans la notification est null. Pour en savoir plus, consultez la section La variable d'un libellé de métrique est nulle.

Exemple

L'exemple suivant présente les versions de la console Google Cloud et de l'API Cloud Monitoring de la documentation du modèle pour une règle d'alerte d'utilisation du processeur, ainsi que la documentation affichée dans le corps d'une notification. Cet exemple utilise une adresse e-mail pour le type de canal de notification. Le modèle de documentation inclut plusieurs variables pour résumer l'incident et référencer les ressources REST de règle d'alerte et de condition.

Console Google Cloud

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

API Cloud Monitoring

"documentation": {
"content": "## CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Mettre en forme la notification

Exemple d'affichage de la documentation dans une notification.

`null` valeurs

Les valeurs des variables metric.*, resource.* et metadata.* sont dérivées de séries temporelles. Leurs valeurs peuvent être null si aucune valeur n'est renvoyée par la requête de séries temporelles.

Les variables resource.label.KEY et metric.label.KEY peuvent avoir des valeurs null si votre règle d'alerte utilise une agrégation multi-série (réduction), par exemple pour calculer la SOMME sur chacune des séries temporelles correspondant à un filtre. Lorsque vous utilisez l'agrégation interséries, tous les libellés non utilisés dans le regroupement sont supprimés et, par conséquent, ils sont affichés en tant que null lorsque la variable est remplacée par sa valeur. Tous les libellés sont conservés en l'absence d'agrégation interséries. Pour en savoir plus, consultez la section La variable d'un libellé de métrique est nulle.
Les valeurs des variables metadata.* ne sont disponibles que si les libellés sont explicitement inclus dans le filtre ou le regroupement d'une condition utilisée pour l'agrégation interséries. En d'autres termes, pour que le libellé que vous référencez ait une valeur dans le modèle, il faut qu’il figure soit dans le filtre soit dans le regroupement.

Résolution variable

Les variables des modèles de documentation ne sont résolues que dans les notifications envoyées à l'aide des canaux de notification suivants:

Adresse e-mail
Slack
Pub/Sub, schéma JSON version 1.2
Webhooks, schéma JSON version 1.2
PagerDuty, schéma JSON version 1.2

Les variables ne sont pas résolues, mais apparaissent sous forme de chaînes comme ${varname} dans d'autres contextes, y compris les suivants:

Sur la page Détails de l'incident de la console Google Cloud
dans les notifications envoyées via d'autres canaux de notification ;

Utilisation des contrôles de canal

Le texte du champ de documentation peut également inclure des caractères spéciaux utilisés par le canal de notification lui-même pour contrôler la mise en forme et les notifications.

Par exemple, Slack utilise @ pour les mentions. Vous pouvez utiliser @ pour associer la notification à un ID utilisateur spécifique. Les mentions ne peuvent pas inclure de noms. Supposons que vous incluiez une chaîne comme celle-ci dans le champ de documentation:

<@backendoncall> Incident created based on policy ${policy.display_name}

Lorsque le champ de documentation est reçu par le canal Slack pertinent dans le cadre de la notification, la chaîne précédente oblige Slack à envoyer un message supplémentaire à l'ID utilisateur backendoncall. Le message envoyé par Slack à l'utilisateur peut contenir des informations pertinentes provenant de la notification, par exemple "Incident créé en fonction de la règle pour un taux de modification élevé du processeur".

Ces options supplémentaires sont spécifiques aux canaux. Pour en savoir plus sur les possibilités offertes, consultez la documentation fournie par le fournisseur du canal.