Benachrichtigungen mit benutzerdefinierter Dokumentation annotieren

Auf dieser Seite wird beschrieben, wie Sie die Dokumentation der Benachrichtigungsrichtlinie konfigurieren können, um den Text und die Betreffzeile Ihrer Benachrichtigungen anzupassen. In den Dokumentationsfeldern werden Nur-Text, Markdown, Variablen und kanalspezifische Steuerelemente unterstützt.

Informationen zur Benachrichtigung hinzufügen

Sie können Ihren Rettungskräften Abhilfemaßnahmen und Informationen zum Vorfall in der Benachrichtigung zur Verfügung stellen, indem Sie diesen Inhalt beim Erstellen der Benachrichtigungsrichtlinie angeben. Sie können die Benachrichtigungsrichtlinie beispielsweise so konfigurieren, dass alle Benachrichtigungen Links zu einem internen Playbook enthalten.

Eine Beispielimplementierung finden Sie auf dieser Seite im Abschnitt Beispiel.

Betreffzeile von Benachrichtigungen konfigurieren

Sie können Ihre Benachrichtigungen verwalten und sortieren, indem Sie die Betreffzeile dieser Benachrichtigungen angeben. Betreffzeilen sind auf 255 Zeichen beschränkt. Wenn Sie in der Dokumentation kein Thema definieren, wird die Betreffzeile von Cloud Monitoring bestimmt.

Sie können die Betreffzeile konfigurieren, wenn Sie die Cloud Monitoring API, die Google Cloud CLI oder die Google Cloud Console verwenden.

Eine Beispielimplementierung finden Sie auf dieser Seite im Abschnitt Beispiel.

Markdown verwenden

Im Dokumentationsfeld wird die folgende Teilmenge von Markdown-Tagging unterstützt:

• Header, dargestellt durch Anfangs-Hashzeichen.
• Unsortierte Listen, gekennzeichnet durch anfängliche Plus-, Minus- oder Sternchenzeichen.
• Sortierte Listen, gekennzeichnet durch eine anfängliche Zahl gefolgt von einem Punkt.
• Iterischer Text, gekennzeichnet durch einzelne Unterstriche oder Sternchen um eine Wortgruppe.
• Fettdruck, der durch doppelte Unterstriche oder Sternchen um eine Wortgruppe gekennzeichnet ist.
• Links, gekennzeichnet durch die Syntax [link text](url).

Weitere Informationen zu diesem Tagging finden Sie in der Markdown-Referenz, z. B. in der Markdown-Anleitung.

Variablen verwenden

Sie können Variablen im Format ${varname} verwenden, um den Text in Ihrer Dokumentation anzupassen. Wenn die Dokumentation mit einer Benachrichtigung gesendet wird, wird der String ${varname} wie in der folgenden Tabelle beschrieben durch einen Wert aus der entsprechenden Google Cloud-Ressource ersetzt.

