Auf dieser Seite wird gezeigt, wie Sie mit der Cloud Monitoring API Benachrichtigungsrichtlinien programmatisch erstellen und verwalten. Außerdem wird die Verwendung der Befehlszeilenschnittstelle des Cloud SDK für die Verwaltung von Benachrichtigungsrichtlinien veranschaulicht.
Sie können viele dieser Aufgaben auch mit der Cloud Monitoring-Konsole ausführen. Unter Benachrichtigungsrichtlinie verwenden finden Sie eine Einführung in das Erstellen und Verwalten von Benachrichtigungsrichtlinien mit der Cloud Monitoring-Konsole.
Hinweis
Bevor Sie Code für die API schreiben, sollten Sie Folgendes tun:
- Machen Sie sich mit den allgemeinen Konzepten und der Terminologie von Benachrichtigungsrichtlinien vertraut. Weitere Informationen finden Sie unter Einführung in Benachrichtigungen.
- Prüfen Sie, ob die Cloud Monitoring API aktiviert ist Weitere Informationen finden Sie unter API aktivieren.
-
So konfigurieren Sie einen Cloud Monitoring-Arbeitsbereich für Ihr Projekt:
- Wählen Sie in der Cloud Console Ihr Google Cloud-Projekt aus.
Zur Cloud Console - Wählen Sie im Navigationsbereich Monitoring aus.
Wenn Sie Cloud Monitoring noch nie verwendet haben, wird beim ersten Zugriff auf Monitoring in der Google Cloud Console automatisch ein Arbeitsbereich erstellt und Ihr Projekt mit diesem Arbeitsbereich verknüpft. Wenn Ihr Projekt nicht mit einem Arbeitsbereich verknüpft ist, wird ein Dialogfeld angezeigt, in dem Sie entweder einen Arbeitsbereich erstellen oder dieses Projekt zu einem vorhandenen Arbeitsbereich hinzufügen können. Wir empfehlen, einen Arbeitsbereich zu erstellen. Klicken Sie nach der Auswahl auf Hinzufügen.
- Wählen Sie in der Cloud Console Ihr Google Cloud-Projekt aus.
- Installieren Sie die Clientbibliotheken für die zu verwendenden Sprachen. Weitere Informationen finden Sie unter Clientbibliotheken. Momentan ist API-Unterstützung für Benachrichtigungen nur für C#, Go, Java, Node.js und Python verfügbar.
Installieren Sie Cloud SDK. Dadurch erhalten Sie Zugriff auf die
gcloud
-Befehlszeilenschnittstelle, von der aus Sie diese Aufgaben ausführen können. Wenn Sie Cloud Shell verwenden, können Sie diese nutzen, statt das Cloud SDK zu installieren.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
.Stellen Sie sicher, dass Sie die entsprechenden Berechtigungen für das Google Cloud-Projekt haben. Weitere Informationen finden Sie unter Berechtigungen.
Informationen zu Benachrichtigungsrichtlinien
Eine Benachrichtigungsrichtlinie wird durch ein Objekt des Typs AlertPolicy
repräsentiert. Sie definiert eine Reihe von Bedingungen, die auf einen potenziell fehlerhaften Systemstatus hinweisen. Benachrichtigungsrichtlinien verweisen auf Benachrichtigungskanäle, mit denen Sie angeben können, wie Sie darüber informiert werden möchten, dass eine Benachrichtigungsrichtlinie ausgelöst wurde.
Jede Benachrichtigungsrichtlinie gehört zu einem einzelnen Arbeitsbereich und jeder Arbeitsbereich kann bis zu 500 Richtlinien enthalten.
Der Arbeitsbereich wird durch seine ID gekennzeichnet, die im Referenzmaterial als "Projekt-ID" bezeichnet wird. In diesen Beispielen lautet die ID des Arbeitsbereichs a-gcp-project
.
Die Ressource AlertPolicy
unterstützt fünf Vorgänge:
- Erstellen neuer Richtlinien
- Löschen vorhandener Richtlinien
- Abrufen bestimmter Richtlinien
- Abrufen aller Richtlinien
- Ändern bestehender Richtlinien
Benachrichtigungsrichtlinien können in JSON oder YAML ausgedrückt werden, mit denen Sie Richtlinien in Dateien aufzeichnen und Dateien zum Sichern und Wiederherstellen von Richtlinien verwenden können. Mit Cloud SDK können Sie Richtlinien aus Dateien in beiden Formaten erstellen. Mit der REST-API können Sie Richtlinien aus JSON-Dateien erstellen. Siehe Beispielrichtlinien für eine Auswahl von Benachrichtigungsrichtlinien im JSON-Format.
In den folgenden Beispielen werden diese grundlegenden Anwendungsfälle anhand der gcloud
-Schnittstelle und der API veranschaulicht. Die API-Beispiele stammen aus einem Beispielprogramm, das die API zum Implementieren eines Sicherungs- und Wiederherstellungssystems für Benachrichtigungsrichtlinien nutzt. Ausführlichere Beispiele werden im Beispiel: Sichern und Wiederherstellen vorgestellt.
Richtlinien erstellen
Verwenden Sie zum Erstellen einer Benachrichtigungsrichtlinie in einem Projekt die Methode alertPolicies.create
.
Erstellen Sie Richtlinien aus JSON- oder YAML-Dateien.
Diese Dateien werden in der gcloud
-Befehlszeile als Argumente akzeptiert. Sie können damit JSON-Dateien programmatisch lesen, in AlertPolicy
-Objekte umwandeln und daraus mit der Methode alertPolicies.create
Richtlinien erstellen.
Die folgenden Beispiele veranschaulichen das Erstellen von Benachrichtigungsrichtlinien.
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 den JSON-Code für eine Richtlinie mit dem Anzeigenamen "High CPU rate of change" (Hohe CPU-Änderungsrate). Diese Richtlinie wird unter Änderungsrichtlinie beschrieben.
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies create
.
C#
Go
Java
Node.js
PHP
Python
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.
Richtlinien abrufen
Eine Liste mit Richtlinien in einem Projekt rufen Sie mit der Methode alertPolicies.list
ab:
Rufen Sie mit dieser Methode alle Richtlinien ab und wenden Sie Maßnahmen auf jede von ihnen an, beispielsweise um sie zu sichern. Diese Methode unterstützt auch die Optionen filter
und orderBy
zum Eingrenzen und Sortieren der Ergebnisse. Weitere Informationen finden Sie unter Sortieren und Filtern.
Wenn Sie eine bestimmte Richtlinie suchen und ihren Namen kennen, können Sie mit der Methode alertPolicies.get
nur diese Richtlinie abrufen. Der Name einer Richtlinie ist der Wert des Felds name
, nicht der displayName
im Objekt AlertPolicy
. Der Name einer Richtlinie hat das Format projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]
, zum Beispiel:
projects/a-gcp-project/alertPolicies/12669073143329903307
gcloud
Listen Sie mit dem Befehl gcloud alpha monitoring
policies list
alle Benachrichtigungsrichtlinien eines Projekts auf:
gcloud alpha monitoring policies list
Bei Erfolg gibt der Befehl list
eine Liste aller Richtlinien des angegebenen Projekts im YAML-Format zurück. Beispiel: Die Richtlinie mit dem Anzeigenamen "High CPU rate of change" (Hohe CPU-Änderungsrate) des Projekts a-gcp-project
wird wie unten dargestellt mit den anderen Richtlinien aufgelistet:
---
combiner: OR
conditions:
- conditionThreshold:
aggregations:
- alignmentPeriod: 900s
perSeriesAligner: ALIGN_PERCENT_CHANGE
comparison: COMPARISON_GT
duration: 180s
filter: metric.type="compute.googleapis.com/instance/cpu/utilization" AND resource.type="gce_instance"
thresholdValue: 0.5
trigger:
count: 1
displayName: CPU usage is increasing at a high rate
name: projects/a-gcp-project/alertPolicies/12669073143329903307/conditions/12669073143329903008
creationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
displayName: High CPU rate of change
enabled: true
mutationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
name: projects/a-gcp-project/alertPolicies/12669073143329903307
---
Wenn Sie nur eine Benachrichtigungsrichtlinie auflisten möchten, verwenden Sie stattdessen gcloud alpha monitoring policies
describe
und geben Sie den Namen der Richtlinie an. Dieser Befehl gibt beispielsweise nur die obige Liste zurück:
gcloud alpha monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307
Weitere Informationen finden Sie in den Referenzen gcloud alpha monitoring policies list
und describe
. Der Befehl describe
entspricht der Methode alertPolicies.get
in der API.
C#
Go
Java
Node.js
PHP
Python
Richtlinien löschen
Löschen Sie eine Richtlinie aus einem Projekt mit der Methode alertPolicies.delete
. Geben Sie den Namen der Benachrichtigungsrichtlinie an, die gelöscht werden soll.
gcloud
Wenn Sie eine Benachrichtigungsrichtlinie löschen möchten, verwenden Sie gcloud alpha monitoring policies
delete
und geben den Namen der zu löschenden Richtlinie an. Der folgende Befehl löscht beispielsweise die Richtlinie "High CPU rate of change" (Hohe CPU-Änderungsrate):
gcloud alpha monitoring policies delete projects/a-gcp-project/alertPolicies/12669073143329903307
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies delete
.
Richtlinien ändern
Ändern Sie mit der Methode alertPolicies.patch
in der REST API eine Benachrichtigungsrichtlinie.
In anderen API-Implementierungen und der gcloud
-Schnittstelle wird dies als update
anstatt patch
bezeichnet.
Ein Aktualisierungsvorgang kann die vorhandene Richtlinie vollständig ersetzen oder eine Teilmenge von Feldern ändern. Bei einem Aktualisierungsvorgang werden ein neues AlertPolicy
-Objekt und optional eine Feldmaske verwendet.
Wenn eine Feldmaske angegeben wird, dann wird jedes in der Feldmaske aufgelistete Feld mit dem Wert in der bereitgestellten Richtlinie aktualisiert. Wenn in der angegebenen Richtlinie ein Feld fehlt, das in der Feldmaske angegeben ist, wird der Wert in diesem Feld gelöscht und auf den Standardwert zurückgesetzt. Nicht in der Maske aufgeführte Felder behalten ihren vorherigen Wert bei.
Wenn keine Feldmaske angegeben ist, wird die vorhandene Richtlinie durch die angegebene ersetzt. Der Name projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]
bleibt jedoch gleich. Alle Bedingungen in der neuen Richtlinie, die Werte vom Typ name
mit einer CONDITION_ID
haben, übernehmen diese Namen. Wenn nicht, werden neue Bedingungs- und Richtliniennamen erstellt.
Wenn Sie Richtlinien über die gcloud
-Befehlszeile aktualisieren, werden die zu aktualisierenden Felder nicht mit einer Feldmaske, sondern mit Befehlszeilen-Flags angegeben.
Details hierzu finden Sie unter gcloud alpha monitoring policies update
.
Richtlinie aktivieren oder deaktivieren
Ändern Sie zum Aktivieren oder Deaktivieren einer Richtlinie den Wert des booleschen Felds enabled
im Objekt AlertPolicy
. Beachten Sie, dass nach dem Aktivieren einer Richtlinie diese auch durch Daten ausgelöst werden kann, die erhoben wurden, während die Richtlinie deaktiviert war.
gcloud
Deaktivieren Sie eine Benachrichtigungsrichtlinie mit dem Befehl gcloud alpha monitoring policies update
und geben Sie das Flag --no-enabled
an. Der folgende Befehl deaktiviert die Benachrichtigungsrichtlinie "High CPU rate of change" (Hohe CPU-Änderungsrate) im Projekt a-gcp-project
:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 --no-enabled
Aktivieren Sie die Richtlinie mit demselben Befehl und geben Sie das Flag --enabled
an.
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies update
. Der Befehl update
entspricht der Methode alertPolicies.patch
in der REST API.
C#
Go
Java
Node.js
PHP
Python
Benachrichtigungskanäle in einer Richtlinie aktualisieren
Sie können auch die Benachrichtigungskanäle aktualisieren, auf die von einer Benachrichtigungsrichtlinie verwiesen wird. Benachrichtigungsrichtlinien beziehen sich namentlich auf Benachrichtigungskanäle. Die Kanäle müssen bereits vorhanden sein, damit sie in einer Benachrichtigungsrichtlinie verwendet werden können.
Benachrichtigungskanäle erstellen und verwalten Sie programmgesteuert mit den Ressourcen NotificationChannel
und NotificationChannelDescriptors
.
In den Beispielen in diesem Abschnitt wird davon ausgegangen, dass die Kanäle bereits vorhanden sind. Es werden daher die entsprechenden APIs verwendet.
Weitere Informationen zu den Objekten der Benachrichtigungskanäle finden Sie unter Verwalten von Kanälen nach API.
gcloud
Die Benachrichtigungskanäle in einer Benachrichtigungsrichtlinie ändern Sie mit dem Befehl gcloud alpha monitoring policies update
. Es gibt Flags, mit denen Sie Benachrichtigungskanäle entfernen, ersetzen und neue Benachrichtigungskanäle hinzufügen können.
Beispielsweise wurde die Richtlinie mit dem Anzeigenamen "High CPU rate of change" (Hohe CPU-Änderungsrate) im Projekt a-gcp-project ohne Benachrichtigungskanäle erstellt.
Fügen Sie mit dem Befehl gcloud alpha monitoring
policies update
dieser Richtlinie einen Benachrichtigungskanal hinzu und geben den hinzuzufügenden Kanal mit dem Flag --add-notification-channels
an:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--add-notification-channels="projects/a-gcp-project/notificationChannels/1355376463305411567"
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies update
. Der Befehl update
entspricht der Methode alertPolicies.patch
in der REST API.
Der hier hinzugefügte Benachrichtigungskanal muss bereits vorhanden sein. Weitere Informationen finden Sie unter Erstellen von Kanälen.
C#
Go
Java
Node.js
PHP
Python
Dokumentation in einer Richtlinie ändern
Eine Richtlinie kann Dokumentation enthalten, die in Vorfällen und Benachrichtigungen enthalten ist, die mit der Richtlinie verknüpft sind. Verwenden Sie dieses Feld, um Informationen einzubeziehen, die es den Beauftragten ermöglichen, das von der Benachrichtigungsrichtlinie angezeigte Problem zu verstehen und zu bearbeiten. Die Dokumentation ist in E-Mail-Benachrichtigungen und Benachrichtigungstypen enthalten, die diese zulassen. Andere Kanaltypen lassen sie möglicherweise weg.
gcloud
Wenn Sie einer Richtlinie eine Dokumentation hinzuzufügen oder eine vorhandene Dokumentation ersetzen möchten, verwenden Sie den Befehlgcloud alpha monitoring policies update
und geben das Flag --documentation-format="text/markdown"
(das einzige unterstützte Format) und wahlweise das Flag --documentation
oder --documentation-from-file
an, um den Wert aus einer Datei zu lesen.
Beispielsweise wurde die Richtlinie mit dem Anzeigenamen "High CPU rate of change" (Hohe CPU-Änderungsrate) im Projekt a-gcp-project ohne eine Dokumentation erstellt.
Mit dem folgenden Befehl wird das Feld documentation
in der angegebenen Richtlinie auf den Inhalt der Datei cpu-usage-doc.md
gesetzt:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--documentation-format="text/markdown" \
--documentation-from-file="cpu-usage-doc.md"
Weitere Informationen finden Sie in der Referenz gcloud alpha monitoring policies update
. Der Befehl update
entspricht der Methode alertPolicies.patch
in der REST API.
Beispiel: Sicherung und Wiederherstellung
Alle gezeigten API-Beispiele stammen aus einer größeren Anwendung, welche die Benachrichtigungsrichtlinien eines Projekts in einer Datei sichern und sie später wiederherstellen kann, falls gewünscht auch in einem anderen Projekt. Wenn sich die für die Sicherung und Wiederherstellung verwendeten Projekte unterscheiden, exportiert und importiert die Anwendung im Grunde Richtlinien von einem Projekt in ein anderes.
Dieser Abschnitt zeigt den Code für das Sichern und Wiederherstellen im Kontext, anstatt als eine Gruppe kleiner, isolierter Auszüge.
Richtlinien sichern
Der Sicherungsvorgang ist leicht zu verstehen. Die Gruppe der Benachrichtigungsrichtlinien und die Gruppe der Benachrichtigungskanäle in jedem Projekt werden gesammelt und in einem externen Speicher in JSON gespeichert.
C#
Go
Java
Node.js
PHP
Python
Gesicherte Richtlinien wiederherstellen
Der Wiederherstellungsprozess ist komplexer als die ursprüngliche Sicherung. Sie können die Richtlinien einerseits in dem Projekt wiederherstellen, in dem Sie sie ursprünglich gesichert haben. Andererseits können Sie sie auch in einem anderen Projekt wiederherstellen, was im Grunde einem Import der Benachrichtigungsrichtlinien entspricht.
Bei der Wiederherstellung in demselben Projekt werden vorhandene Kanäle oder Richtlinien aktualisiert, sofern sie noch vorhanden sind. Ist dies nicht der Fall, werden sie neu erstellt. Schreibgeschützte Felder der gesicherten Richtlinien wie die Datensätze zur Erstellung und Mutation werden gelöscht, bevor Richtlinien und Benachrichtigungen neu erstellt werden.
Sie können eine in einem Projekt gespeicherte Richtlinie zur Erstellung einer neuen oder ähnlichen Richtlinie in einem anderen Projekt verwenden. Allerdings müssen Sie zuvor folgende Änderungen in einer Kopie der gespeicherten Richtlinie vornehmen:
- Entfernen Sie die folgenden Felder aus allen Benachrichtigungskanälen:
name
verificationStatus
- Erstellen Sie die Benachrichtigungskanäle, bevor Sie in den Benachrichtigungsrichtlinien darauf verweisen. Es müssen die neuen Kanalkennzeichnungen verwendet werden.
- Entfernen Sie die folgenden Felder aus allen Benachrichtigungsrichtlinien, die Sie neu erstellen:
name
condition.name
creationRecord
mutationRecord
Wenn die Richtlinie in einem neuen Projekt neu erstellt wird, werden die Namen der Bedingungen in den gesicherten Richtlinien mit den Erstellungs- und Mutationsdatensätzen gelöscht.
Wenn ein Benachrichtigungskanal in einem anderen Projekt neu erstellt wird, erhält er einen anderen Namen. Daher müssen bei der Wiederherstellung die Namen der Kanäle in den gesicherten Benachrichtigungsrichtlinien den neuen Namen zugeordnet werden. Außerdem müssen die alten Namen durch die neuen ersetzt werden.
Neben den Namen der Benachrichtigungskanäle kann beim Erstellen oder Aktualisieren des Kanals auch der Wert des Felds verificationStatus
nicht festgelegt werden. Daher wird als Wert "Sentinel" unspecified
verwendet. Nachdem Kanäle in einem neuen Projekt wiederhergestellt wurden, müssen sie explizit verifiziert werden.
C#
Go
Java
Node.js
PHP
Python
Benachrichtigung und Cloud SDK
Im Cloud SDK ist monitoring
(derzeit in der Alphaphase) die Befehlsgruppe für das Verwalten von Benachrichtigungsrichtlinien und Benachrichtigungskanälen.
Die Gruppe monitoring
ist in der Komponente alpha
verfügbar.
Das heißt, diese Befehle beginnen alle mit:
gcloud alpha monitoring
Prüfen Sie mit dem folgenden Befehl, ob die Komponente alpha
installiert ist:
gcloud components list
Wenn Sie die Komponente alpha
nicht installiert haben, installieren Sie sie mit diesem Befehl:
gcloud components install alpha
Wenn die Komponente alpha
installiert ist, suchen Sie mit dem folgenden Befehl die Gruppe monitoring
:
gcloud alpha monitoring --help
Wenn die Gruppe monitoring
nicht enthalten ist, werden Sie aufgefordert, sie hinzuzufügen:
You do not currently have this command group installed.
[...]
Do you want to continue (Y/n)? y