Benachrichtigungen mit benutzerdefinierter Dokumentation versehen

Auf dieser Seite wird beschrieben, wie Sie die Dokumentation Ihrer Benachrichtigungsrichtlinie so konfigurieren, dass Benachrichtigungen den Reaktionspersonen Ressourcen und zusätzliche Informationen zur Behebung von Benachrichtigungen 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 -Konsole, der Cloud Monitoring API und der Google Cloud CLI konfigurieren.

Betreffzeilen

Der Betreff Ihrer Dokumentation wird im Betreff von Benachrichtigungen für Benachrichtigungen angezeigt, die sich auf Ihre Benachrichtigungsrichtlinie beziehen. Benachrichtigungsempfänger können ihre Benachrichtigungen nach Thema 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 über das Feld Betreffzeile der Benachrichtigung im Bereich Benachrichtigungen und Name auf der Seite Benachrichtigungsrichtlinie erstellen.

Inhalt

Der Inhalt Ihrer Dokumentation wird in den folgenden Benachrichtigungstypen angezeigt:

  • E-Mail im Abschnitt Richtliniendokumentation
  • Logo: PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Wir empfehlen, Ihre Inhalte so zu konfigurieren, dass Reaktionskräfte auf Benachrichtigungen im Zusammenhang mit Ihrer Benachrichtigungsrichtlinie Schritte zur Fehlerbehebung und Benachrichtigungsinformationen sehen können. Sie können die Dokumentation beispielsweise so konfigurieren, dass sie eine Zusammenfassung der Benachrichtigung und Informationen zu relevanten Ressourcen enthält.

Dokumentationsinhalte unterstützen Folgendes:

Cloud Monitoring API

Konfigurieren Sie Dokumentationsinhalte mit dem Feld content der Benachrichtigungsrichtlinie documentation.

Google Cloud Console

Konfigurieren Sie die Dokumentationsinhalte über das Feld Dokumentation im Abschnitt Benachrichtigungen und Name auf der Seite Benachrichtigungsrichtlinie erstellen.

Sie können Links zu Ihrer Dokumentation hinzufügen, damit Reaktionsverantwortliche für Benachrichtigungen ü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 Reaktionsverantwortliche enthält. In der Google Cloud -Konsole gibt es zwar kein Feld speziell für Links, Sie können aber einen Abschnitt für Links in den Text Ihrer Dokumentation einfügen.

Cloud Monitoring API

Sie können Links zu Ihrer Dokumentation 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 einem url. Sie können bis zu drei Links in Ihre Dokumentation einfügen.

Die folgende Konfiguration zeigt das Feld links mit einem Link-Objekt, das eine URL zu einem Alert-Playbook darstellt. Die URL enthält eine Variable, damit die Empfänger der Benachrichtigung auf das richtige Playbook zugreifen können, basierend auf der überwachten Ressource, in der die Benachrichtigung ausgelöst wurde:

"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 Abschnitt Quick Links (Schnellzugriff)
  • Logo: PagerDuty
  • Pub/Sub
  • Webhooks

Google Cloud Console

Sie können Links zu Ihrer Dokumentation hinzufügen, indem Sie sie in das Feld Dokumentation Ihrer Benachrichtigungsrichtlinie einfügen. In der folgenden Dokumentation wird beispielsweise eine URL für ein Kunden-Playbook aufgeführt:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

Dokumentationslinks, die über die Google Cloud Console hinzugefügt werden, werden zusammen mit den restlichen Dokumentationsinhalten in den folgenden Benachrichtigungstypen angezeigt:

  • E-Mail im Abschnitt Richtliniendokumentation
  • Logo: PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Markdown in Dokumentationsinhalten

Sie können die Inhalte Ihrer Dokumentation mit Markdown formatieren. Dokumentationsinhalte unterstützen die folgende Teilmenge von Markdown-Tags:

  • 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, die Cloud Monitoring API zu verwenden und das 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 in 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. CPU usage increasing rapidly