Variable	Wert
condition.name	Der REST-Ressourcenname der Bedingung, z. B. projects/foo/alertPolicies/1234/conditions/5678
condition.display_name	Der Anzeigename einer Bedingung, z. B. CPU usage increasing rapidly
log.extracted_label.KEY	Der Wert des Labels KEY, extrahiert aus einem Logeintrag. Nur für logbasierte Benachrichtigungen. Weitere Informationen finden Sie unter Logbasierte Benachrichtigungen mit der Monitoring API erstellen.
metadata.system_label.KEY	Der Wert des vom System bereitgestellten Ressourcenmetadatenlabels KEY.^1
metadata.user_label.KEY	Der Wert des benutzerdefinierten Ressourcenmetadatenlabels KEY.^1,3
metric.type	Der Messwerttyp, z. B. compute.googleapis.com/instance/cpu/utilization
metric.display_name	Der Anzeigename für den Messwerttyp, z. B. CPU utilization
metric.label.KEY	Der Wert des Messwertlabels KEY.^1 Die mit dem Messwerttyp verknüpften Labels finden Sie in der Messwertliste. Wenn der Wert der Variablen ${metric.label.KEY} nicht mit einer Ziffer, einem Buchstaben, einem Schrägstrich (/) oder einem Gleichheitszeichen (=) beginnt, schließt Monitoring das Label bei Benachrichtigungen aus. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Vorlagen für das Prometheus-Benachrichtigungsfeld ({{$value}} und {{humanize $value}}) in der Konfiguration der Dokumentation der Benachrichtigungsrichtlinie als ${metric.label.VALUE} angezeigt. In diesem Fall enthält VALUE den Wert der PromQL-Abfrage. Sie können ${metric.label.VALUE} auch verwenden, wenn Sie PromQL-Abfragen in Google Cloud erstellen.
metric_or_resource.labels	Diese Variable rendert alle Messwert- und Ressourcenlabelwerte als sortierte Liste von key-value-Paaren. Wenn ein Messwertlabel und ein Ressourcenlabel denselben Namen haben, wird nur das Messwertlabel gerendert. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Vorlagen für die Prometheus-Benachrichtigungsfeld ({{$labels}} und {{humanize $labels}}) in der Dokumentation der Benachrichtigungsrichtlinie als ${metric_or_resource.labels} angezeigt.
metric_or_resource.label.KEY	Wenn KEY ein gültiges Label ist, wird diese Variable in der Benachrichtigung als Wert von ${metric.label.KEY} gerendert. Wenn KEY eine gültige Ressource ist, wird diese Variable in der Benachrichtigung als Wert von ${resource.label.KEY} gerendert. Wenn KEY weder ein gültiges Label noch eine gültige Ressource ist, wird diese Variable in der Benachrichtigung als leerer String gerendert. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Benachrichtigungsfeldvorlagen {{$labels.KEY}} und {{humanize $labels.KEY}} in der Konfiguration der Dokumentation der Benachrichtigungsrichtlinie als ${metric_or_resource.labels.KEY} angezeigt.
policy.name	Der REST-Ressourcenname der Richtlinie, z. B. projects/foo/alertPolicies/1234
policy.display_name	Der Anzeigename einer Richtlinie, z. B. High CPU rate of change
policy.user_label.KEY	Der Wert des Nutzerlabels KEY.^1 Schlüssel müssen mit einem Kleinbuchstaben beginnen. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten.
project	Die ID des Bereichprojekts des Messwertbereichs, z. B. a-gcp-project.
resource.type	Der Typ der überwachten Ressource, z. B. gce_instance.
resource.project	Die Projekt-ID der überwachten Ressource der Benachrichtigungsrichtlinie
resource.label.KEY	Der Wert des Ressourcenlabels KEY.^1, 2, 3 Informationen zu den Labels, die dem Typ der überwachten Ressource zugeordnet sind, finden Sie in der Ressourcenliste.

¹ Beispielsweise wird ${resource.label.zone} durch den Wert des zone-Labels ersetzt. Die Werte dieser Variablen unterliegen einer Gruppierung. Weitere Informationen finden Sie unter null-Werte.
² Verwenden Sie ${resource.project}, um den Wert des Labels project_id für eine überwachte Ressource in der Benachrichtigungsrichtlinie abzurufen.
³ Sie können nicht mit resource.label.KEY. auf benutzerdefinierte Ressourcenmetadatenlabels zugreifen. Verwenden Sie stattdessen metadata.user_label.KEY.

Verwendungshinweise

