Cette page explique comment configurer la documentation de votre règle d'alerte afin que les notifications fournissent aux personnes chargées de répondre aux alertes des ressources et des informations supplémentaires pour résoudre les alertes.
Structure de la documentation
La documentation d'une règle d'alerte se compose d'un sujet, d'un contenu et de liens. Vous pouvez configurer la documentation dans la console Google Cloud , l'API Cloud Monitoring et Google Cloud CLI.
Sujets
Le sujet de votre documentation apparaît dans l'objet des notifications d'alertes liées à 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 l'objet de la notification à l'aide du champ subject de la règle d'alerte documentation.
Console Google Cloud
Configurez l'objet de la notification à l'aide du champ 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 apparaît dans les types de notifications suivants :
- E-mail, dans la section Documentation sur les règles
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Nous vous recommandons de configurer votre contenu de sorte que les personnes chargées de répondre aux alertes puissent consulter les étapes de correction et les informations sur les alertes dans les notifications liées à votre règle d'alerte. Par exemple, vous pouvez configurer la documentation pour inclure un récapitulatif de l'alerte et des informations sur les ressources pertinentes.
Le contenu de la documentation est compatible avec les éléments suivants :
- Texte brut
- Variables
- Paramètres spécifiques à une chaîne
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 vers votre documentation afin que les personnes chargées de répondre aux alertes puissent accéder à des ressources telles que des playbooks, des dépôts et des tableaux de bord Google Cloud à partir d'une notification.
L'API Cloud Monitoring vous permet de définir un objet contenant les liens les plus pertinents pour les personnes chargées de répondre. Bien que la console Google Cloud ne comporte pas de champ spécifique pour les liens, vous pouvez ajouter une section pour les liens dans le corps de votre documentation.
API Cloud Monitoring
Vous pouvez ajouter des liens vers votre documentation en définissant un ou plusieurs objets Link dans le champ links de la règle d'alerte documentation. Chaque objet Link se compose d'un display_name et d'un url. Vous pouvez inclure jusqu'à trois liens dans votre documentation.
La configuration suivante montre le champ links avec un objet Link représentant l'URL d'un playbook d'alerte. L'URL inclut une variable afin que les destinataires des notifications puissent accéder au playbook approprié en fonction de la ressource surveillée sur laquelle l'alerte s'est produite :
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Les liens vers la documentation ajoutés à l'aide du champ Link s'affichent dans les types de notifications suivants :
- E-mail, dans la section Liens rapides
- PagerDuty
- Pub/Sub
- Webhooks
Console Google Cloud
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}
Les liens vers la documentation ajoutés à l'aide de la console Google Cloud s'affichent avec le reste du contenu de votre documentation dans les types de notifications suivants :
- E-mail, dans la section Documentation sur les règles
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Markdown dans le contenu de la documentation
Vous pouvez utiliser le format 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). Pour ajouter des liens à votre notification, nous vous recommandons d'utiliser l'API Cloud Monitoring et de configurer l'objetLink.
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 de la forme ${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 Pour les règles d'alerte basées sur les journaux que vous créez à l'aide de l'explorateur de journaux, la valeur de ce champ est |
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
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 du libellé de métadonnées de ressource KEY défini par l'utilisateur.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 champs d'alerte Prometheus Vous pouvez également utiliser |
metric.label.metadata_system_VALUE |
Fait référence à un libellé système de métadonnées PromQL, où VALUE est le nom de libellé spécifique, tel que Exemple d'utilisation :
|
metric.label.metadata_user_VALUE |
Fait référence à un libellé utilisateur de métadonnées PromQL, où VALUE est le nom du libellé spécifique, tel que Exemple d'utilisation : |
metric_or_resource.labels |
Cette variable affiche toutes les valeurs de libellés de métriques et de ressources sous forme de liste triée de paires Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champs d'alerte Prometheus |
metric_or_resource.label.KEY |
Lorsque vous migrez une règle d'alerte Prometheus, les modèles de champs 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 du projet de la ressource surveillée de la règle d'alerte. |
resource.label.KEY |
Valeur du libellé de ressource KEY.1,2,3Pour trouver les libellés associés au type de ressource surveillée, consultez la page 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 à l'aide de resource.label.KEY.. Utilisez plutôt 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. - Les règles d'alerte affichent toujours des chaînes de variables telles que
${varname}. - Pour certains canaux de notification, Cloud Monitoring remplace les chaînes de variables telles que
${varname}par les valeurs correspondantes. Pour en savoir plus, consultez Résolution des variables. - Lorsque la console Google Cloud affiche la vue détaillée d'une alerte, elle remplace généralement les chaînes de variables telles que
${varname}par les valeurs correspondantes. - Vérifiez que les paramètres d'agrégation de la condition n'éliminent pas le libellé. Si le libellé est éliminé, sa valeur dans la notification est
null. Pour en savoir plus, consultez 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.KEYetmetric.label.KEYpeuvent avoir des valeursnullsi votre règle d'alerte utilise une agrégation (réduction) interséries, 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 quenulllorsque 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 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 sont résolues dans les contextes suivants :
- Notifications envoyées à l'aide des canaux de notification suivants :
- Google Chat
- Slack
- Pub/Sub, version 1.2 du schéma JSON
- Webhooks, schéma JSON version 1.2
- PagerDuty, schéma JSON version 1.2
- Vue des détails des alertes de la console Google Cloud .
Paramètres 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> Alert 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 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 "Alerte créée en fonction de la règle "Haute variation de l'utilisation du processeur"".
Ces options supplémentaires sont spécifiques aux chaînes. Pour en savoir plus sur les possibilités sans frais, consultez la documentation fournie par le fournisseur de la chaîne.
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 sur l'utilisation du processeur. Ces exemples utilisent un e-mail pour le type de canal de notification. Les modèles de documentation incluent plusieurs variables permettant de résumer l'alerte et de référencer les ressources REST de la règle et de la condition d'alerte.
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 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 apparaît dans une notification par e-mail :