Bei logbasierten Benachrichtigungsrichtlinien, die Sie mit dem Log-Explorer erstellen, ist der Wert dieses Felds "Log match condition". Wenn Sie den Wert dieses Felds anpassen möchten, verwenden Sie die Cloud Monitoring API.
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 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, wird das Label in Benachrichtigungen nicht berücksichtigt.

Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Benachrichtigungsfeldvorlagen {{$value}} und {{humanize $value}} in der Dokumentationskonfiguration der Benachrichtigungsrichtlinie als ${metric.label.value} angezeigt. In diesem Fall enthält ${metric.label.value} den Auslöserwert der Prometheus-Benachrichtigungsregel.

Sie können ${metric.label.value} auch verwenden, wenn Sie PromQL-Abfragen in Google Clouderstellen.
metric.label.metadata_system_VALUE

Verweist auf ein PromQL-Metadatensystemlabel, wobei VALUE der spezifische Labelname ist, z. B. region oder version.

Beispiel für die Verwendung: ${metric.label.metadata_system_version}.
metric.label.metadata_user_VALUE

Verweist auf ein PromQL-Metadaten-Nutzerlabel, wobei VALUE der spezifische Labelname ist, z. B. region oder name.

Beispiel für die Verwendung: ${metric.label.metadata_user_name}.
metric_or_resource.labels

Mit dieser Variablen werden alle Messwert- und Ressourcenlabelwerte als sortierte Liste von key-value-Paaren gerendert. 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 Dokumentationskonfiguration 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 Dokumentation zur Konfiguration 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
Die mit dem Typ der überwachten Ressource verknüpften Labels finden Sie in der 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 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 über 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.
  • In Benachrichtigungsrichtlinien werden immer Variablenstrings wie ${varname} angezeigt.
  • Bei einigen Benachrichtigungschannels ersetzt Cloud Monitoring Variablenstrings wie ${varname} durch die entsprechenden Werte. Weitere Informationen finden Sie unter Variablenauflösung.
  • Wenn in der Google Cloud -Konsole die Detailansicht einer Benachrichtigung angezeigt wird, werden normalerweise Variablenstrings wie ${varname} durch die entsprechenden Werte ersetzt.
  • Prüfen Sie, ob das Label durch die Aggregationseinstellungen der Bedingung entfernt wird. 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 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 in Ihrer Benachrichtigungsrichtlinie eine achsenübergreifende Aggregation (Reduzierung) verwendet wird, z. B. die Summe für jede der Zeitachsen, die einem Filter entsprechen. Bei Verwendung einer achsenübergreifenden Zusammenfassung werden alle nicht in der Gruppierung berücksichtigten Labels verworfen. Wenn die Variable durch ihren Wert ersetzt wird, werden sie daher als null gerendert. Alle Labels werden beibehalten, wenn keine serienübergreifende Aggregation erfolgt. 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 in den folgenden Kontexten aufgelöst:

  • Benachrichtigungen, die über die folgenden Benachrichtigungskanäle gesendet werden:
    • E-Mail
    • Google Chat
    • Slack
    • Pub/Sub, JSON-Schemaversion 1.2
    • Webhooks, JSON-Schemaversion 1.2
    • PagerDuty, JSON-Schemaversion 1.2
  • Die Ansicht mit den Benachrichtigungsdetails in der Google Cloud -Konsole.

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 solchen String in das Dokumentationsfeld ein:

<@backendoncall> Alert 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. „Alert created based on policy High CPU rate of change“ (Warnung basierend auf 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

Im folgenden Beispiel sehen Sie Google Cloud die Konsolen- und Cloud Monitoring API-Versionen der Vorlagendokumentation für eine Benachrichtigungsrichtlinie zur CPU-Auslastung. In diesen Beispielen wird eine E-Mail-Adresse für den notification channel type (Typ des Benachrichtigungskanals) verwendet. Die Dokumentationsvorlagen enthalten mehrere Variablen, mit denen die Benachrichtigung zusammengefasst und auf die REST-Ressourcen für Benachrichtigungsrichtlinie und Bedingung verwiesen werden kann.

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:

Beispiel dafür, wie die Dokumentation in einer Benachrichtigung dargestellt wird Links werden im Abschnitt „Quick Links“ angezeigt.

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:

Beispiel dafür, wie die Dokumentation in einer Benachrichtigung dargestellt wird Links werden unter der Überschrift „Referenzen zur Fehlerbehebung und zum Debugging“ angezeigt.