Diese Seite wurde von der Cloud Translation API übersetzt.

Benachrichtigungen mit benutzerdefinierter Dokumentation versehen

Auf dieser Seite wird beschrieben, wie Sie die Dokumentation Ihrer Benachrichtigungsrichtlinie so konfigurieren, dass Benachrichtigungen Ressourcen und zusätzliche Informationen zur Behebung von Vorfällen enthalten.

Dokumentationsstruktur

Die Dokumentation einer Benachrichtigungsrichtlinie besteht aus einem Thema, Inhalten 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 angezeigt, die mit Ihrer Benachrichtigungsrichtlinie zusammenhängen. Benachrichtigungsempfänger können ihre Benachrichtigungen nach Betreff verwalten und sortieren.

Betreffzeilen sind auf 255 Zeichen begrenzt. Wenn Sie in Ihrer Dokumentation kein Betreff angeben, wird die Betreffzeile von Cloud Monitoring festgelegt. Betreffzeilen unterstützen Nur-Text und Variablen.

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 des Felds 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, unter der Überschrift Richtliniendokumentation
Logo: PagerDuty
Pub/Sub
Slack
Webhooks

Wir empfehlen, Ihre Inhalte so zu konfigurieren, dass Personen, die auf Vorfälle reagieren, in Benachrichtigungen im Zusammenhang mit Ihrer Benachrichtigungsrichtlinie Maßnahmen zur Behebung und Informationen zum Vorfall sehen können. Sie können die Dokumentation beispielsweise so konfigurieren, dass sie eine Zusammenfassung des Vorfalls und Informationen zu relevanten Ressourcen enthält.

Für Dokumentationsinhalte wird Folgendes unterstützt:

Nur Text
Variablen
Kanalspezifische Einstellungen
Markdown in Benachrichtigungskanälen, die nicht Slack sind

Cloud Monitoring API

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

Google Cloud Console

Konfigurieren Sie den Dokumentationsinhalt mithilfe des Felds Documentation (Dokumentation) im Abschnitt Notifications and name (Benachrichtigungen und Name) der Seite Create alerting policy (Benachrichtigungsrichtlinie erstellen).

Links

Sie können Ihrer Dokumentation Links hinzufügen, damit Einsatzteams ü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 Direktlinks
Logo: PagerDuty
Pub/Sub
Webhooks

Wenn Sie einen Link konfigurieren möchten, fügen Sie der documentation Ihrer Benachrichtigungsrichtlinie ein Link hinzu. Jeder Link wird durch ein display_name und ein url dargestellt. Sie können bis zu drei Links in Ihrer Dokumentation haben.

In der folgenden Konfiguration wird links mit einer URL verwendet, um eine Verknüpfung zu einem Incident-Playbook zu erstellen. Die URL enthält eine Variable, damit die Benachrichtigungsempfänger je nach überwachter Ressource, an 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 Rest Ihrer Dokumentationsinhalte in den folgenden Benachrichtigungstypen angezeigt:

E-Mail, unter der Überschrift Richtliniendokumentation
Logo: PagerDuty
Pub/Sub
Slack
Webhooks

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

### Troubleshooting and Debug References

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

Markdown in Dokumentationsinhalten

Sie können den Inhalt Ihrer Dokumentation mit Markdown formatieren. Für Dokumentationsinhalte 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). Wir empfehlen jedoch, das Objekt Link zu verwenden, 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 den Text in Ihrer Dokumentation mit Variablen der Form ${varname} anpassen. 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`
`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`.¹
`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`.¹ 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 den Benachrichtigungen von Monitoring nicht berücksichtigt. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Benachrichtigungsfelder `{{$value}}` und `{{humanize $value}}` in der Konfiguration 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.label.metadata_system_VALUE`	Verweist auf ein PromQL-Metadatensystemlabel, wobei `VALUE` der spezifische Labelname ist, z. B. `region` oder `version`. Beispiel: `${metric.label.metadata_system_version}`.
`metric.label.metadata_user_VALUE`	Verweist auf ein PromQL-Metadatennutzerlabel, wobei `VALUE` der spezifische Labelname ist, z. B. `region` oder `name`. Beispiel: `${metric.label.metadata_user_name}`.
`metric_or_resource.labels`	Diese Variable gibt alle Messwert- und Ressourcenlabelwerte als sortierte Liste von `key-value`-Paaren aus. Wenn ein Messwertlabel und ein Ressourcenlabel denselben Namen haben, wird nur das Messwertlabel gerendert. Wenn Sie eine Prometheus-Benachrichtigungsregel migrieren, werden die Prometheus-Benachrichtigungsfelder `{{$labels}}` und `{{humanize $labels}}` in der Konfigurationsdokumentation 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-Benachrichtigungsfelder `{{$labels.KEY}}` und `{{humanize $labels.KEY}}` in der 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`.¹ 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.

¹ 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 mit der Benachrichtigungsrichtlinie überwachte Ressource abzurufen.
³ Sie können nicht auf benutzerdefinierte Metadatenlabels von Ressourcen zugreifen, indem Sie resource.label.KEY. verwenden. 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 in der Google Cloud Console die Dokumentation angezeigt wird, sehen Sie die Variablen und 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 durch die Aggregationseinstellungen der Bedingung nicht 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 Ihre Benachrichtigungsrichtlinie eine serverbasierte Aggregation (Reduzierung) verwendet, 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 dargestellt. Alle Labels werden beibehalten, wenn es keine achsenübergreifende Zusammenfassung 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 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
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 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, löst der vorherige String aus, 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“ (Problem 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 Google Cloud Console- und Cloud Monitoring API-Versionen der Vorlagendokumentation für eine Benachrichtigungsrichtlinie für die CPU-Auslastung. In diesen Beispielen wird eine E-Mail für den 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:

Beispiel für die Darstellung von Dokumenten in einer Benachrichtigung Links werden im Bereich „Direktlinks“ 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 angezeigt wird:

Beispiel für die Darstellung von Dokumenten in einer Benachrichtigung Die Links werden unter der Überschrift „Referenzen zur Fehlerbehebung und zum Debuggen“ angezeigt.

Benachrichtigungen mit benutzerdefinierter Dokumentation versehen

Dokumentationsstruktur

Betreffzeilen

Cloud Monitoring API

Google Cloud Console

Inhalt

Cloud Monitoring API

Google Cloud Console

Links

Cloud Monitoring API

Google Cloud Console

Markdown in Dokumentationsinhalten

Variablen in der Dokumentation

Verwendungshinweise

null values

Variable Auflösung

Kanaleinstellungen

Beispiel

Cloud Monitoring API

Google Cloud Console

`null` values