• Nur die Variablen in der Tabelle werden unterstützt. Sie können sie nicht zu komplexeren Ausdrücken wie etwa ${varname1 + varname2} kombinieren.
• Wenn Sie den literalen String ${ in Ihre Dokumentation aufnehmen möchten, verwenden Sie das $-Symbol mit einem zweiten $-Symbol als Escapezeichen. Dadurch wird $${ in Ihrer Dokumentation als ${ gerendert.
• Diese Variablen werden nur in Benachrichtigungen, die über Benachrichtigungskanäle gesendet werden, durch ihre Werte ersetzt. Wenn die Dokumentation in der Google Cloud Console angezeigt wird, werden die Variablen und nicht die Werte angezeigt. Beispiele in der Konsole sind die Beschreibungen von Vorfällen und die Vorschau der Dokumentation beim Erstellen einer Benachrichtigungsrichtlinie.
• Achten Sie darauf, dass das Label durch die Aggregationseinstellungen der Bedingung nicht entfernt wird. Wenn das Label entfernt wird, hat das Label in der Benachrichtigung den Wert null. Weitere Informationen finden Sie unter Variable für ein Messwertlabel ist null.

Hinweis: Labels, die Sie logbasierten Messwerten hinzufügen, können nicht in Vorlagenausdrücken verwendet werden. Sie können diese Labels jedoch in Diagrammlegenden anzeigen und Zeitachsen nach den Labelwerten filtern.

Beispiel

Das folgende Beispiel zeigt die Versionen der Google Cloud Console und der Cloud Monitoring API der Vorlagendokumentation für eine Benachrichtigungsrichtlinie zur CPU-Auslastung sowie die gerenderte Dokumentation, die im Text einer Benachrichtigung angezeigt wird. In diesem Beispiel wird eine E-Mail-Adresse als Benachrichtigungskanaltyp verwendet. Die Dokumentationsvorlage enthält mehrere Variablen, um den Vorfall zusammenzufassen und auf die Benachrichtigungsrichtlinie und die REST-Ressourcen für Bedingungen zu verweisen.

Google Cloud Console

Hinweis: Die Betreffzeile einer Benachrichtigung wird auf der Seite „Benachrichtigungsrichtlinie erstellen“ im Abschnitt „Benachrichtigungen und Name“ konfiguriert.

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

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

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

Cloud Monitoring API

"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 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Hinweis :Der Text subject wird in der Betreffzeile der Benachrichtigung angezeigt.

In Benachrichtigung formatieren

null values

Die Werte für die Variablen metric.*, resource.* und metadata.* werden aus Zeitachsen abgeleitet. Ihre Werte können null sein, wenn von der Zeitachsenabfrage keine Werte zurückgegeben werden.

• Die Variablen resource.label.KEY und metric.label.KEY können null-Werte haben, wenn Ihre Benachrichtigungsrichtlinie eine reihenübergreifende Aggregation (Reduzierung) verwendet, z. B. indem die SUMME für jede der Zeitachsen berechnet wird, die einem Filter entsprechen. Bei der reihenübergreifenden Aggregation werden alle nicht zur Gruppierung verwendeten Labels entfernt und folglich als null gerendert, wenn die Variable durch ihren Wert ersetzt wird. Alle Labels werden beibehalten, wenn es keine reihenübergreifende Aggregation gibt. Weitere Informationen finden Sie unter Variable für ein Messwertlabel ist null.

• Werte für metadata.*-Variablen sind nur verfügbar, wenn die Labels explizit im Filter einer Bedingung oder Gruppierung für eine achsenübergreifende Zusammenfassung enthalten sind. Das heißt, Sie müssen auf das Metadatenlabel im Filter oder in der Gruppierung verweisen, damit es einen Wert für die Vorlage hat.

Variable Auflösung

Variablen in Dokumentationsvorlagen werden nur in den Benachrichtigungen aufgelöst, die über die folgenden Benachrichtigungskanäle gesendet werden:

• E-Mail
• Slack
• Pub/Sub, JSON-Schemaversion 1.2
• Webhooks, JSON-Schemaversion 1.2
• PagerDuty, JSON-Schemaversion 1.2

Variablen werden nicht aufgelöst, aber in anderen Kontexten als Strings wie ${varname} angezeigt:

• In der Google Cloud Console auf der Seite Vorfalldetails:
• In Benachrichtigungen, die über andere Benachrichtigungskanäle gesendet wurden

Kanalsteuerelemente verwenden

Der Text im Dokumentationsfeld kann auch Sonderzeichen enthalten, die vom Benachrichtigungskanal selbst zur Steuerung von Formatierungen und Benachrichtigungen verwendet werden.

Zum Beispiel verwendet Slack @ für Erwähnungen. Mit @ kannst du die Benachrichtigung mit einer bestimmten Nutzer-ID verknüpfen. Erwähnungen dürfen keine Namen enthalten. Angenommen, Sie fügen einen String wie den folgenden in das Dokumentationsfeld ein:

<@backendoncall> Incident created based on policy ${policy.display_name}

Wenn das Dokumentationsfeld als Teil der Benachrichtigung vom entsprechenden Slack-Kanal empfangen wird, veranlasst der vorherige String Slack, eine zusätzliche Nachricht an die Nutzer-ID backendoncall zu senden. Die von Slack an den Nutzer gesendete Nachricht könnte relevante Informationen aus der Benachrichtigung enthalten, z. B. „Ein auf Grundlage der Richtlinie erstellter Vorfall – hohe CPU-Änderungsrate“.

Diese zusätzlichen Optionen sind kanalspezifisch. Weitere Informationen zu den verfügbaren Optionen finden Sie in der Dokumentation des Kanalanbieters.