Variables dans les modèles de documentation

Cette page décrit les variables et les contrôles spécifiques aux canaux disponibles dans le modèle de documentation associé à une règle d'alerte.

Utiliser des variables

En plus de Markdown, vous pouvez utiliser des variables ayant la forme ${varname} pour adapter le contenu de votre documentation. Lorsque la documentation est envoyée avec une notification, la chaîne ${varname} est remplacée par la valeur de varname. La capture d'écran suivante montre la documentation incluse dans une notification par e-mail, créée à partir du modèle de documentation spécifié pour une règle d'alerte :

Documentation incluse dans l'e-mail.

Pour en savoir plus sur la création d'un modèle de documentation pour une règle d'alerte, consultez l'étape facultative permettant de spécifier la documentation à inclure dans les notifications.

Les variables suivantes sont disponibles pour une utilisation dans les champs de la documentation :

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.
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ée de ressource KEY défini par l'utilisateur.1,4
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.

Les valeurs doivent être précédées d'un chiffre, d'une lettre, d'une barre oblique (/) ou d'un signe égal (=). Tous les autres préfixes ne sont pas interdits. Si une valeur contient un préfixe non pris en charge, elle n'est pas signalée.

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,2
project ID de projet de l'espace de travail, par exemple 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é KEY de la ressource.1,3,4
Pour accéder à la liste des 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 Les libellés de l'utilisateur dans une règle ne peuvent être définis qu'à l'aide de l'API Monitoring.
3 Pour récupérer la valeur du libellé project_id sur une ressource surveillée dans la règle d'alerte, utilisez ${resource.project}.
4 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.

Valeurs null

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). En cas d'agrégation interséries, tous les libellés non utilisés dans le regroupement sont abandonnés et ont des valeurs null s'ils sont référencés dans la substitution de variables. Ces libellés sont automatiquement conservés s'il n'y a pas d'agrégation interséries.
  • 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.

Autres 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 $. $${ sera affiché 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 Google Cloud Console, 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.

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 ce lien pour associer la notification à un utilisateur spécifique. Supposons que vous incluez une chaîne de ce type dans le champ de documentation :

<@backendoncall> policy ${policy.display_name} triggered an incident

Lorsque le champ de documentation est reçu par le canal Slack pertinent dans le cadre de la notification, cette ligne déclenche l'envoi d'un message supplémentaire à l'utilisateur backendoncall, par exemple policy High CPU rate of change triggered an incident.

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.