Observability-Buckets verwalten

Vorschau

Dieses Produkt oder Feature unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der Dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und -Features sind „im Ist-Zustand“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

In diesem Dokument wird beschrieben, wie Sie mit der Observability API Informationen zu Ihren Observability-Buckets abrufen. Außerdem wird beschrieben, wie Sie Datasets, Links und Ansichten auflisten. Weitere Informationen dazu, wie Daten in Google Cloud Observability gespeichert werden, finden Sie unter Speicherübersicht.

Ihre Trace-Daten werden in Observability-Buckets gespeichert. In diesem Dokument wird beschrieben, wie Sie die Speicherung Ihrer Trace-Daten verwalten. Das Format der gespeicherten Daten wird jedoch nicht beschrieben. Weitere Informationen finden Sie unter Trace-Schema.

Dieses Dokument gilt nicht für die Speicherung von Log- oder Messwertdaten. Log- und Messwertdaten werden nicht in Observability-Buckets gespeichert.

Hinweis

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Google Cloud-Nutzer sind, erstellen Sie ein Konto, um zu prüfen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
Installieren Sie die Google Cloud CLI.
Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.
Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init
Erstellen oder wählen Sie ein Google Cloud Projekt aus.
Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind
• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Informationen zum Zuweisen von Rollen.
Hinweis: Wenn Sie die in dieser Anleitung erstellten Ressourcen nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes auszuwählen. Nachdem Sie diese Schritte ausgeführt haben, können Sie das Projekt löschen und damit alle Ressourcen entfernen, die mit dem Projekt verknüpft sind.
• Projekt erstellen: Google Cloud

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

• Wählen Sie das Google Cloud Projekt aus, das Sie erstellt haben:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch Ihren Google Cloud Projektnamen.
Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.
Aktivieren Sie die Observability API:
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.
gcloud services enable observability.googleapis.com
Weisen Sie Ihrem Nutzerkonto Rollen zu. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus: roles/observability.viewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Ersetzen Sie Folgendes:
• PROJECT_ID: Ihre Projekt-ID.
• USER_IDENTIFIER: Die Kennung für Ihr Nutzerkonto. Beispiel: [e-mail].
• ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen oder wählen Sie ein Google Cloud Projekt aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Informationen zum Zuweisen von Rollen.

Hinweis: Wenn Sie die in dieser Anleitung erstellten Ressourcen nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes auszuwählen. Nachdem Sie diese Schritte ausgeführt haben, können Sie das Projekt löschen und damit alle Ressourcen entfernen, die mit dem Projekt verknüpft sind.

• Projekt erstellen: Google Cloud

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

• Wählen Sie das Google Cloud Projekt aus, das Sie erstellt haben:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch Ihren Google Cloud Projektnamen.

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

Aktivieren Sie die Observability API:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.

gcloud services enable observability.googleapis.com

Weisen Sie Ihrem Nutzerkonto Rollen zu. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus: roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Projekt-ID.
• USER_IDENTIFIER: Die Kennung für Ihr Nutzerkonto. Beispiel: [e-mail].
• ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.

Observability-Buckets auflisten

REST

Wenn Sie die Observability-Buckets auflisten möchten, die sich in Ihrem Projekt und an einem bestimmten Standort befinden, senden Sie eine -Anfrage an den projects.locations.buckets.list Endpunkt.

Sie müssen den Parameter „parent“ angeben, der die folgende Form hat:

projects/PROJECT_ID/locations/LOCATION

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

• PROJECT_ID: Die Kennung des Projekts.
• LOCATION: Der Standort des Observability-Buckets. Wenn Sie LOCATION auf einen Bindestrich (-) setzen, werden alle Observability-Buckets in Ihrem Projekt aufgelistet.

Die Antwort ist ein Array von Bucket-Objekten. Für jedes Objekt hat der Wert des Felds name das folgende Format:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Wenn beispielsweise ein Befehl an den Endpunkt buckets.list gesendet wurde und der Parameter „parent“ auf projects/my-project/locations/us gesetzt war, lautete die Antwort:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

Sie können Befehle an andere Observability API-Endpunkte senden, um weitere Informationen zum Bucket mit der ID BUCKET_ID zu erhalten. Sie können beispielsweise die Datasets in diesem Bucket sowie die Ansichten und Links in jedem Dataset auflisten. Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Datasets in einem Observability-Bucket auflisten

REST

Wenn Sie die Datasets für einen Observability-Bucket auflisten möchten, senden Sie eine -Anfrage an den projects.locations.buckets.datasets.list Endpunkt.

Sie müssen den Parameter „parent“ angeben, der die folgende Form hat:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

• PROJECT_ID: Die Kennung des Projekts.
• LOCATION: Der Standort des Observability-Buckets.
• BUCKET_ID: Die ID des Observability-Buckets. Beispiel: _Trace.

Die Antwort ist ein Array von Dataset-Objekten. Für jedes Objekt hat der Wert des Felds name das folgende Format:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

Wenn beispielsweise ein Befehl an den Endpunkt buckets.datasets.list gesendet wurde und der Parameter „parent“ auf projects/my-project/locations/us/buckets/_Trace gesetzt war, lautete die Antwort:

{
  "datasets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans",
      "description": "Trace Spans",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Sie können Befehle an andere Observability API-Endpunkte senden, um Informationen zum Dataset mit der ID DATASET_ID zu erhalten. Sie können beispielsweise die Ansichten und Links in jedem Dataset auflisten. Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Ansichten in einem Dataset auflisten

REST

Wenn Sie die Ansichten in einem Dataset auflisten möchten, senden Sie eine -Anfrage an den projects.locations.buckets.datasets.views.list Endpunkt.

Sie müssen den Parameter „parent“ angeben, der die folgende Form hat:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

• PROJECT_ID: Die Kennung des Projekts.
• LOCATION: Der Standort des Observability-Buckets.
• BUCKET_ID: Die ID des Observability-Buckets. Beispiel: _Trace.
• DATASET_ID: Die ID des Datasets, das abgefragt wird. Beispiel: Spans.

Die Antwort ist ein Array von View-Objekten. Für jedes Objekt hat der Wert des Felds name das folgende Format:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

Im vorherigen Ausdruck wird die ID einer Ansicht durch OBS_VIEW_ID dargestellt. Beispiel: _AllSpans.

Wenn beispielsweise ein Befehl an den Endpunkt buckets.datasets.views.list gesendet wurde und der Parameter „parent“ auf projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views gesetzt war, lautete die Antwort:

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Links in einem Dataset auflisten

REST

Wenn Sie die Links in einem Dataset auflisten möchten, senden Sie eine -Anfrage an den projects.locations.buckets.datasets.links.list Endpunkt.

Sie müssen den Parameter „parent“ angeben, der die folgende Form hat:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

• PROJECT_ID: Die Kennung des Projekts.
• LOCATION: Der Standort des Observability-Buckets.
• BUCKET_ID: Die ID des Observability-Buckets. Beispiel: _Trace.
• DATASET_ID: Die ID des Datasets, das abgefragt wird. Beispiel: Spans.

Die Antwort ist ein Array von Link-Objekten. Für jedes Objekt hat der Wert des Felds name das folgende Format:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/links/LINK_ID

LINK_ID ist der Name des BigQuery-Datasets. Dieses Feld ist für Ihr Google Cloud Projekt global eindeutig.

Wenn beispielsweise ein Befehl an den Endpunkt buckets.datasets.links.list gesendet wurde und der Parameter „parent“ auf projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links gesetzt war, lautete die Antwort:

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Link in einem Dataset erstellen

Sie können einen Link in einem Dataset erstellen, mit dem Ihre Trace-Daten in BigQuery abgefragt werden können. Sie können auch das Link-Objekt löschen, das an ein Dataset angehängt ist.

Hinweis

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Links in einem Dataset benötigen:

• Observability-Bearbeiter (roles/observability.editor)
• BigQuery User (roles/bigquery.user)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Verknüpftes BigQuery-Dataset erstellen

REST

Wenn Sie einen Link zu einem BigQuery-Dataset erstellen möchten, senden Sie eine -Anfrage an den projects.locations.buckets.datasets.links.create Endpunkt.

Sie müssen den Parameter „parent“ angeben, der die folgende Form hat:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

• PROJECT_ID: Die Kennung des Projekts.
• LOCATION: Der Standort des Observability-Buckets.
• BUCKET_ID: Die ID des Observability-Buckets. Beispiel: _Trace.
• DATASET_ID: Die ID des Datasets, das abgefragt wird. Beispiel: Spans.

Für diesen Befehl sind ein Abfrageparameter und ein Anfragetext erforderlich:

• Der Abfrageparameter linkId muss angegeben und auf den Namen des BigQuery-Datasets gesetzt werden. Beispiel: linkId="my_link". Der Name des BigQuery-Datasets muss für Ihr Google Cloud Projekt eindeutig sein, darf maximal 100 Zeichen lang sein und darf nur Buchstaben, Ziffern und Unterstriche enthalten.

• Der Anfragetext ist ein Link-Objekt. Der Wert des Felds name hat das folgende Format:

  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID
  

  Der Wert, den Sie für das Feld name angeben, muss mit dem verknüpften BigQuery-Dataset übereinstimmen, auf das der Abfrageparameter verweist.

  Das Feld LINK_ID ist der Name des BigQuery-Datasets.

Die Antwort ist ein Operation Objekt. Dieses Objekt enthält Informationen zum Fortschritt der Methode. Wenn die Methode abgeschlossen ist, enthält das Operation-Objekt Statusdaten.

Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Nächste Schritte

Informationen zum Abfragen Ihrer Telemetriedaten finden Sie unter Telemetriedaten ansehen und analysieren.