Benachrichtigungen mit benutzerdefinierter Dokumentation annotieren

Auf dieser Seite wird beschrieben, wie Sie die Dokumentation Ihrer Benachrichtigungsrichtlinie so konfigurieren können, dass Incident-Response-Experten Ressourcen und zusätzliche Informationen zur Behebung von Vorfällen bereitstellen.

Struktur der Dokumentation

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 zu Vorfällen im Zusammenhang mit Ihrer Benachrichtigungsrichtlinie angezeigt. 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 Ihrer Dokumentation kein Thema definieren, 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. Verwenden Sie dazu auf der Seite Benachrichtigungsrichtlinie erstellen im Abschnitt Benachrichtigungen und Name das Feld Benachrichtigungsbetreff.

Inhalt

Der Inhalt Ihrer Dokumentation wird in den folgenden Benachrichtigungstypen angezeigt:

• Email (E-Mail) unter der Überschrift Policy Documentation (Richtliniendokumentation)
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Wir empfehlen, Ihre Inhalte so zu konfigurieren, dass Mitarbeiter, die auf Vorfälle reagieren, Abhilfemaßnahmen und Informationen zum Vorfall in Benachrichtigungen im Zusammenhang mit Ihrer Benachrichtigungsrichtlinie sehen können. Beispielsweise können Sie die Dokumentation so konfigurieren, dass sie eine Zusammenfassung des Vorfalls und Informationen über relevante Ressourcen enthält.

Dokumentationsinhalte unterstützen Nur-Text, Markdown, Variablen und kanalspezifische Steuerelemente.

Cloud Monitoring API

Konfigurieren Sie den Dokumentationsinhalt mithilfe des Felds content der Benachrichtigungsrichtlinie documentation.

Google Cloud Console

Konfigurieren Sie den Dokumentationsinhalt. Verwenden Sie dazu auf der Seite Benachrichtigungsrichtlinie erstellen im Abschnitt Benachrichtigungen und Name das Feld Dokumentation.

Links

Sie können Ihrer Dokumentation Links hinzufügen, damit Incident-Response-Experten über eine Benachrichtigung auf Ressourcen wie Playbooks, Repositories und Google Cloud-Dashboards zugreifen können.

Cloud Monitoring API

In der Cloud Monitoring API konfigurierte Dokumentationslinks werden in den folgenden Benachrichtigungstypen angezeigt:

• E-Mail (unter der Überschrift Quick Links)
• PagerDuty
• Pub/Sub
• Webhooks

Zum Konfigurieren eines Links fügen Sie dem documentation Ihrer Benachrichtigungsrichtlinie ein Link hinzu. Jeder Link wird durch ein display_name und ein url dargestellt. Ihre Dokumentation kann bis zu drei Links enthalten.

Bei der folgenden Konfiguration wird links mit einer URL verwendet, um einen Link zu einem Vorfalls-Playbook zu erstellen. Die URL enthält eine Variable, sodass die Empfänger von Benachrichtigungen basierend auf der überwachten Ressource, in der der Vorfall aufgetreten ist, auf das richtige Playbook zugreifen können:

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

Google Cloud Console

In der Google Cloud Console konfigurierte Dokumentationslinks werden zusammen mit dem restlichen Dokumentationsinhalt in den folgenden Benachrichtigungstypen angezeigt:

• Email (E-Mail) unter der Überschrift Policy Documentation (Richtliniendokumentation)
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Sie können Links zu Ihrem Dokumentationsinhalt hinzufügen, indem Sie sie in das Feld Documentation Ihrer Benachrichtigungsrichtlinie aufnehmen. 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}

Hinweis: Die Google Cloud Console unterstützt nicht die Konfiguration des Links-Objekts für Benachrichtigungsrichtlinien.

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, Links für deine Inhalte mit dem Objekt Link 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 im Format ${varname} verwenden. Wenn die Dokumentation mit einer Benachrichtigung gesendet wird, wird der String ${varname} durch einen Wert ersetzt, der aus der entsprechenden Google Cloud-Ressource stammt. Dies ist 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. 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 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 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, lässt Monitoring das Label in Benachrichtigungen weg. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Benachrichtigungsfeldvorlagen {{$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 auch ${metric.label.VALUE} 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 Prometheus-Benachrichtigungsfeldvorlagen {{$labels}} und {{humanize $labels}} in der Konfiguration 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 in der Benachrichtigungsrichtlinie überwachte Ressource abzurufen.
³ Mit resource.label.KEY. können Sie nicht auf benutzerdefinierte Labels für Ressourcenmetadaten 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 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 das Label nicht aus den Aggregationseinstellungen der Bedingung 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.

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 achsenübergreifende Aggregation (Reduktion) verwendet, z. B. wenn die SUM für jede Zeitachse berechnet wird, die einem Filter entspricht. Bei Verwendung der reihenübergreifenden Aggregation werden alle Labels, die nicht in der Gruppierung verwendet werden, verworfen. Daher werden sie als null gerendert, wenn die Variable durch ihren Wert ersetzt wird. Wenn keine reihenübergreifende Aggregation vorhanden ist, werden alle Labels beibehalten. 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 mit den folgenden Benachrichtigungskanälen gesendet werden:

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

Hinweis: Variablen werden nicht aufgelöst, aber in anderen Kontexten in Benachrichtigungen, die über andere Benachrichtigungskanäle gesendet werden, als Strings wie ${varname} angezeigt.

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 die Benachrichtigung mit einer bestimmten Nutzer-ID zu verknüpfen. 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 relevante Slack-Kanal das Dokumentationsfeld als Teil der Benachrichtigung empfängt, führt der vorherige String dazu, 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. „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 Versionen der Google Cloud Console und der Cloud Monitoring API der 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 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-Benachrichtigung angezeigt wird:

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 angezeigt wird: