Buckets für die Beobachtbarkeit erstellen

Sie können den Beobachtbarkeits-Bucket _Trace manuell erstellen, bevor Ihr Projekt Tracedaten empfängt, um den Speicherort und die Einstellungen für den kundenverwalteten Verschlüsselungsschlüssel (Customer-Managed Encryption Key, CMEK) anzupassen. Wenn Ihr Google Cloud Projekt Tracedaten aufnimmt, bevor dieser Bucket vorhanden ist, stellt Google Cloud Observability automatisch den Bucket mit den Standardeinstellungen Ihres Projekts für Beobachtbarkeits-Bucketsbereit.

Informationen dazu, wie Google Cloud Observability Daten speichert, finden Sie unter Speicherübersicht.

Interaktion mit Organisationsrichtlinien

Bei einer Anfrage zum Erstellen eines Beobachtbarkeits-Buckets wird geprüft, ob die Befehlsparameter den Organisationsrichtlinien entsprechen. Wenn beispielsweise eine Organisationsrichtlinie die Speicherorte von Ressourcen einschränkt, schlägt das Erstellen eines Buckets fehl, wenn Sie einen eingeschränkten Speicherort angeben.

Interaktion mit Standardeinstellungen für Beobachtbarkeits-Buckets

Wenn Google Cloud Observability aufgrund der Aufnahme von Daten automatisch einen Beobachtbarkeits-Bucket erstellt, werden die Standardeinstellungen für Beobachtbarkeits-Buckets verwendet, die auf die übergeordnete Ressource des Buckets angewendet werden. Diese Standardeinstellungen können in der übergeordneten Ressource oder in einem hierarchischen Vorgänger der übergeordneten Ressource definiert sein und geben Folgendes an:

  • Der Speicherort.
  • Der Cloud KMS-Schlüssel, der für die gespeicherten Daten verwendet werden soll.

Beim Erstellen eines Beobachtbarkeits-Buckets müssen Sie einen Speicherort angeben. Google Cloud Observability wendet den in Ihren Standardeinstellungen definierten Cloud KMS-Schlüssel an, es sei denn, Sie geben in Ihrer Erstellungsanfrage explizit einen anderen Schlüssel an.

Sie können keinen Bucket mit der Standardverschlüsselung von Google erstellen, wenn in den entsprechenden Standardeinstellungen ein Cloud KMS-Schlüssel angegeben ist. Wenn Sie die Standardverschlüsselung von Google verwenden möchten, darf in Ihren Standardeinstellungen kein Cloud KMS-Schlüssel konfiguriert sein.

Informationen zu den Standardeinstellungen für Beobachtbarkeits-Buckets finden Sie unter Standardeinstellungen für Beobachtbarkeits-Buckets festlegen.

Beschränkungen

Folgende Einschränkungen gelten:

  • Sie müssen einen unterstützten Speicherort angeben.
  • Die BUCKET_ID muss _Trace sein.
  • Der Anzeigename darf nicht länger als 100 codierte Byte sein.
  • Die Beschreibung darf nicht länger als 1.000 codierte Byte sein.
  • Daten werden 30 Tage lang gespeichert. Sie müssen den Aufbewahrungszeitraum entweder weglassen oder auf 30 festlegen.
  • Wenn Sie einen Cloud KMS-Schlüssel angeben, muss der Speicherort des Schlüssels genau mit dem übergeordneten Speicherort des Beobachtbarkeits-Buckets übereinstimmen.
  • Sie können Beobachtbarkeits-Buckets nur in Google Cloud Projekten erstellen.
  • Ein Google Cloud Projekt kann maximal einen Beobachtbarkeits-Bucket mit dem Namen _Trace haben.

Hinweis

Konfigurieren Sie Ihr Projekt und Ihre IAM-Rollen und wählen Sie die Schnittstelle aus, die Sie verwenden möchten.

Projekt und Rollen konfigurieren

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Beobachtbarkeits-Editor (roles/observability.editor) für Ihr Projekt zu erteilen, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Beobachtbarkeits-Buckets benötigen. 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.

Schnittstellen konfigurieren

gcloud

Installieren Sie die Google Cloud CLI und melden Sie sich dann mit Ihrer föderierten Identität in der gcloud CLI an. Initialisieren Sie nach der Anmeldung, initialisieren Sie die Google Cloud CLI mit dem folgenden Befehl: 

gcloud init

REST

Wenn Sie die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, verwenden Sie die Anmeldedaten, die Sie der gcloud CLI bereitstellen.

    Installieren Sie die Google Cloud CLI und melden Sie sich dann mit Ihrer föderierten Identität in der gcloud CLI an.

Weitere Informationen finden Sie in der Google Cloud Authentifizierungsdokumentation unter Für die Verwendung von REST authentifizieren.

Cloud KMS-Schlüssel konfigurieren

