In diesem Dokument wird beschrieben, wie Sie mit der Google Cloud CLI oder der Cloud Monitoring API den Messwertbereich eines Google Cloud-Projekts konfigurieren. Diese Seite richtet sich an Entwickler und Systemadministratoren.
Die Befehle auf dieser Seite beziehen sich auf einen „Ressourcencontainer“. Ein Ressourcencontainer kann eine Organisation, ein Ordner oder ein Projekt sein. Mit den auf dieser Seite beschriebenen Befehlen werden jedoch nur Google Cloud-Projekte unterstützt.
Hinweise
Wenn Sie mit den Begriffen Messwertumfang und den Umfang festlegendes Projekt nicht vertraut sind, lesen Sie den Abschnitt Messwertbereiche.
Achten Sie darauf, dass Ihre IAM-Rollen (Identity and Access Management) für das Projektumfang festlegen und für jedes Projekt, das Sie als überwachtes Projekt hinzufügen möchten, alle Berechtigungen der Rolle „Monitoring-Administrator“ (
roles/monitoring.admin
) enthalten. Weitere Informationen finden Sie unter Konfigurationen des Messwertbereichs.Die Messwertbereichsmethoden der Cloud Monitoring API, die Informationen abrufen, sind synchron. APIs, die den Zustand ändern, sind jedoch asynchron. Die Google Cloud CLI-Befehle werden blockiert, bis der asynchrone Vorgang abgeschlossen ist. Informationen dazu, wie Sie feststellen, wann eine asynchrone API-Methode abgeschlossen ist und wie ihr Status ermittelt wird, finden Sie unter Asynchrone API-Methoden.
Wenn Sie die Cloud Monitoring API mit
curl
aufrufen oder die Beispiele auf dieser Seite verwenden möchten, führen Sie die Schritte zur Einrichtung descurl
-Befehls aus.
Alle Messwertbereiche auflisten, die ein Projekt enthalten
gcloud
Führen Sie den Befehl gcloud beta monitoring metrics-scopes list
aus, um eine Liste der Messwertbereiche abzurufen, in denen die Messwerte für einen Ressourcencontainer wie ein Google Cloud-Projekt angezeigt werden können:
gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME
Geben Sie vor dem Ausführen des Befehls die ID des Ressourcencontainers in die Variable MONITORED_RESOURCE_CONTAINER_NAME ein.
Wenn der Ressourcencontainer ein Google Cloud-Projekt ist, geben Sie projects/PROJECT_ID_OR_NUMBER
ein.
Führen Sie beispielsweise den folgenden Befehl aus, um die Messwertbereiche aufzulisten, die das Projekt my-project
enthalten:
gcloud beta monitoring metrics-scopes list projects/my-project
Die folgende Antwort gibt an, dass das Projekt my-project
in zwei Messwertbereichen enthalten ist:
metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
name: locations/global/metricsScopes/9876543210
updateTime: '2021-04-13T15:37:27.284239Z'
Führen Sie den Befehl gcloud beta monitoring metrics-scopes describe
aus, um detaillierte Informationen zu einem Messwertbereich abzurufen.
curl
Wenn Sie eine Liste der Messwertbereiche abrufen möchten, die die Messwerte für ein Projekt aufrufen können, senden Sie eine GET
-Anfrage an den Endpunkt locations.global.metricsScopes.listMetricsScopesByMonitoredProject
und fügen Sie den Abfrage-Parameter ein, der das Projekt angibt.
curl -H "Authorization: Bearer ${TOKEN}" \ https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}
Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort ein Array von MetricsScope
-Objekten.
Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des den Bereich festlegenden Projekts geschrieben wird. Damit diese Aktionen im Audit-Log aufgezeichnet werden, aktivieren Sie Datenlesevorgänge für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.
Details zu einem Messwertbereich abrufen
gcloud
Führen Sie den Befehl gcloud beta monitoring metrics-scopes describe
aus, um detaillierte Informationen zu einem Messwertbereich abzurufen:
gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID
Geben Sie, bevor Sie den Befehl ausführen, den voll qualifizierten Namen eines Messwertbereichs in die Variable METRICS_SCOPE_ID ein. Im Folgenden finden Sie ein Beispiel für einen voll qualifizierten Namen:
locations/global/metricsScopes/012345012345
Im Folgenden finden Sie ein Beispiel für eine Antwort. In diesem Beispiel umfasst der Messwertbereich ein Projekt und die ID des Messwertbereichs und des Projekts sind identisch:
createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'
Führen Sie den Befehl gcloud projects list
aus und filtern Sie nach der Projekt-ID, um das Google Cloud-Projekt anhand seiner ID zu identifizieren. Führen Sie beispielsweise den folgenden Befehl aus, um den Namen für das Projekt 012345012345
abzurufen:
gcloud projects list --filter="012345012345" -format="value(NAME)"
curl
Wenn Sie Informationen zu einem Messwertbereich abrufen möchten, senden Sie eine GET
-Anfrage an den Endpunkt locations.global.metricsScopes.get
:
curl -H "Authorization: Bearer ${TOKEN}" \ https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}
Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort ein MetricsScope
-Objekt.
Diese Methode führt nicht dazu, dass ein Eintrag in die Audit-Logs des den Bereich festlegenden Projekts geschrieben wird. Damit diese Aktionen im Audit-Log aufgezeichnet werden, aktivieren Sie Datenlesevorgänge für die Cloud Resource Manager API. Weitere Informationen finden Sie unter Audit-Logs zum Datenzugriff konfigurieren.
Projekt einem Messwertbereich hinzufügen
gcloud
Wenn Sie einem Messwertbereich einen Ressourcencontainer wie ein Google Cloud-Projekt hinzufügen möchten, führen Sie den Befehl gcloud beta monitoring metrics-scopes create
aus:
gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER
Führen Sie vor dem Ausführen des vorherigen Befehls die folgenden Schritte aus:
Geben Sie den Namen oder die ID des Google Cloud-Projekts ein, dessen Messwertbereich geändert werden soll, in die Variable SCOPING_PROJECT_ID_OR_NUMBER.
Geben Sie die ID Ihres Ressourcencontainers in die Variable MONITORED_RESOURCE_CONTAINER_NAME ein. Wenn der Ressourcencontainer ein Google Cloud-Projekt ist, geben Sie
projects/PROJECT_ID_OR_NUMBER
ein.
Mit dem folgenden Befehl wird beispielsweise das Projekt my-monitored-project
dem Messwertbereich des Projekts my-staging-projects
hinzugefügt:
gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects
Die Antwort auf den vorherigen Befehl bestätigt, dass der Befehl erfolgreich abgeschlossen wurde:
Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].
curl
Senden Sie eine POST
-Anfrage an den Endpunkt locations.global.metricsScopes.projects.create
, um ein Google Cloud-Projekt zu einem Messwertbereich hinzuzufügen. Im folgenden Beispiel wird das durch die Umgebungsvariable MONITORED_PROJECT_ID_OR_NUMBER
identifizierte Projekt als überwachtes Projekt hinzugefügt:
curl -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" -X POST \ -d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \ https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects
Die Antwort dieser asynchronen Methode ist ein Operation
-Objekt.
Anwendungen, die diese Methode aufrufen, sollten den Endpunkt operation.get
abfragen, bis das Feld Operation.done
den Wert true
hat.
Wenn das Feld Operation.done
auf false
gesetzt ist, bedeutet dies, dass der Vorgang läuft. Weitere Informationen finden Sie unter Asynchrone API-Befehle.
Das folgende Beispiel zeigt die Antwort wenn das Hinzufügen eines überwachten Projekts erfolgreich:
{ "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2", "metadata": { "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata", "state": "DONE", ... }, "done": true, "response": { "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject", "name": "locations/global/metricsScopes/012012012012/projects/678678678678", "provider": "GCP", "providerAccountId": "...", ... } }
In der vorherigen Antwort ist das Feld Operation.done
auf true
gesetzt. Dieser Wert gibt an, dass der Befehl abgeschlossen ist. Da der Befehl erfolgreich ausgeführt wurde, wird das Feld Operation.response
festgelegt und sein Wert ist ein MonitoredProject
-Objekt.
Das Feld response.name
enthält die ID des den Bereich festlegenden überwachten Projekts. Im Feld providerAccountId
ist der Name des überwachten Projekts aufgeführt.
Der Aufruf dieser Methode führt zu einem Eintrag in den Audit-Logs des den Bereich festlegenden Projekts. Die Google Cloud Console ruft diese API-Methode nicht auf. Daher werden Änderungen, die bei der Verwendung der Google Cloud Console an einem Messwertbereich vorgenommen werden, nicht in den Audit-Logs aufgezeichnet.
Projekt aus einem Messwertbereich entfernen
gcloud
Wenn Sie einen Ressourcencontainer wie ein Google Cloud-Projekt aus einem Messwertbereich entfernen möchten, führen Sie den Befehl gcloud beta monitoring metrics-scopes delete
aus:
gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER
Führen Sie vor dem Ausführen des vorherigen Befehls die folgenden Schritte aus:
Geben Sie den Namen oder die ID des Google Cloud-Projekts ein, dessen Messwertbereich geändert werden soll, in die Variable SCOPING_PROJECT_ID_OR_NUMBER.
Geben Sie die ID Ihres Ressourcencontainers in die Variable MONITORED_RESOURCE_CONTAINER_NAME ein. Wenn der Ressourcencontainer ein Google Cloud-Projekt ist, geben Sie
projects/PROJECT_ID_OR_NUMBER
ein.
Mit dem folgenden Befehl wird beispielsweise das Projekt my-monitored-project
aus dem Messwertbereich des Projekts my-staging-projects
entfernt:
gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects
Die Antwort auf den vorherigen Befehl bestätigt, dass der Befehl erfolgreich abgeschlossen wurde:
Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].
Der folgende Fehler wird gemeldet, wenn das den Umfang festlegende Projekt das durch die Variable MONITORED_RESOURCE_CONTAINER_NAME angegebene Projekt nicht überwacht:
NOT_FOUND: Requested entity was not found.
curl
Senden Sie zum Entfernen eines Google Cloud-Projekts aus einem Messwertbereich eine DELETE
-Anfrage an den Endpunkt locations.global.metricsScopes.projects.delete
:
curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \ https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}
Die Antwort auf diese asynchrone Methode ist ein Operation
-Objekt.
Anwendungen, die diese Methode aufrufen, sollten den Endpunkt operation.get
abfragen, bis das Feld Operation.done
den Wert true
hat.
Wenn das Feld Operation.done
auf false
gesetzt ist, bedeutet dies, dass der Vorgang läuft. Weitere Informationen finden Sie unter Asynchrone API-Befehle.
Das folgende Beispiel zeigt die Antwort bei erfolgreicher Entfernung eines überwachten Projekts:
{ "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c", "metadata": { "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata", "state": "DONE", ... }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
In der vorherigen Antwort ist das Feld Operation.done
auf true
gesetzt. Dieser Wert gibt an, dass der Befehl abgeschlossen ist. Da der Befehl erfolgreich ausgeführt wurde, ist das Feld Operation.response
festgelegt und enthält das Feld @type
.
Der Aufruf dieser Methode führt zu einem Eintrag in den Audit-Logs des den Bereich festlegenden Projekts. Die Google Cloud Console ruft diese API-Methode nicht auf. Daher werden Änderungen, die bei der Verwendung der Google Cloud Console an einem Messwertbereich vorgenommen werden, nicht in den Audit-Logs aufgezeichnet.
Asynchrone API-Methoden
Alle Messwertbereichsmethoden der Cloud Monitoring API, die den Systemzustand ändern, beispielsweise der Befehl zum Hinzufügen eines überwachten Projekts zu einem Messwertbereich, sind asynchron.
Bei diesen Befehlen ist die Befehlsantwort ein Operation
-Objekt.
Anwendungen, die eine asynchrone API-Methode aufrufen, sollten den Endpunkt operation.get
abfragen, bis das Feld Operation.done
den Wert true
hat:
Wenn
done
den Wertfalse
hat, wird der Vorgang noch ausgeführt.Senden Sie zum Aktualisieren der Statusinformationen eine
GET
-Anfrage an den Endpunktoperation.get
:curl -H "Authorization: Bearer ${TOKEN}" \ https://monitoring.googleapis.com/v1/${OPERATION_NAME}
Im vorherigen Befehl ist
OPERATION_NAME
eine Umgebungsvariable, die den Wert des FeldsOperation.name
speichert.Wenn
done
den Werttrue
hat, ist der Vorgang abgeschlossen und entweder das Felderror
oderresponse
ist festgelegt:error
: Wenn dies festgelegt ist, ist der asynchrone Vorgang fehlgeschlagen. Der Wert dieses Felds ist einStatus
-Objekt, das einen gRPC-Fehlercode und eine Fehlermeldung enthält.response
: Wenn dies festgelegt ist, wurde der asynchrone Vorgang erfolgreich abgeschlossen und der Wert spiegelt das Ergebnis wider.
Einrichtung des curl
-Befehls
In diesem Abschnitt wird die Einrichtung beschrieben, mit der die curl-Befehle in diesem Dokument erstellt wurden. Jeder curl
-Befehl auf dieser Seite enthält eine Reihe von Argumenten, gefolgt von der URL einer API-Ressource:
curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>
Legen Sie die folgenden Umgebungsvariablen fest, um die Erstellung der curl
-Befehle zu vereinfachen:
Erstellen Sie die Umgebungsvariable, um die ID oder Nummer des den Umfang festlegenden Projekts zu speichern:
SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
Optional. Wenn Sie beabsichtigen, überwachte Projekte hinzuzufügen oder zu entfernen, konfigurieren Sie die Umgebungsvariable mit der ID oder Nummer des überwachten Projekts:
MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
Authentifizieren Sie sich in der Google Cloud CLI:
gcloud auth login
Optional. Damit Sie Ihre Projekt-ID nicht bei jedem
gcloud
-Befehl angeben müssen, legen Sie Ihre Projekt-ID über die gcloud CLI als Standard-Projekt-ID fest:gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen.
TOKEN=`gcloud auth print-access-token`
Tokens sind für eine begrenzte Zeit gültig. Wenn zuvor funktionierende Befehle plötzlich melden, dass Sie nicht authentifiziert sind, führen Sie diesen Befehl noch einmal aus.
Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable
TOKEN
zurück:echo ${TOKEN} ya29.GluiBj8o....
Möglicherweise müssen Sie auch andere Argumente angeben, um beispielsweise den Typ der HTTP-Anfrage anzugeben (z. B. -X DELETE
). Die Standardanfrage ist GET
, sodass dies in den Beispielen nicht angegeben wird.
Nächste Schritte
Informationen zur Verwendung von Google Cloud mit Terraform finden Sie in den folgenden Ressourcen: