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

Cette page explique comment configurer la documentation de votre règle d'alerte afin que les notifications fournissent aux personnes chargées de la résolution des incidents des ressources et des informations supplémentaires.

Structure de la documentation

La documentation d'une règle d'alerte se compose d'un objet, d'un contenu et de liens. Vous pouvez configurer la documentation dans la console Google Cloud, l'API Cloud Monitoring et la Google Cloud CLI.

Sujets

L'objet de votre document figure dans l'objet de pour les incidents liés à votre règle d'alerte. Les destinataires peuvent gérer et trier leurs notifications par objet.

L'objet des messages 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 ne pouvez utiliser que du texte brut dans l'objet des messages ni des variables.

API Cloud Monitoring

Configurez la ligne d'objet de la notification à l'aide du champ subject. de la règle d'alerte documentation.

console Google Cloud

Configurez la ligne d'objet de la notification à l'aide de la propriété Le champ Ligne d'objet de la notification Section Notifications et nom de la page Créer une règle d'alerte

Contenu

Le contenu de votre documentation s'affiche dans les types de notifications suivants :

• Par e-mail, sous l'en-tête Documentation sur les règles
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Nous vous recommandons de configurer votre contenu afin que les personnes chargées de la gestion des incidents puissent consulter les étapes de résolution et les informations sur l'incident dans les notifications liées à votre stratégie d'alerte. Par exemple, vous pouvez configurer la documentation pour inclure un résumé de l'incident et des informations sur les ressources pertinentes.

Le contenu de la documentation accepte les formats de texte brut, Markdown, variables et paramètres propres à la chaîne.

API Cloud Monitoring

Configurer le contenu de la documentation à l'aide du champ content de la règle d'alerte documentation.

console Google Cloud

Configurez le contenu de la documentation à l'aide du champ Documentation dans la section Notifications et nom de la page Créer une règle d'alerte.

Liens

Vous pouvez ajouter des liens à votre documentation afin que les personnes chargées de la gestion des incidents puissent accéder à des ressources telles que des playbooks, des dépôts et des tableaux de bord Google Cloud à partir d'une notification.

API Cloud Monitoring

Les liens de documentation configurés dans l'API Cloud Monitoring apparaissent dans types de notifications suivants:

• E-mail, sous l'en-tête Quick Links (Liens rapides)
• PagerDuty
• Pub/Sub
• Webhooks

Pour configurer un lien, ajoutez un Link à l'documentation de votre règle d'alerte. Chaque lien est représenté par un display_name et un url. Vous pouvez inclure jusqu'à trois liens dans votre documentation.

La configuration suivante utilise links avec une URL pour créer un lien vers un playbook d'incident. L'URL inclut une variable afin que les destinataires de la notification puissent accéder au playbook approprié en fonction de la ressource surveillée où l'incident s'est produit :

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

console Google Cloud

Les liens de documentation configurés dans la console Google Cloud apparaissent avec le reste du contenu de la documentation dans les types de notifications suivants:

• Adresse e-mail, sous l'en-tête Documentation du règlement
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Vous pouvez ajouter des liens vers le contenu de votre documentation en les incluant dans le champ Documentation de votre règle d'alerte. Par exemple, la documentation suivante liste une URL pour un playbook client:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

Remarque :La console Google Cloud ne permet pas de configurer l'objet Links pour les règles d'alerte.

Markdown dans le contenu de la documentation

Vous pouvez utiliser Markdown pour mettre en forme le contenu de votre documentation. Le contenu de la 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). Toutefois, nous vous recommandons d'utiliser l'objet Link pour configurer les liens de votre contenu.

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

Variables dans la documentation

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 à partir d'une entrée de journal. Pour les règles d'alerte basées sur les journaux uniquement. pour en savoir plus d'informations, voir <ph type="x-smartling-placeholder"></ph> Créer une règle d'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.^1
metadata.user_label.KEY	Valeur de l'étiquette de métadonnées de ressource définie 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.^1 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 (/) ; ou un signe égal (=), Monitoring omet le libellé dans les notifications. Lorsque vous migrez une règle d'alerte Prometheus, le champ d'alerte Prometheus modélise {{$value}}. et {{humanize $value}} apparaissent comme ${metric.label.VALUE} dans la configuration de la documentation sur les 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 des libellés de métrique et de ressource 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 est affiché. Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champ d'alerte Prometheus {{$labels}} et {{humanize $labels}} apparaissent sous la forme ${metric_or_resource.labels} dans la configuration de la documentation sur les règles 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é 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 champ 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.^1 Les clés doivent commencer par une lettre minuscule. Les clés et les valeurs peuvent contenir uniquement 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 étiquettes de métadonnées de ressources définies par l'utilisateur avec 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 dans des 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, vous voyez 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 le libellé. Si l'étiquette est éliminée, la valeur de l'étiquette dans la notification est null. Pour en savoir plus, consultez la section Variable pour un libellé de métrique est nulle.

Remarque :Les étiquettes que vous ajoutez aux métriques basées sur les journaux ne peuvent pas être utilisées dans le modèle . Toutefois, vous pouvez afficher ces libellés dans les légendes des graphiques et filtrer les séries temporelles en fonction des valeurs des libellés.

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 Valeurs null si votre règle d'alerte utilise l'agrégation interséries (réduction), par exemple pour calculer la SOMME dans chacun des 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 Variable pour 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:

• E-mail
• Google Chat
• Slack
• Pub/Sub, schéma JSON version 1.2
• Webhooks, schéma JSON version 1.2
• PagerDuty, schéma JSON version 1.2

Remarque : Les variables ne sont pas résolues, mais apparaissent sous forme de chaînes telles que ${varname}, dans d'autres contextes, dans les notifications envoyées à l'aide d'autres canaux de notification.

Commandes de la chaîne

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 incluez une chaîne de ce type 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 amène Slack à envoyer une message supplémentaire à l'ID utilisateur backendoncall Message envoyé par Slack à l'utilisateur s'il comporte des informations pertinentes issues de la notification ; Exemple : "Incident créé en fonction de la règle 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.

Exemple

L'exemple suivant présente les versions de la documentation du modèle pour une règle d'alerte d'utilisation du processeur dans la console Google Cloud et l'API Cloud Monitoring. Dans ces exemples, un e-mail est utilisé pour le type de canal de notification. Les modèles de documentation incluent plusieurs variables pour résumer l'incident et faire référence à la règle d'alerte et aux ressources REST de la condition.

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 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}",
    "mimeType": "text/markdown",
    "subject": "Alert: ${metric.display_name} exceeded",
    "links": [
      {
        "displayName": "Playbook",
        "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
      },
      {
        "displayName": "Repository with debug scripts",
        "url": "https://altostrat.com"
      },
      {
        "displayName": "Google Cloud dashboard",
        "url": "https://example.com"
      }
    ]
  }

L'image suivante montre comment ce modèle apparaît dans un e-mail notification:

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 5% for over 60 seconds.

#### Additional resource information

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

#### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}  
Repository with debug scripts: https://altostrat.com  
${resource.type} dashboard: https://example.com

L'image suivante montre comment ce modèle s'affiche dans une notification par e-mail :