Benachrichtigungen mit benutzerdefinierter Dokumentation versehen

Mit Benachrichtigungsrichtlinien können Sie benutzerdefinierte Dokumentation hinzufügen, die Cloud Monitoring in Benachrichtigungen einfügt. Diese benutzerdefinierte Dokumentation kann Informationen und Links zur Fehlerbehebung enthalten und den Adressaten helfen, Benachrichtigungen zu bearbeiten. Sie können diese Dokumentation mit Markdown formatieren und Variablen hinzufügen. Cloud Monitoring ersetzt Variablen beim Senden von Benachrichtigungen durch Details zur Benachrichtigungsrichtlinie und zu den überwachten Daten.

Dokumentationsstruktur

Die Dokumentation einer Benachrichtigungsrichtlinie besteht aus einer Betreffzeile, Inhalten und Links. Sie können die Dokumentation in der Google Cloud Console, der Cloud Monitoring API und der Google Cloud CLI konfigurieren.

Betreffzeilen

Die Betreffzeile Ihrer Dokumentation wird in der Betreffzeile von Benachrichtigungen für Benachrichtigungen angezeigt, die sich auf Ihre Benachrichtigungsrichtlinie beziehen. Die Empfänger von Benachrichtigungen können ihre Benachrichtigungen nach Betreffzeile verwalten und sortieren.

Betreffzeilen dürfen maximal 255 Zeichen lang sein. Wenn Sie in Ihrer Dokumentation keine Betreffzeile definieren, wird sie von Cloud Monitoring festgelegt. Betreffzeilen unterstützen Nur-Text und Variablen.

Inhalt

Der Inhalt Ihrer Dokumentation wird in den folgenden Benachrichtigungstypen angezeigt:

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

Wir empfehlen, Ihre Inhalte so zu konfigurieren, dass die Adressaten von Benachrichtigungen Schritte zur Fehlerbehebung und Benachrichtigungsinformationen in Benachrichtigungen zu Ihrer Benachrichtigungsrichtlinie 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:

• Nur-Text
• Variablen
• Kanalspezifische Steuerelemente

• Markdown

Links

Sie können Ihrer Dokumentation Links hinzufügen, damit die Adressaten von Benachrichtigungen über eine Benachrichtigung auf Ressourcen wie Playbooks, Repositories und Dashboards Google Cloud zugreifen können.

Mit der Cloud Monitoring API können Sie ein Objekt definieren, das die wichtigsten Links für die Adressaten 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.

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

### Troubleshooting and Debug References

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

Markdown in Dokumentationsinhalten

Sie können Markdown verwenden, um Ihre Dokumentationsinhalte zu 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 Link Objekt 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 aus der entsprechenden Google Cloud Ressource ersetzt, wie in der folgenden Tabelle beschrieben.

¹ 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.
² Verwenden Sie ${resource.project}, um den Wert des Labels project_id für eine überwachte Ressource in der Benachrichtigungsrichtlinie abzurufen.
³ Sie können nicht mit 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 kombinieren, z. B. ${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.
• In Benachrichtigungsrichtlinien werden immer Variablenstrings wie ${varname} angezeigt.
• Bei einigen Benachrichtigungskanälen ersetzt Cloud Monitoring Variablenstrings wie ${varname} durch die entsprechenden Werte. Weitere Informationen finden Sie unter Variablenauflösung.
• Wenn in der Google Cloud Console die Detailansicht einer Benachrichtigung angezeigt wird, werden Variablenstrings wie ${varname} in der Regel durch die entsprechenden Werte ersetzt.
• 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 bei der Zeitreihenabfrage keine Werte zurückgegeben werden.

• Die resource.label.KEY und metric.label.KEY Variablen können null Werte haben, wenn in Ihrer Benachrichtigungsrichtlinie eine achsenübergreifende Aggregation (Reduzierung) verwendet wird, z. B. die Berechnung der SUMME für alle Zeitreihen, die einem Filter entsprechen. Bei der achsenübergreifenden Aggregation werden alle Labels, die nicht in der Gruppierung verwendet werden, entfernt und daher als null gerendert, wenn die Variable durch ihren Wert ersetzt wird. Alle Labels bleiben erhalten, wenn keine achsenü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.

Variablenauflö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
  • Logo: PagerDuty, JSON-Schemaversion 1.2
• Detailansicht der Benachrichtigung in der Google Cloud Console.

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

<@backendoncall> Alert created based on policy ${policy.display_name}

Wenn das Dokumentationsfeld als Teil der Benachrichtigung vom entsprechenden Slack-Kanal empfangen wird, sendet Slack aufgrund des vorherigen Strings eine zusätzliche Nachricht an die Nutzer-ID backendoncall. Die von Slack an den Nutzer gesendete Nachricht kann relevante Informationen aus der Benachrichtigung enthalten, z. B. „Benachrichtigung 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

Das folgende Beispiel zeigt Google Cloud die Console- und Cloud Monitoring API-Versionen der Vorlagendokumentation für eine Benachrichtigungsrichtlinie zur CPU-Auslastung. In diesen Beispielen wird eine E-Mail für den Benachrichtigungskanaltyp verwendet. Die Dokumentationsvorlagen enthalten mehrere Variablen, um die Benachrichtigung zusammenzufassen und auf die REST-Ressourcen der Benachrichtigungsrichtlinie und der Bedingung zu verweisen.

  "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"
      }
    ]
  }

### 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