Auf dieser Seite wird beschrieben, wie Sie die Dokumentation zu Benachrichtigungsrichtlinien konfigurieren können damit Incident-Response-Experten über Benachrichtigungen zur Behebung von Vorfällen.
Struktur der Dokumentation
Die Dokumentation einer Benachrichtigungsrichtlinie besteht aus einem Betreff, und Links. Sie können die Dokumentation in der Google Cloud Console konfigurieren. Cloud Monitoring API und Google Cloud CLI.
Betreffzeilen
Der Betreff Ihrer Dokumentation erscheint im Betreff Ihrer Benachrichtigungen zu Vorfällen im Zusammenhang mit Ihrer Benachrichtigungsrichtlinie erhalten. Die Empfänger von Benachrichtigungen können ihre Benachrichtigungen verwalten und nach Betreff sortieren.
Betreffzeilen dürfen maximal 255 Zeichen lang sein. Wenn Sie in der Tabelle kein Dokumentation, dann bestimmt Cloud Monitoring die Betreffzeile. In Betreffzeilen sind nur Text und Variablen zulässig.
Cloud Monitoring API
Konfigurieren Sie die Betreffzeile der Benachrichtigung mithilfe des Felds „subject
“
der Benachrichtigungsrichtlinie documentation
.
Google Cloud Console
Konfigurieren Sie die Betreffzeile der Benachrichtigung mithilfe der Notification subject line (Betreffzeile der Benachrichtigung) in der Abschnitt Benachrichtigungen und Name auf der Seite Benachrichtigungsrichtlinie erstellen.
Inhalt
Der Inhalt Ihrer Dokumentation ist in der folgenden Benachrichtigung zu sehen. Typen:
- Email (E-Mail) unter der Überschrift Policy Documentation (Richtliniendokumentation)
- Logo: PagerDuty
- Pub/Sub
- Slack
- Webhooks
Wir empfehlen, die Inhalte so zu konfigurieren, Mitarbeiter können Abhilfemaßnahmen und Informationen zum Vorfall in Benachrichtigungen sehen in Bezug auf Ihre Benachrichtigungsrichtlinie. Beispielsweise können Sie die eine Zusammenfassung des Vorfalls und Informationen zu relevanten Ressourcen.
Dokumentationsinhalte unterstützen Nur-Text, Markdown, Variablen und channelspezifische Einstellungen zu implementieren.
Cloud Monitoring API
Dokumentationsinhalt mithilfe des Felds content
konfigurieren
der Benachrichtigungsrichtlinie documentation
.
Google Cloud Console
Konfigurieren Sie den Dokumentationsinhalt mithilfe des Felds Documentation im Abschnitt Benachrichtigungen und Name auf der Seite Benachrichtigungsrichtlinie erstellen.
Links
Sie können Ihrer Dokumentation Links hinzufügen, Auf Ressourcen wie Playbooks, Repositories und Google Cloud-Dashboards zugreifen über eine Benachrichtigung.
Cloud Monitoring API
In der Cloud Monitoring API konfigurierte Dokumentationslinks werden in der folgenden Benachrichtigungstypen:
- E-Mail (unter der Überschrift Quick Links)
- Logo: PagerDuty
- Pub/Sub
- Webhooks
Um eine Verknüpfung zu konfigurieren, fügen Sie ein Link
zum
documentation
Ihrer Benachrichtigungsrichtlinie.
Jeder Link wird durch ein display_name
und ein url
dargestellt. Sie können bis zu
drei Links in Ihrer Dokumentation.
Bei der folgenden Konfiguration wird links
mit einer URL verwendet
um einen Link zu einem Playbook für Vorfälle zu erstellen. Die URL enthält eine Variable,
dass die Empfänger von Benachrichtigungen
auf das richtige Playbook zugreifen können,
überwachte Ressource, in der der Vorfall aufgetreten ist:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Google Cloud Console
In der Google Cloud Console konfigurierte Dokumentationslinks werden mit der den restlichen Dokumentationsinhalt in den folgenden Benachrichtigungstypen verwenden:
- Email (E-Mail) unter der Überschrift Policy Documentation (Richtliniendokumentation)
- Logo: PagerDuty
- Pub/Sub
- Slack
- Webhooks
Sie können Links zu Ihren Dokumentationsinhalten hinzufügen, indem Sie sie einfügen im Feld Documentation (Dokumentation) Ihrer Benachrichtigungsrichtlinie ein. Beispiel: Der Parameter Die folgende Dokumentation enthält eine URL für ein Kunden-Playbook:
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Markdown im Dokumentationsinhalt
Sie können Markdown zur Formatierung Ihrer Dokumentationsinhalte verwenden. In der Dokumentation werden die folgenden Markdown-Tags 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)
. Wir empfehlen jedoch die Verwendung desLink
-Objekt, um Links für Ihre Inhalte zu konfigurieren.
Weitere Informationen zu diesem Tagging finden Sie in der Markdown-Referenz, z. B. in der Markdown-Anleitung.
Variablen in der Dokumentation
Sie können Variablen verwenden, um den Text in Ihrer Dokumentation anzupassen
im Format ${varname}
. Wenn die Dokumentation zusammen mit
eine Benachrichtigung ist, wird der String ${varname}
durch einen Wert ersetzt, der aus dem
entsprechende Google Cloud-Ressource, 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. CPU usage increasing rapidly |
log.extracted_label.KEY |
Der Wert des Labels KEY , extrahiert
aus einem Logeintrag. Nur für logbasierte Benachrichtigungsrichtlinien: für weitere Informationen
Informationen,
Siehe
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 benutzerdefinierten Labels für Ressourcenmetadaten 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 Vorlagen für das Prometheus-Benachrichtigungsfeld Sie können auch |
metric_or_resource.labels |
Diese Variable rendert alle Messwert- und Ressourcenlabelwerte als sortierte Liste von Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Vorlagen des Prometheus-Benachrichtigungsfelds |
metric_or_resource.label.KEY |
Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Vorlagen für das Prometheus-Benachrichtigungsfeld |
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 können folgende Zeichen enthalten: Nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche. |
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 zone
-Labels ersetzt. Die Werte dieser Variablen unterliegen einer Gruppierung. Weitere Informationen finden Sie unter null
-Werte.
2 So rufen Sie den Wert des Labels project_id
für eine
überwachte Ressource in der Benachrichtigungsrichtlinie mit ${resource.project}
.
3 Sie können nicht auf benutzerdefinierte Labels für Ressourcenmetadaten zugreifen,
mit resource.label.KEY.
Verwenden Sie metadata.user_label.KEY
stattdessen.
Verwendungshinweise
- Nur die Variablen in der Tabelle werden unterstützt. Sie können sie nicht zu
komplexere Ausdrücke
wie
${varname1 + varname2}
. - 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 in der Google Cloud Console sehen Sie die Variablen, nicht die Werte. Beispiele in der Konsole sind die Beschreibungen von Vorfällen und die Vorschau der Dokumentation beim Erstellen einer Benachrichtigungsrichtlinie.
- Achten Sie darauf, dass in den Aggregationseinstellungen der Bedingung das Feld
. Wird das Label entfernt, hat der Wert des Labels in der Spalte
Benachrichtigung ist
null
. Weitere Informationen Siehe Variable für ein Messwertlabel ist null.
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
undmetric.label.KEY
könnennull
-Werte, wenn in Ihrer Benachrichtigungsrichtlinie eine reihenübergreifende Aggregation verwendet wird (Reduktion) zu vergleichen, z. B. durch Berechnung der SUM für jedes der die einem Filter entsprechen. Wenn Sie die reihenübergreifende Aggregation verwenden, Alle nicht in der Gruppierung verwendeten Labels werden verworfen und daher alsnull
, wenn die Variable durch ihren Wert ersetzt wird. Alle Labels werden beibehalten, wenn keine reihenübergreifende Aggregation vorhanden ist. Weitere Informationen Siehe 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 gesendet über die folgenden Benachrichtigungskanäle:
- Google Chat
- Slack
- Pub/Sub, JSON-Schemaversion 1.2
- Webhooks, JSON-Schemaversion 1.2
- PagerDuty, JSON-Schemaversion 1.2
Kanaleinstellungen
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 das
an eine bestimmte Nutzer-ID gesendet. Erwähnungen dürfen keine Namen enthalten.
Angenommen, Sie fügen einen String wie diesen in das Dokumentationsfeld ein:
<@backendoncall> Incident created based on policy ${policy.display_name}
Wenn der entsprechende Slack-Kanal das Dokumentationsfeld als Teil des
der Benachrichtigung führt der vorherige String dazu, dass Slack eine
an die Nutzer-ID senden,
backendoncall
Die Nachricht, die von Slack an den Nutzer gesendet wird
relevante Informationen aus der Meldung enthalten könnten; zum Beispiel
„Vorfall erstellt basierend auf der Richtlinie „Hohe CPU-Änderungsrate“.
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 Versionen der Google Cloud Console und der Cloud Monitoring API von Vorlagendokumentation für eine Benachrichtigungsrichtlinie zur CPU-Auslastung. In diesen Beispielen wird eine E-Mail-Adresse als Benachrichtigungskanaltyp verwendet. Die Dokumentationsvorlagen enthalten mehrere Variablen, um den Vorfall zusammenzufassen und um auf die Benachrichtigungsrichtlinie und die REST-Ressourcen für Bedingungen 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 aussieht. Benachrichtigung:
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 aussieht. Benachrichtigung: