Messwertbereich mit der API konfigurieren

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.

Sie können auch Terraform verwenden, um einen Messwertbereich zu konfigurieren. Weitere Informationen finden Sie in der Terraform-Registry für google_monitoring_monitored_project.

App Hub-Anwendungen und Messwertbereiche

Sie verwalten den Messwertbereich für App Hub Hostprojekte und -Verwaltungsprojekte für einzelne Projektgrenzen. Sie können den Messwertbereich entweder über die Google Cloud Console oder die Cloud Monitoring API verwalten.

Google Cloud verwaltet den Messwertbereich für für Apps aktivierte Ordner, es sei denn, das Hinzufügen eines Projekts zum Messwertbereich schlägt aufgrund der Erschöpfung des Kontingents für den Messwertbereich fehl. In diesem Fall können Sie eine Kontingenterhöhung beantragen und dann Projekte manuell zum Messwertbereich des Verwaltungsprojekts für Ihren für Apps aktivierten Ordner hinzufügen. Weitere Informationen finden Sie unter Messwertbereiche der für die Anwendungsverwaltung konfigurierten Ordner.

Hinweis

  • Wenn Sie mit den Begriffen Messwertbereich und den Bereich festlegendes Projekt nicht vertraut sind, lesen Sie den Abschnitt Messwertbereiche.

  • Achten Sie darauf, dass Ihre IAM-Rollen (Identity and Access Management) für das den Bereich festlegende Projekt und für jedes Projekt, das Sie einem Messwertbereich hinzufügen oder daraus entfernen möchten, alle Berechtigungen der Rolle „Monitoring-Administrator“ (roles/monitoring.admin) enthalten. Weitere Informationen finden Sie unter Messwertbereichskonfigurationen.

  • 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 Sie ihren Status ermitteln, finden Sie unter Asynchrone API-Methoden.

  • Wenn Sie die Cloud Monitoring API mit curl aufrufen möchten oder die Beispiele auf dieser Seite verwenden möchten, führen Sie die Schritte zur Einrichtung des curl Befehls aus.

Projekt einem Messwertbereich hinzufügen

gcloud

Führen Sie den gcloud beta monitoring metrics-scopes create Befehl aus, um ein Google Cloud Projekt einem Messwertbereich hinzuzufügen:

gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --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, dessen Messwertbereich geändert werden soll, in die Variable SCOPING_PROJECT_ID_OR_NUMBER ein. Wählen Sie für App Hub Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt aus.

  • Geben Sie die ID Ihres überwachten Projekts in die Variable MONITORED_PROJECT_ID_OR_NUMBER ein. Das Format dafür ist projects/PROJECT_ID_OR_NUMBER.

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 ausgeführt wurde:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

Senden Sie eine POST Anfrage an den locations.global.metricsScopes.projects.create Endpunkt, um ein Google Cloud Projekt einem Messwertbereich hinzuzufügen:

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

Im vorherigen Beispiel sind die Umgebungsvariablen so definiert:

  • MONITORED_PROJECT_ID_OR_NUMBER speichert die ID des Projekts, das dem Messwertbereich hinzugefügt werden soll.
  • SCOPING_PROJECT_ID_OR_NUMBER speichert die ID des Projekts, dessen Messwertbereich aktualisiert wird.

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": "G​C​P",
    "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. Diese API-Methode wird von der Google Cloud Console nicht aufgerufen. Daher werden Änderungen an einem Messwertbereich, wenn Sie die Google Cloud Console verwenden, nicht in den Audit-Logs aufgezeichnet.

Projekt aus einem Messwertbereich entfernen

gcloud

Führen Sie den gcloud beta monitoring metrics-scopes delete Befehl aus, um ein Google Cloud Projekt aus einem Messwertbereich zu entfernen:

gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --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, dessen Messwertbereich geändert werden soll, in die Variable SCOPING_PROJECT_ID_OR_NUMBER ein. Wählen Sie für App Hub Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt aus.

  • Geben Sie die ID Ihres überwachten Projekts in die Variable MONITORED_PROJECT_ID_OR_NUMBER ein. Das Format dafür ist projects/PROJECT_ID_OR_NUMBER.

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 ausgeführt wurde:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

Der folgende Fehler wird gemeldet, wenn das den Bereich festlegende Projekt das durch die MONITORED_PROJECT_ID_OR_NUMBER Variable angegebene Projekt nicht überwacht:

NOT_FOUND: Requested entity was not found.

curl

Senden Sie eine DELETE Anfrage an den locations.global.metricsScopes.projects.delete Endpunkt, um ein Google Cloud Projekt aus einem Messwertbereich zu entfernen:

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}

Im vorherigen Beispiel sind die Umgebungsvariablen so definiert:

  • MONITORED_PROJECT_ID_OR_NUMBER speichert die ID des Projekts, das aus dem Messwertbereich entfernt werden soll.
  • SCOPING_PROJECT_ID_OR_NUMBER speichert die ID des Projekts, dessen Messwertbereich aktualisiert wird.

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, wird das Feld Operation.response festgelegt und enthält ein Feld @type.

Der Aufruf dieser Methode führt zu einem Eintrag in den Audit-Logs des den Bereich festlegenden Projekts. Diese API-Methode wird von der Google Cloud Console nicht aufgerufen. Daher werden Änderungen an einem Messwertbereich, wenn Sie die Google Cloud Console verwenden, nicht in den Audit-Logs aufgezeichnet.

Alle Messwertbereiche auflisten, die ein Projekt enthalten

Wenn Sie wissen möchten, welche Ressourcen die von einem Google Cloud Projekt gespeicherten Daten aufrufen können, können Sie alle Messwertbereiche auflisten, die das Projekt enthalten, und dann Details zu diesen Bereichen abrufen. In diesem Abschnitt erfahren Sie , wie Sie die Messwertbereiche auflisten, die ein bestimmtes Google Cloud Projekt enthalten.

gcloud

Wenn Sie eine Liste der Messwertbereiche abrufen möchten, die die Messwerte für ein Google Cloud Projekt aufrufen können, führen Sie den gcloud beta monitoring metrics-scopes list Befehl aus:

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

Geben Sie vor dem Ausführen des Befehls die ID Ihres überwachten Projekts in die Variable MONITORED_PROJECT_ID_OR_NUMBER ein. Das Format dafür ist projects/PROJECT_ID_OR_NUMBER.

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 zeigt, 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 locations.global.metricsScopes.listMetricsScopesByMonitoredProject Endpunkt und fügen Sie den Abfrageparameter 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}

Im vorherigen Beispiel speichert die Umgebungsvariable PROJECT_ID_OR_NUMBER die ID des Projekts, dessen Aufnahme in den Messwertbereich abgefragt wird.

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

In diesem Abschnitt erfahren Sie, wie Sie Details zu einem bestimmten Messwertbereich abrufen.

gcloud

Führen Sie den gcloud beta monitoring metrics-scopes describe Befehl aus, um detaillierte Informationen zu einem Messwertbereich abzurufen:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Geben Sie vor dem Ausführen des Befehls den voll qualifizierten Namen eines Messwertbereichs in die Variable METRICS_SCOPE_ID ein. Im Folgenden finden Sie ein Beispiel für einen vollständig qualifizierten Namen:

locations/global/metricsScopes/012345012345

Im Folgenden finden Sie ein Beispiel für eine Antwort. In diesem Beispiel enthält 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 gcloud projects list Befehl 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 locations.global.metricsScopes.get Endpunkt:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Im vorherigen Beispiel speichert die Umgebungsvariable SCOPING_PROJECT_ID_OR_NUMBER die ID des Projekts, dessen Messwertbereich abgefragt wird.

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.

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 Wert false hat, wird der Vorgang noch ausgeführt.

    Senden Sie zum Aktualisieren der Statusinformationen eine GET-Anfrage an den Endpunkt operation.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 Felds Operation.name speichert.

  • Wenn done den Wert true hat, ist der Vorgang abgeschlossen und entweder das Feld error oder response ist festgelegt:

    • error: Wenn dies festgelegt ist, ist der asynchrone Vorgang fehlgeschlagen. Der Wert dieses Felds ist ein Status-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:

  1. Erstellen Sie die Umgebungsvariable, um die ID oder Nummer des den Bereich festlegenden Projekts zu speichern. Wenn Sie App Hub verwenden, legen Sie diese Variable auf die ID Ihres App Hub-Hostprojekts oder auf die ID des Verwaltungsprojekts Ihres für Apps aktivierten Ordners fest:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. Optional. Wenn Sie beabsichtigen, überwachte Projekte hinzuzufügen oder zu entfernen, konfigurieren Sie die Umgebungsvariable mit der Projekt-ID oder Nummer des überwachten Projekts:

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. Authentifizieren Sie sich in der Google Cloud CLI:

    gcloud auth login

  4. Optional. Damit Sie nicht bei jedem gcloud-Befehl Ihre Projekt-ID angeben müssen, legen Sie sie mit der gcloud CLI als Standard-ID fest:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. 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.

  6. 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. Daher wird sie in den Beispielen nicht angegeben.

Nächste Schritte

Informationen zur Verwendung von Google Cloud mit Terraform finden Sie in den folgenden Ressourcen: