Auf dieser Seite wird beschrieben, wie Sie die Dokumentation Ihrer Benachrichtigungsrichtlinie so konfigurieren können, dass Benachrichtigungen den Reaktionspersonen für Vorfälle Ressourcen und zusätzliche Informationen zur Behebung von Vorfällen zur Verfügung stellen.
Dokumentationsstruktur
Die Dokumentation einer Benachrichtigungsrichtlinie besteht aus einem Betreff, Inhalt und Links. Sie können die Dokumentation in der Google Cloud Console, der Cloud Monitoring API und der Google Cloud CLI konfigurieren.
Betreffzeilen
Der Betreff Ihrer Dokumentation wird im Betreff von Benachrichtigungen für Vorfälle angezeigt, die mit Ihrer Benachrichtigungsrichtlinie zusammenhängen. Empfänger von Benachrichtigungen können ihre Benachrichtigungen nach Betreff verwalten und sortieren.
Betreffzeilen dürfen maximal 255 Zeichen lang sein. Wenn Sie in Ihrer Dokumentation keinen Betreff definieren, wird die Betreffzeile von Cloud Monitoring festgelegt. Betreffzeilen unterstützen Nur-Text und Variablen.
Cloud Monitoring API
Konfigurieren Sie die Betreffzeile der Benachrichtigung mit dem Feld subject
der Benachrichtigungsrichtlinie documentation.
Google Cloud Console
Konfigurieren Sie die Betreffzeile der Benachrichtigung mit dem Feld Notification subject line (Betreffzeile der Benachrichtigung) im Bereich Notifications and name (Benachrichtigungen und Name) auf der Seite Create alerting policy (Benachrichtigungsrichtlinie erstellen).
Inhalt
Der Inhalt Ihrer Dokumentation wird in den folgenden Benachrichtigungstypen angezeigt:
- E‑Mail im Bereich Policy Documentation (Richtliniendokumentation)
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Wir empfehlen, den Inhalt so zu konfigurieren, dass Reaktionspersonen für Vorfälle in Benachrichtigungen zu Ihrer Benachrichtigungsrichtlinie Schritte zur Behebung und Informationen zu Vorfällen sehen können. Sie können die Dokumentation beispielsweise so konfigurieren, dass sie eine Zusammenfassung des Vorfalls und Informationen zu relevanten Ressourcen enthält.
Dokumentationsinhalte unterstützen Folgendes:
Cloud Monitoring API
Konfigurieren Sie den Dokumentationsinhalt mit dem content Feld
der Benachrichtigungsrichtlinie documentation.
Google Cloud Console
Konfigurieren Sie den Dokumentationsinhalt mit dem Feld Documentation (Dokumentation) im Bereich Notifications and name (Benachrichtigungen und Name) auf der Seite Create alerting policy (Benachrichtigungsrichtlinie erstellen).
Links
Sie können Ihrer Dokumentation Links hinzufügen, damit Reaktionspersonen für Vorfälle über eine Benachrichtigung auf Ressourcen wie Playbooks, Repositories und Google Cloud Dashboards zugreifen können.
Mit der Cloud Monitoring API können Sie ein Objekt definieren, das die wichtigsten Links für Reaktionspersonen enthält. Die Google Cloud Console hat zwar kein Feld speziell für Links, Sie können aber einen Abschnitt für Links im Textkörper Ihrer Dokumentation hinzufügen.
Cloud Monitoring API
Sie können Ihrer Dokumentation Links hinzufügen, indem Sie ein oder mehrere
Link-Objekte im Feld links der Benachrichtigungsrichtlinie
documentation definieren. Jedes Link-Objekt besteht aus einem display_name und einer url. Ihre Dokumentation kann bis zu drei Links enthalten.
Die folgende Konfiguration zeigt das Feld links mit einem Link-Objekt, das eine URL zu einem Vorfall-Playbook darstellt. Die URL enthält eine Variable, damit Empfänger von Benachrichtigungen auf das richtige Playbook zugreifen können, je nachdem, auf welcher überwachten Ressource der Vorfall aufgetreten ist:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Dokumentationslinks, die mit dem Feld Link hinzugefügt wurden, werden in den folgenden Benachrichtigungstypen angezeigt:
- E‑Mail im Bereich Quick Links (Schnelllinks)
- PagerDuty
- Pub/Sub
- Webhooks
Google Cloud Console
Sie können Ihrem Dokumentationsinhalt Links hinzufügen, indem Sie sie in das Feld Documentation (Dokumentation) Ihrer Benachrichtigungsrichtlinie einfügen. Die folgende Dokumentation enthält beispielsweise eine URL für ein Kunden-Playbook:
### Troubleshooting and Debug References
Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Dokumentationslinks, die mit der Google Cloud Console hinzugefügt wurden, werden mit dem Rest Ihres Dokumentationsinhalts in den folgenden Benachrichtigungstypen angezeigt:
- E‑Mail im Bereich Policy Documentation (Richtliniendokumentation)
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Markdown im Dokumentationsinhalt
Sie können Markdown verwenden, um den Inhalt Ihrer Dokumentation zu formatieren. Dokumentationsinhalte unterstützen die folgende Teilmenge von Markdown-Tagging:
- 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). Wenn Sie Ihrer Benachrichtigung Links hinzufügen möchten, empfehlen wir Ihnen, die Cloud Monitoring API zu verwenden und dasLinkObjekt zu konfigurieren.
Weitere Informationen zu diesem Tagging finden Sie in der Markdown-Referenz, z. B. in der Markdown-Anleitung.
Variablen in der Dokumentation
Wenn Sie den Text in Ihrer Dokumentation anpassen möchten, können Sie Variablen der Form ${varname} verwenden. Wenn die Dokumentation mit
einer Benachrichtigung gesendet wird, wird der String ${varname} durch einen Wert aus der
entsprechenden Google Cloud Ressource ersetzt, wie in der folgenden Tabelle beschrieben.
| 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.
Bei logbasierten Benachrichtigungsrichtlinien, die Sie mit dem
Logs Explorer erstellen, ist der Wert dieses Felds
|
log.extracted_label.KEY |
Der Wert des Labels KEY, der aus einem Logeintrag extrahiert wurde. Nur für logbasierte Benachrichtigungsrichtlinien. Weitere Informationen finden Sie unter
Logbasierte Benachrichtigungsrichtlinie 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 nutzerdefinierten 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 Wenn der Wert der Variablen Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Vorlagen für Benachrichtigungsfelder Sie können |
metric.label.metadata_system_VALUE |
Verweist auf ein PromQL-Metadatensystemlabel,
wobei VALUE der spezifische Labelname ist, z. B.
Beispiel für die Verwendung:
|
metric.label.metadata_user_VALUE |
Verweist auf ein PromQL-Metadatenlabel, wobei VALUE der spezifische Labelname ist, z. B. Beispiel für die Verwendung: |
metric_or_resource.labels |
Diese Variable rendert alle Messwert- und Ressourcenlabelwerte als sortierte Liste von Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Vorlagen für Benachrichtigungsfelder |
metric_or_resource.label.KEY |
Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Vorlagen für Benachrichtigungsfelder |
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,3Die mit dem Typ der überwachten Ressource verknüpften Labels finden Sie unter Ressourcenliste. |
1 Beispielsweise wird ${resource.label.zone} durch
den Wert des Labels zone ersetzt. Die Werte dieser Variablen unterliegen einer
Gruppierung. Weitere Informationen finden Sie unter nullWerte.
2 Verwenden Sie ${resource.project}, um den Wert des Labels project_id für eine mit der Benachrichtigungsrichtlinie überwachte Ressource abzurufen.
3 Sie können nicht mit resource.label.KEY. auf nutzerdefinierte 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
${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, sehen Sie nicht die Werte, sondern die Variablen. Beispiele in der Konsole sind die Beschreibungen von Vorfällen und die Vorschau der Dokumentation beim Erstellen einer Benachrichtigungsrichtlinie.
- Prüfen Sie, ob die Aggregationseinstellungen der Bedingung das Label nicht entfernen. Wenn das Label entfernt wird, ist der Wert des Labels in der Benachrichtigung
null. Weitere Informationen finden Sie unter Variable für ein Messwertlabel ist „null“.
null-Werte
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.KEYundmetric.label.KEYkönnennullWerte haben, wenn Ihre Benachrichtigungsrichtlinie eine achsenübergreifende Aggregation (Reduzierung) verwendet, z. B. die Summe für jede der Zeitachsen, die einem Filter entsprechen. Bei Verwendung einer achsenübergreifenden Aggregation werden alle Labels, die nicht in der Gruppierung verwendet werden, verworfen. Daher werden sie alsnullgerendert, wenn die Variable durch ihren Wert ersetzt wird. Alle Labels werden beibehalten, wenn es keine achsenü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 Aggregation 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.
Variablenauflösung
Variablen in Dokumentationsvorlagen werden nur in den Benachrichtigungen aufgelöst, die über die folgenden Benachrichtigungskanäle gesendet werden:
- E‑Mail
- Google Chat
- Slack
- Pub/Sub, JSON-Schemaversion 1.2
- Webhooks, JSON-Schemaversion 1.2
- Logo: PagerDuty, JSON-Schemaversion 1.2
Kanalsteuerelemente
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. Sie können @ verwenden, um die Benachrichtigung mit einer bestimmten Nutzer-ID zu verknüpfen. Erwähnungen dürfen keine Namen enthalten.
Angenommen, Sie fügen einen solchen String in das Dokumentationsfeld ein:
<@backendoncall> Incident created based on policy ${policy.display_name}
Wenn das Dokumentationsfeld als Teil der Benachrichtigung vom relevanten Slack-Kanal empfangen wird, bewirkt der vorherige String, dass Slack eine zusätzliche Nachricht an die Nutzer-ID backendoncall sendet. Die von Slack an den Nutzer gesendete Nachricht kann relevante Informationen aus der Benachrichtigung enthalten, z. B. „Incident created based on policy High CPU rate of change“ (Vorfall aufgrund der Richtlinie „Hohe CPU-Änderungsrate“ erstellt).
Diese zusätzlichen Optionen sind kanalspezifisch. Weitere Informationen zu den verfügbaren Optionen finden Sie in der Dokumentation des Kanalanbieters.
Beispiel
Das folgende Beispiel zeigt die Console- und Cloud Monitoring API-Versionen der Vorlagendokumentation für eine Benachrichtigungsrichtlinie zur CPU-Auslastung. Google Cloud In diesen Beispielen wird eine E‑Mail für den Benachrichtigungskanaltyp verwendet. Die Dokumentationsvorlagen enthalten mehrere Variablen, um den Vorfall zusammenzufassen und auf die REST-Ressourcen der Benachrichtigungsrichtlinie und der Bedingung zu verweisen.
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 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"
}
]
}
Die folgende Abbildung zeigt, wie diese Vorlage in einer E‑Mail-Benachrichtigung aussieht:
Google Cloud Console
### 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
Die folgende Abbildung zeigt, wie diese Vorlage in einer E‑Mail-Benachrichtigung aussieht:
