Observability-Buckets verwalten

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

Ihre Trace-Daten werden in Observability-Buckets gespeichert. In diesem Dokument wird beschrieben, wie Sie die Speicherung Ihrer Tracedaten verwalten. Das Format der gespeicherten Daten wird jedoch nicht beschrieben. Weitere Informationen zu diesem Thema 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

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Installieren Sie die Google Cloud CLI.

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

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

    gcloud init

  5. Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines 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 jedes 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 Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

    • So erstellen Sie ein Google Cloud -Projekt:

      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 von Ihnen erstellte Google Cloud Projekt aus:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

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

  7. Observability API aktivieren:

    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. Weitere Informationen zum Zuweisen von Rollen 

    gcloud services enable observability.googleapis.com

  8. 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: myemail@example.com
    • ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.

  9. Installieren Sie die Google Cloud CLI.

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

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

    gcloud init

  12. Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines 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 jedes 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 Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

    • So erstellen Sie ein Google Cloud -Projekt:

      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 von Ihnen erstellte Google Cloud Projekt aus:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

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

  14. Observability API aktivieren:

    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. Weitere Informationen zum Zuweisen von Rollen 

    gcloud services enable observability.googleapis.com

  15. 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: myemail@example.com
    • ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.
    16.

Beobachtbarkeits-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 Endpunkt projects.locations.buckets.list.

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

projects/PROJECT_ID/locations/LOCATION

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

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

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 mit dem übergeordneten Parameter projects/my-project/locations/us gesendet wurde, 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 abzurufen. Sie können beispielsweise die Datasets in diesem Bucket sowie die Ansichten und Links für jedes Dataset auflisten. Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Observability API-Referenzdokumentation.

Datasets in einem Beobachtbarkeits-Bucket auflisten

REST

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Die Felder im vorherigen Ausdruck haben die folgende Bedeutung:

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 mit dem übergeordneten Parameter projects/my-project/locations/us/buckets/_Trace gesendet wurde, 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 abzurufen. Sie können beispielsweise die Ansichten und Links für jedes Dataset auflisten. Eine vollständige Liste der Observability API-Endpunkte finden Sie in der Observability API-Referenzdokumentation.

Ansichten für ein Dataset auflisten

REST

Wenn Sie die Ansichten eines Datasets auflisten möchten, senden Sie eine Anfrage an den Endpunkt projects.locations.buckets.datasets.views.list.

Sie müssen den Parameter „parent“ angeben, der das folgende Format 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 Speicherort des Observability-Buckets.
  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace sein.
  • DATASET_ID: Die ID des Datasets, das abgefragt wird. Diese ID könnte beispielsweise Spans sein.

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. Dieses Feld kann beispielsweise den Wert _AllSpans haben.

Wenn beispielsweise ein Befehl an den Endpunkt buckets.datasets.views.list mit dem auf projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views gesetzten Parameter „parent“ ausgegeben wurde, 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 Observability API-Referenzdokumentation.

REST

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

Sie müssen den Parameter „parent“ angeben, der das folgende Format 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 Speicherort des Observability-Buckets.
  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace sein.
  • DATASET_ID: Die ID des Datasets, das abgefragt wird. Diese ID könnte beispielsweise Spans sein.

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 mit dem auf projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links gesetzten Parameter „parent“ ausgegeben wurde, 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 Observability API-Referenzdokumentation.

Sie können eine Verknüpfung für ein Dataset erstellen, damit Ihre Tracedaten in BigQuery abgefragt werden können. Sie können auch das Objekt Link löschen, das mit einem Dataset verknüpft ist.

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 für ein Dataset 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.

Verknüpftes BigQuery-Dataset erstellen

REST

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

Sie müssen den Parameter „parent“ angeben, der das folgende Format 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 Speicherort des Observability-Buckets.
  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace sein.
  • DATASET_ID: Die ID des Datasets, das abgefragt wird. Diese ID könnte beispielsweise Spans sein.

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

  • Der Abfrageparameter linkId muss angegeben und auf den Namen des BigQuery-Datasets festgelegt werden. Beispiel: linkId="my_link". Der Name des BigQuery-Datasets muss für Ihr Google Cloud -Projekt eindeutig sein und darf maximal 100 Zeichen lang sein. Er 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 im Abfrageparameter verwiesen wird.

    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 Observability API-Referenzdokumentation.

Nächste Schritte

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