Optional. Wenn Sie einen Beobachtbarkeits-Bucket erstellen und einen Cloud KMS-Schlüssel angeben möchten, gehen Sie so vor:

  1. Aktivieren Sie die Cloud Key Management Service API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.

    API aktivieren

  2. Erstellen Sie einen Schlüsselbund und Schlüssel.

    Der Speicherort des Beobachtbarkeits-Buckets muss mit dem Speicherort des Schlüssels übereinstimmen.

  3. Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts und führen Sie dann den folgenden Befehl aus:

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    Mit dem vorherigen Befehl wird geprüft, ob Sie einen Standardspeicherort konfiguriert haben. Außerdem wird das Google Cloud Observability-Dienstkonto erstellt, wenn es nicht vorhanden ist. In der Antwort des Befehls wird die ID des Dienstkontos aufgeführt.

  4. Weisen Sie dem Google Cloud Observability-Dienstkonto die Rolle „ Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler “ zu.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    Ersetzen Sie vor dem Ausführen des vorherigen Befehls die folgenden Werte:

    • KMS_PROJECT_ID: Die eindeutige alphanumerische Kennung, bestehend aus dem Namen Ihres Google Cloud Projekts und einer zufällig zugewiesenen Nummer, des Google Cloud Projekts, in dem Cloud KMS ausgeführt wird. Informationen zum Abrufen dieser Kennung finden Sie unter Projekte identifizieren.
    • service-PROJECT_NUMBER: Der Name des Beobachtbarkeits-Dienstkontos , der in der Antwort des vorherigen Schritts aufgeführt wurde.
    • KMS_KEY_LOCATION: Die Region des Cloud KMS-Schlüssels.
    • KMS_KEY_RING: Der Name des Cloud KMS-Schlüsselbunds.
    • KMS_KEY_NAME: Der Name des Cloud KMS-Schlüssels. Er hat folgendes Format: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Beobachtbarkeits-Bucket erstellen

REST

Senden Sie eine Anfrage an projects.locations.buckets.create, um einen Beobachtbarkeits-Bucket zu erstellen.

Sie müssen den Parameter „parent“ angeben, der folgendes Format hat:

projects/PROJECT_ID/locations/LOCATION

Die Felder im vorherigen Ausdruck haben folgende Bedeutung:

Der Anfragetext ist ein Bucket-Objekt. Füllen Sie die folgenden Felder aus:

  • name: Legen Sie dieses Feld auf Folgendes fest:

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • Optional: Geben Sie Werte für die Felder displayName und description an.

  • Optional: Geben Sie einen CMEK an. Wenn angegeben, verschlüsselt dieser Schlüssel die gespeicherten Daten.

    Wenn Sie keinen CMEK angeben, bestimmen die Standardeinstellungen, die auf die übergeordnete Ressource des Buckets angewendet werden, den Verschlüsselungsschlüssel. Wenn in den Standardeinstellungen ein Cloud KMS-Schlüssel angegeben ist, verschlüsselt dieser Schlüssel die gespeicherten Daten. Andernfalls wird die Standardverschlüsselung von Google verwendet.

Die Antwort ist ein Operation Objekt. Fragen Sie die projects.locations.operations.get Methode ab, bis das Operation.done Feld auf true gesetzt ist. Andere Felder in der Operation-Struktur enthalten Informationen zum Erfolg oder Misserfolg der Anfrage.

Beobachtbarkeits-Buckets auflisten

Sie können die Beobachtbarkeits-Buckets auflisten, um zu prüfen, ob die Erstellungsanfrage erfolgreich abgeschlossen wurde.

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • LOCATION: Der Speicherort der Beobachtbarkeits-Buckets. Wenn Sie alle Beobachtbarkeits-Buckets unabhängig vom Speicherort auflisten möchten, setzen Sie den Speicherort auf einen Bindestrich (-).
  • PROJECT_ID: Die Kennung des Projekts.

Führen Sie den gcloud beta observability buckets list Befehl aus:

Linux, macOS oder Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

Die Antwort enthält den Namen, die Beschreibung und die Erstellungszeit der einzelnen Beobachtbarkeits-Buckets. Das folgende Beispiel zeigt eine Antwort, wenn der Befehl erfolgreich war: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

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

Sie müssen den Parameter „parent“ angeben, der folgendes Format hat:

projects/PROJECT_ID/locations/LOCATION

Die Felder im vorherigen Ausdruck haben folgende Bedeutung:

  • PROJECT_ID: Die Kennung des Projekts.
  • LOCATION: Der Speicherort des Beobachtbarkeits-Buckets. Wenn Sie LOCATION auf einen Bindestrich (-) setzen, werden alle Beobachtbarkeits-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 den einzelnen Datasets auflisten. Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Referenzdokumentation zur Observability API.

Nächste Schritte