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

Annoter les notifications avec une 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 documentation s'affiche dans l'objet des notifications pour les incidents liés à votre règle d'alerte. Les destinataires des notifications peuvent les gérer et les trier par sujet.

Les lignes d'objet sont limitées à 255 caractères. Si vous ne définissez pas d'objet dans votre documentation, Cloud Monitoring détermine la ligne d'objet. Les lignes d'objet acceptent le texte brut et les 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 du champ Ligne d'objet de la notification dans la 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 est compatible avec les éléments suivants:

Texte brut
Variables
Commandes spécifiques à la chaîne
Markdown dans les canaux de notification autres que Slack

API Cloud Monitoring

Configurez 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 vers la documentation configurés dans l'API Cloud Monitoring apparaissent dans les 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 vers la documentation configurés dans la console Google Cloud s'affichent avec le reste du contenu de la documentation dans les types de notifications suivants:

Par e-mail, sous l'en-tête Documentation sur les règles
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}

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 ayant la forme ${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 du libellé `KEY`, extraite d'une entrée de journal. Pour les règles d'alerte basées sur les journaux uniquement. Pour en savoir plus, consultez la section 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.¹
`metadata.user_label.KEY`	Valeur du libellé de métadonnées de ressource défini 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 (`/`) ou un signe égal (`=`), la surveillance ne l'inclut pas dans les notifications. Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champ d'alerte Prometheus `{{$value}}` et `{{humanize $value}}` apparaissent sous la forme `${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.label.metadata_system_VALUE`	Fait référence à un libellé système de métadonnées PromQL, où `VALUE` est le nom spécifique du libellé, tel que `region` ou `version`. Exemple d'utilisation : `${metric.label.metadata_system_version}`.
`metric.label.metadata_user_VALUE`	Fait référence à un libellé utilisateur de métadonnées PromQL, où `VALUE` est le nom spécifique du libellé, tel que `region` ou `name`. Exemple d'utilisation: `${metric.label.metadata_user_name}`.
`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 sous la forme de la valeur de `${metric.label.KEY}`. Si `KEY` est une ressource valide, cette variable s'affiche dans la notification sous la forme de la 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`.¹ 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 des métadonnées de ressource définies par l'utilisateur à l'aide de la commande resource.label.KEY.. Utilisez la commande metadata.user_label.KEY.

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, 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 le libellé est éliminé, la valeur du libellé dans la notification est null. Pour en savoir plus, consultez Variable pour un libellé de métrique est nulle.

`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 l'agrégation interséries (réduction), par exemple pour le calcul de 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 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

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 entraîne l'envoi d'un message supplémentaire à l'ID utilisateur backendoncall. Le message envoyé par Slack à l'utilisateur peut contenir des informations pertinentes de la notification, par exemple "Incident créé en fonction du 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 s'affiche dans une notification par e-mail:

Exemple de rendu de la documentation dans une notification. Les liens s'affichent dans la section "Liens rapides".

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:

Exemple de rendu de la documentation dans une notification. Les liens s'affichent sous l'en-tête "Références de dépannage et de débogage".

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

Structure de la documentation

Sujets

API Cloud Monitoring

Console Google Cloud

Contenu

API Cloud Monitoring

Console Google Cloud

Liens

API Cloud Monitoring

Console Google Cloud

Markdown dans le contenu de la documentation

Variables dans la documentation

Remarques sur l'utilisation

null valeurs

Résolution variable

Commandes de la chaîne

Exemple

API Cloud Monitoring

Console Google Cloud

`null` valeurs