Cette page explique comment configurer la documentation de vos règles d'alerte afin que les notifications fournissent aux équipes de réponse aux incidents des ressources et des informations supplémentaires pour la résolution des incidents.
Structure de la documentation
La documentation d'une règle d'alerte comprend un objet, du contenu et des 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 apparaît dans l'objet des notifications 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 en utilisant le champ Ligne d'objet de la notification dans la section Notifications et nom de la page Créer une règle d'alerte.
Contenus
Le contenu de votre documentation apparaît dans les types de notifications suivants:
- Adresse e-mail, sous l'en-tête Documentation du règlement
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Nous vous recommandons de configurer votre contenu afin que les intervenants en cas d'incident puissent voir les mesures correctives et les informations sur les incidents dans les notifications liées à votre règle 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 le texte brut, le Markdown, les variables et les paramètres spécifiques à un canal.
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 de la section Notifications et nom de la page Créer une règle d'alerte.
Liens
Vous pouvez ajouter des liens vers votre documentation afin que les spécialistes 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 les types de notifications suivants:
- E-mail, sous l'en-tête Liens rapides
- PagerDuty
- Pub/Sub
- Webhooks
Pour configurer une association, ajoutez un Link
au documentation
de votre règle d'alerte.
Chaque lien est représenté par un display_name
et un url
. Votre documentation peut contenir
jusqu'à trois liens.
La configuration suivante utilise links
avec une URL pour créer un lien vers un playbook sur les incidents. L'URL inclut une variable permettant aux destinataires des notifications d'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 de votre contenu de 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 répertorie 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 est compatible avec le sous-ensemble suivant de balises 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'objetLink
pour configurer des liens pour 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 extraite 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 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.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 Lorsque la valeur de la variable Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champ d'alerte Prometheus Vous pouvez également utiliser |
metric_or_resource.labels |
Cette variable affiche toutes les valeurs de libellé de métrique et de ressource sous la forme d'une liste triée de paires Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champ d'alerte Prometheus |
metric_or_resource.label.KEY |
Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champ d'alerte Prometheus |
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 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 |
La valeur du libellé de ressource KEY .1,2,3Pour trouver les libellés associés au type de ressource surveillée, consultez la section Liste des ressources. |
1 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
.
2 Pour récupérer la valeur du libellé project_id
sur une ressource surveillée dans la règle d'alerte, utilisez ${resource.project}
.
3 Vous ne pouvez pas accéder aux libellés de métadonnées de ressources définis 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, telles que
${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 s'affiche, vous voyez les variables, et non 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 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.
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
etmetric.label.KEY
peuvent avoir des valeursnull
si votre règle d'alerte utilise l'agrégation interséries (réduction), par exemple en calculant 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 quenull
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:
- 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 incluiez 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 oblige Slack à envoyer un message supplémentaire à l'ID utilisateur backendoncall
. Le message envoyé par Slack à l'utilisateur peut contenir des informations pertinentes issues de la notification, par exemple "Incident créé en fonction du taux de modification du processeur élevé" de la règle.
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 montre 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. Dans ces exemples, le type de canal de notification correspond à une adresse e-mail. Les modèles de documentation incluent plusieurs variables pour résumer l'incident et référencer les ressources REST de règle d'alerte et de 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:
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: