Eine Benachrichtigungsrichtlinie wird in der Cloud Monitoring API durch ein Objekt des Typs AlertPolicy
repräsentiert. Sie definiert eine Reihe von Bedingungen, die auf einen potenziell fehlerhaften Systemstatus hinweisen.
In diesem Dokument wird Folgendes beschrieben:
- Darstellung von Benachrichtigungsrichtlinien durch die Monitoring API
- Die Bedingungstypen, die die Monitoring API für Benachrichtigungsrichtlinien.
- So erstellen Sie eine Benachrichtigungsrichtlinie mithilfe der Google Cloud CLI oder Clientbibliotheken.
Struktur einer Benachrichtigungsrichtlinie
Die Struktur AlertPolicy
definiert die Komponenten einer Benachrichtigungsrichtlinie. Wenn Sie eine Richtlinie erstellen, geben Sie Werte für die
folgende AlertPolicy
-Felder:
displayName
: Ein beschreibendes Label für die Richtlinie.documentation
: Wir empfehlen, dieses Feld zu verwenden. um Informationen bereitzustellen, die für Incident-Response-Teams hilfreich sind. Weitere Informationen Siehe Benachrichtigungen mit benutzerdefinierter Dokumentation annotieren.userLabels
: Alle benutzerdefinierten Labels, die der Richtlinie zugeordnet sind. Weitere Informationen zur Verwendung von Labels mit Benachrichtigungen finden Sie unter Vorfälle mit Labels versehen.conditions[]
: Ein Array vonCondition
-Strukturen.combiner
: Ein logischer Operator, der bestimmt, wie mehrere .notificationChannels[]
: ein Array von Ressourcennamen, die jeweils einenNotificationChannel
identifizieren.alertStrategy
: Gibt an, wie schnell Monitoring wird beendet wenn keine Daten eingehen. Dieses Objekt gibt außerdem an, werden wiederholte Benachrichtigungen für messwertbasierte Benachrichtigungsrichtlinien aktiviert, und das Intervall zwischen diesen Benachrichtigungen. Weitere Informationen finden Sie unter Konfigurieren Sie wiederholte Benachrichtigungen für messwertbasierte Benachrichtigungsrichtlinien.
Sie können das Feld severity
auch angeben, wenn Sie die Cloud Monitoring API verwenden
und die Google Cloud Console. In diesem Feld können Sie die Wichtigkeitsstufe
Vorfälle. Wenn Sie keinen Schweregrad angeben,
legt Cloud Monitoring den Schweregrad der Benachrichtigungsrichtlinie auf No Severity
fest.
Je nach den von Ihnen erstellten Bedingungen können Sie weitere Felder verwenden.
Wenn eine Benachrichtigungsrichtlinie eine Bedingung enthält, wird eine Benachrichtigung gesendet, wenn ob die Bedingung erfüllt ist. Informationen zu Benachrichtigungen bei Richtlinien enthalten mehrere Bedingungen, siehe Richtlinien mit mehreren Bedingungen und Anzahl der Benachrichtigungen pro Richtlinie.
Wenn Sie die Benachrichtigungsrichtlinie erstellen oder ändern, legt Monitoring auch andere Felder fest, einschließlich des Felds name
. Der Wert des Felds name
ist der Ressourcenname für die Benachrichtigungsrichtlinie, die die Richtlinie identifiziert. Der Ressourcenname hat das folgende Format:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Bedingungstypen in der API
Die Cloud Monitoring API unterstützt eine Vielzahl von Bedingungstypen in der Struktur Condition
. Es gibt mehrere Bedingungstypen für messwertbasierte Benachrichtigungsrichtlinien und einen für logbasierte Benachrichtigungsrichtlinien. In den folgenden Abschnitten werden die verfügbaren Bedingungstypen beschrieben.
Bedingungen für messwertbasierte Benachrichtigungsrichtlinien
So erstellen Sie eine Benachrichtigungsrichtlinie, die Messwertdaten überwacht, einschließlich logbasierter Daten. können Sie die folgenden Bedingungstypen verwenden:
Filterbasierte Messwertbedingungen
Die Bedingungen MetricAbsence
und MetricThreshold
verwenden Monitoring-Filter, um die zu überwachenden Zeitachsendaten auszuwählen. Die anderen Felder in der Bedingungsstruktur
geben an, wie gefiltert werden soll,
und aggregieren die Daten. Weitere Informationen zu diesen Konzepten finden Sie unter Filtern und Aggregation: Zeitachsen bearbeiten.
Wenn Sie den Bedingungstyp MetricAbsence
verwenden, können Sie eine Bedingung erstellen,
die nur erfüllt ist,
wenn alle Zeitreihen fehlen. Diese Bedingung verwendet
den Parameter aggregations
, um mehrere Zeitreihen zu einer einzigen
Zeitreihe. Weitere Informationen finden Sie unter
Referenz zu MetricAbsence
in der API-Dokumentation
Eine Benachrichtigungsrichtlinie für fehlende Messwerte erfordert, dass einige Daten geschrieben wurden Früher: finden Sie unter Benachrichtigungsrichtlinien für fehlende Messwerte erstellen
Wenn Sie Benachrichtigungen basierend auf einem prognostizierten Wert erhalten möchten, konfigurieren Sie
die Benachrichtigungsrichtlinie
MetricThreshold
-Bedingungstyp und zum Festlegen von forecastOptions
ein. Wann?
nicht festgelegt ist, werden die gemessenen Daten mit einem Schwellenwert verglichen.
Wenn dieses Feld jedoch festgelegt ist, werden die vorhergesagten Daten mit einem
Grenzwert. Weitere Informationen finden Sie unter
Benachrichtigungsrichtlinien für prognostizierte Messwerte erstellen
MQL-basierte Messwertbedingungen
Die Bedingung MonitoringQueryLanguageCondition
verwendet die Monitoring Query Language (MQL), um die zu überwachenden Zeitachsendaten auszuwählen und zu bearbeiten. Sie können Benachrichtigungsrichtlinien erstellen, die Werte mit einem Schwellenwert vergleichen oder auf das Fehlen von Werten mit diesem Bedingungstyp testen.
Wenn Sie eine MonitoringQueryLanguageCondition
-Bedingung verwenden, muss diese die einzige Bedingung in Ihrer Benachrichtigungsrichtlinie sein. Weitere Informationen finden Sie unter Benachrichtigungsrichtlinien mit MQL.
PromQL-basierte Messwertbedingungen
Die Bedingung PrometheusQueryLanguageCondition
verwendet Prometheus Query Language (PromQL)
Abfragen verwenden, um zu überwachende Zeitreihendaten auszuwählen und zu bearbeiten.
Ihre Bedingung kann ein Verhältnis
von Metriken berechnen,
Messwertvergleiche auszuwerten und vieles mehr.
Wenn Sie eine PrometheusQueryLanguageCondition
-Bedingung verwenden, darf dies die einzige sein
Bedingung in Ihrer Benachrichtigungsrichtlinie festlegen. Weitere Informationen finden Sie unter
Benachrichtigungsrichtlinien mit PromQL
Bedingungen für Benachrichtigungen zu Verhältnissen
Sie können Benachrichtigungsrichtlinien mit Messwertschwellen erstellen, um das Verhältnis von zwei Messwerten zu überwachen. Sie können diese Richtlinien entweder mit dem Bedingungstyp MetricThreshold
oder MonitoringQueryLanguageCondition
erstellen.
Sie können MQL auch direkt in der Google Cloud Console verwenden. Über die grafische Benutzeroberfläche zum Erstellen von Schwellenwertbedingungen können Sie keine verhältnisbasierten Bedingungen erstellen oder verwalten.
Wir empfehlen die Verwendung von MQL, um verhältnisbasierte Benachrichtigungsrichtlinien zu erstellen.
Mit MQL können Sie leistungsstärkere und flexiblere Abfragen erstellen, als Sie es mit dem Bedingungstyp MetricTheshold
und Monitoring-Filtern möglich ist.
Mit einer MonitoringQueryLanguageCondition
-Bedingung können Sie beispielsweise das Verhältnis eines absoluten Messwerts zu einem Deltamesswert berechnen. Beispiele finden Sie unter Beispiele für MQL-Benachrichtigungsrichtlinien.
Wenn Sie die Bedingung MetricThreshold
verwenden, müssen Zähler und Nenner des Verhältnisses dieselbe MetricKind
haben.
Eine Liste der Messwerte und ihrer Eigenschaften finden Sie unter Messwertlisten.
Im Allgemeinen ist es am besten, Verhältnisse basierend auf Zeitachsen zu berechnen, die unter Einsatz von Labelwerten für einen einzelnen Messwerttyp erfasst wurden. Ein über zwei berechnetes Verhältnis verschiedenen Messwerttypen aufgrund unterschiedlicher Stichproben Anomalien und Ausrichtungsfenster.
Angenommen, Sie haben zwei verschiedene Messwerttypen, eine RPCs-Gesamtzahl und eine RPC-Fehlerzahl, und Sie möchten das Verhältnis von Fehler- zu Gesamtzahl berechnen. Die fehlgeschlagenen RPCs werden in der Zeitreihe für beide Messwerttypen. Daher besteht die Möglichkeit, dass bei der Abstimmung der Zeit -Serie ist, wird ein fehlgeschlagener RPC nicht im gleichen Ausrichtungsintervall für Zeitreihen. Dies kann folgende Gründe haben:
- Da zwei verschiedene Zeitachsen dasselbe Ereignis aufzeichnen, gibt es zwei unterliegende Zählerwerte, die die Sammlung implementieren. Diese werden nicht atomar aktualisiert.
- Die Abtastraten können abweichen. Wenn die Zeitachsen auf einen gemeinsamen Zeitraum ausgerichtet sind, kann die Anzahl für ein einzelnes Ereignis in angrenzenden Ausrichtungsintervallen für die verschiedenen Messwerte angezeigt werden.
Die unterschiedliche Anzahl der Werte in den entsprechenden Ausrichtungsintervallen kann zu einem unsinnigen error/total
-Verhältniswert führen, z. B. 1/0 oder 2/1.
Bei Verhältnissen größerer Zahlen ist die Wahrscheinlichkeit geringer, dass sie zu unsinnigen Werten führen. Sie können größere Zahlen durch Aggregation erhalten, indem Sie entweder ein Ausrichtungsfenster verwenden das entspricht länger als der Stichprobenzeitraum ist, oder indem Daten für bestimmte Labels. Diese Techniken minimieren den Effekt kleiner Unterschiede in der Anzahl der Punkte in einem gegebenen Intervall. Das heißt, ein Zwei-Punkte-Unterschied ist bei einer erwarteten Anzahl von 3 Punkten in einem Intervall signifikanter als bei einer erwarteten Anzahl von 300.
Wenn Sie integrierte Messwerttypen verwenden, haben Sie möglicherweise keine andere Wahl, als die Verhältnisse zwischen den Messwerttypen zu berechnen, um den von Ihnen benötigten Wert zu erhalten.
Wenn Sie benutzerdefinierte Messwerte entwerfen, die die gleiche Sache – wie RPCs, die den Fehlerstatus zurückgeben – in zwei verschiedenen Messwerten zählen könnten, sollten Sie stattdessen einen einzigen Messwert in Betracht ziehen, der jede Zählung nur einmal enthält. Angenommen, Sie zählen RPCs und möchten das Verhältnis von nicht erfolgreichen RPCs zu allen RPCs verfolgen. Zur Behebung dieses Problems erstellen Sie einen einzelnen Messwerttyp, um RPCs zu zählen, und verwenden ein Label, um den Status des Aufrufs einschließlich des Status „OK“ aufzuzeichnen. Dann wird jeder Statuswert bzw. jeder Fehler oder jedes „OK“ aufgezeichnet, indem für diesen Fall ein einzelner Zähler aktualisiert wird.
Bedingung für logbasierte Benachrichtigungsrichtlinien
Verwenden Sie den Bedingungstyp LogMatch
, um eine logbasierte Benachrichtigungsrichtlinie zu erstellen. Sie werden dann benachrichtigt, wenn eine Nachricht, die Ihrem Filter entspricht, in Ihren Logeinträgen angezeigt wird. Wenn Sie eine LogMatch
-Bedingung verwenden, muss sie die einzige Bedingung in Ihrer Benachrichtigungsrichtlinie sein.
Verwenden Sie den Bedingungstyp LogMatch
nicht in Verbindung mit logbasierten
Messwerte. Benachrichtigungsrichtlinien, die logbasierte Messwerte überwachen, sind messwertbasiert
Richtlinien. Weitere Informationen zur Auswahl
von Benachrichtigungsrichtlinien, die
Logbasierte Messwerte oder Logeinträge überwachen, siehe
Logs überwachen
Die Benachrichtigungsrichtlinien, die in den Beispielen im Das Dokument Benachrichtigungsrichtlinien nach API verwalten ist messwertbasiert. Benachrichtigungen Richtlinien, wobei die Prinzipien für logbasierte Benachrichtigungsrichtlinien dieselben sind. Spezifische Informationen zu logbasierten Benachrichtigungsrichtlinien finden Sie unter Logbasierte Benachrichtigungsrichtlinie mit der Monitoring API erstellen in der Cloud Logging-Dokumentation.
Hinweise
Bevor Sie Code für die API schreiben, sollten Sie Folgendes tun:
- Machen Sie sich mit den allgemeinen Konzepten und der Terminologie von Benachrichtigungen vertraut. Richtlinien Weitere Informationen finden Sie in der Benachrichtigungsübersicht. Informationen.
- Achten Sie darauf, dass die Cloud Monitoring API für die Verwendung aktiviert ist. Siehe Weitere Informationen finden Sie unter API aktivieren.
- Wenn Sie Clientbibliotheken verwenden möchten, installieren Sie die Bibliotheken für den Sprachen, die Sie verwenden möchten, Siehe Clientbibliotheken. Momentan ist API-Unterstützung für Benachrichtigungen nur für C#, Go, Java, Node.js und Python verfügbar.
Wenn Sie die Google Cloud CLI verwenden möchten, installieren Sie sie. Wenn Sie jedoch Cloud Shell verwenden, ist die Google Cloud CLI bereits installiert ist.
Sie finden hier auch Beispiele zur Verwendung der
gcloud
-Schnittstelle. Beachten Sie, dass bei den Beispielen zugcloud
davon ausgegangen wird, dass das aktuelle Projekt bereits mitgcloud config set project [PROJECT_ID]
als Ziel festgelegt wurde. Bei Aufrufen wird daher das explizite Flag--project
ausgelassen. Die ID des aktuellen Projekts in den Beispielen lauteta-gcp-project
.
-
So erhalten Sie die Berechtigungen, die Sie zum Erstellen und Ändern von Benachrichtigungsrichtlinien mithilfe der Cloud Monitoring API benötigen: bitten Sie Ihren Administrator, Ihnen IAM-Rolle Bearbeiter von Monitoring-Benachrichtigungsrichtlinien (
roles/monitoring.alertPolicyEditor
) für Ihr Projekt. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.
Ausführliche Informationen zu IAM-Rollen für Monitoring: Zugriff mit Identity and Access Management steuern
Entwerfen Sie Ihre Anwendung für Einzelthread-Aufrufe der Cloud Monitoring API, den Status einer Benachrichtigungsrichtlinie in einem Google Cloud-Projekt Zum Beispiel können Single-Thread-API-Aufrufe zum Erstellen, Aktualisieren, oder eine Benachrichtigungsrichtlinie löschen.
Benachrichtigungsrichtlinie erstellen
Verwenden Sie zum Erstellen einer Benachrichtigungsrichtlinie in einem Projekt die Methode
alertPolicies.create
-Methode. Informationen zum Aufrufen dieses
sowie die zugehörigen Parameter und Antwortdaten finden Sie auf der Referenzseite.
alertPolicies.create
Erstellen Sie Richtlinien aus JSON- oder YAML-Dateien.
Die Google Cloud CLI akzeptiert diese Dateien als Argumente.
können Sie JSON-Dateien programmatisch lesen und in AlertPolicy
konvertieren
Objekte und erstellen daraus Richtlinien
mit der Methode alertPolicies.create
. Wenn Sie
eine Prometheus-JSON- oder YAML-Konfigurationsdatei
mit einer Benachrichtigungsregel haben,
können Sie die gcloud CLI zu Cloud Monitoring-Benachrichtigungen migrieren.
Richtlinie mit einer PromQL-Bedingung. Weitere Informationen finden Sie unter
Benachrichtigungsregeln und Empfänger von Prometheus migrieren
Jede Benachrichtigungsrichtlinie gehört zu einem Scoping-Projekt eines Messwertbereichs. Jedes Projekt kann bis zu 500 Richtlinien enthalten.
Für API-Aufrufe müssen Sie eine „Projekt-ID“ angeben. Verwenden Sie die ID des Bereichs des Bereichs eines Messwerts als Wert. In diesen Beispielen lautet die ID des Scoping-Projekts eines Messwertbereichs a-gcp-project
.
Die folgenden Beispiele veranschaulichen die Erstellung von Benachrichtigungsrichtlinien. beschreiben wir nicht, wie man eine JSON- oder YAML-Datei erstellt, eine Benachrichtigungsrichtlinie erstellt. Stattdessen wird in den Beispielen davon ausgegangen, dass eine Datei im JSON-Format vorhanden ist, und sie veranschaulichen, wie der API-Aufruf ausgegeben wird. Zum Beispiel JSON-Dateien, Siehe Beispielrichtlinien. Allgemeine Informationen zum Monitoringverhältnis von Messwerten finden Sie unter Verhältnis von Messwerten:
gcloud
Erstellen Sie eine Benachrichtigungsrichtlinie in einem Projekt mit dem Befehl gcloud alpha monitoring
policies create
. Im folgenden Beispiel wird eine Benachrichtigungsrichtlinie in a-gcp-project
mit der Datei rising-cpu-usage.json
erstellt:
gcloud alpha monitoring policies create --policy-from-file="rising-cpu-usage.json"
Bei Erfolg gibt dieser Befehl den Namen der neuen Richtlinie zurück. Beispiel:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
Die Datei rising-cpu-usage.json
enthält die JSON-Datei für eine Richtlinie mit
den Anzeigenamen „High CPU rate of change“ (Hohe CPU-Änderungsrate). Weitere Informationen zu dieser Richtlinie finden Sie unter
Änderungsratenrichtlinie.
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies create
.
C#
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Go
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
PHP
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie zur Authentifizierung bei Monitoring Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Das erstellte AlertPolicy
-Objekt enthält zusätzliche Felder.
Die Richtlinie selbst hat die Felder name
, creationRecord
und mutationRecord
. Darüber hinaus wird für jede Bedingung in der Richtlinie das Feld name
angegeben.
Diese Felder können nicht extern geändert werden, sodass sie beim Erstellen einer Richtlinie nicht festgelegt werden müssen. Sie sind in keinem der JSON-Beispiele zum Erstellen von Richtlinien enthalten. Wenn jedoch aus ihnen erstellte Richtlinien nach der Erstellung abgerufen werden, sind die Felder vorhanden.
Konfigurieren Sie wiederkehrende Benachrichtigungen für messwertbasierte Benachrichtigungsrichtlinien
Standardmäßig sendet eine messwertbasierte Benachrichtigungsrichtlinie eine Benachrichtigung an jede Benachrichtigung wenn ein Vorfall geöffnet wird. Sie können die Standardeinstellung und konfigurieren Sie eine Benachrichtigungsrichtlinie, um Benachrichtigungen erneut an alle oder einige der Benachrichtigungskanäle für Ihre Benachrichtigungsrichtlinie. Diese wiederholten Benachrichtigungen werden bei Vorfällen gesendet mit dem Status „Offen“ oder „Bestätigt“. Das Intervall zwischen diesen Benachrichtigungen muss mindestens 30 Minuten sein und nicht mehr als 24 Stunden, angegeben in Sekunden.
Zur Konfiguration wiederkehrender Benachrichtigungen ergänzen Sie die Konfiguration der Benachrichtigungsrichtlinie
Ein AlertStrategy
-Objekt, das mindestens ein Element enthält
NotificationChannelStrategy
-Objekt.
Ein NotificationChannelStrategy
-Objekt hat zwei Felder:
renotifyInterval
: das Intervall in Sekunden zwischen wiederholten Benachrichtigungen.Wenn Sie den Wert des Felds
renotifyInterval
ändern, wenn wird ein Vorfall für die Benachrichtigungsrichtlinie geöffnet, geschieht Folgendes:- Die Benachrichtigungsrichtlinie sendet eine weitere Benachrichtigung für den Vorfall.
- Die Benachrichtigungsrichtlinie startet den Intervallzeitraum neu.
notificationChannelNames
: ein Array mit Ressourcennamen des Benachrichtigungskanals. Das sind Zeichenfolgen im Formatprojects/PROJECT_ID/notificationChannels/CHANNEL_ID
, wobei CHANNEL_ID ist ein numerischer Wert. Informationen zum Abrufen der Kanal-ID findest du unter Benachrichtigungskanäle in einem Projekt auflisten
Das folgende JSON-Beispiel zeigt eine konfigurierte Benachrichtigungsstrategie zum Senden wiederholter Benachrichtigungen alle 1.800 Sekunden (30 Minuten) auf einen Benachrichtigungskanal:
"alertStrategy": { "notificationChannelStrategy": [ { "notificationChannelNames": [ "projects/PROJECT_ID/notificationChannels/CHANNEL_ID" ], "renotifyInterval": "1800s" } ] }
Wenn Sie wiederholte Benachrichtigungen vorübergehend unterdrücken möchten, können Sie die Schlummerfunktion aktivieren. Bis
wiederholte Benachrichtigungen verhindern, die Benachrichtigungsrichtlinie mit der API bearbeiten und
Entfernen Sie das NotificationChannelStrategy
-Objekt.
Nächste Schritte
- Benachrichtigungsrichtlinien nach API verwalten
- Benachrichtigungskanäle nach API erstellen und verwalten