Trace-Speicher verwalten

In diesem Dokument wird beschrieben, wie Sie mit der Observability API Informationen zum Observability-Bucket abrufen, in dem Ihre Tracedaten gespeichert sind. Es enthält Informationen dazu, wie Sie Datasets, Links und Ansichten auflisten. Weitere Informationen zum Speichern von Trace-Daten finden Sie unter Speicherübersicht für Traces.

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

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

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

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

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Observability Viewer (roles/observability.viewer) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Auflisten von Buckets, Links und Ansichten 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.

  9. Wählen Sie den Tab aus, der Ihrer geplanten Verwendung der Beispiele auf dieser Seite entspricht:

    gcloud

    Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

    Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

    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.

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

    Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Für die Verwendung von REST authentifizieren.

Beobachtbarkeits-Buckets auflisten

gcloud

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

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

Führen Sie den Befehl gcloud beta observability buckets list 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 Observability-Buckets. Hier ist ein Beispiel für 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 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

gcloud

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

  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace lauten.
  • LOCATION: Der Speicherort der Observability-Buckets.
  • PROJECT_ID: Die Kennung des Projekts.

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

Linux, macOS oder Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

Die Antwort enthält den Namen, die Beschreibung und die Erstellungszeit jedes Datasets. Das Folgende ist ein Beispiel für eine Antwort, wenn der Befehl erfolgreich ist: 

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

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

gcloud

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

  • DATASET_ID: Die ID des Datasets. Ihre Tracedaten werden in einem Dataset mit dem Namen Spans gespeichert.
  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace lauten.
  • LOCATION: Der Speicherort der Observability-Buckets.
  • PROJECT_ID: Die Kennung des Projekts.

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

Linux, macOS oder Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

In der Antwort werden der Name, die Erstellungszeit und die Aktualisierungszeit der einzelnen Observability-Ansichten aufgeführt. Hier ist ein Beispiel für eine Antwort, wenn der Befehl erfolgreich war: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

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.

In diesem Abschnitt wird beschrieben, wie Sie eine Verknüpfung für ein Dataset erstellen, damit Ihre Tracedaten in BigQuery abgefragt werden können.

  1. Führen Sie die erforderliche Einrichtung zum Auflisten von Links durch.

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

gcloud

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

  • LINK_ID: Der Name des BigQuery-Datasets.
  • DATASET_ID: Die ID des Datasets. Ihre Tracedaten werden in einem Dataset mit dem Namen Spans gespeichert.
  • BUCKET_ID: Die ID des Observability-Buckets. Diese ID könnte beispielsweise _Trace lauten.
  • LOCATION: Der Speicherort der Observability-Buckets.
  • PROJECT_ID: Die Kennung des Projekts.

Führen Sie den Befehl gcloud beta observability buckets datasets links create aus:

Linux, macOS oder Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

Der Befehl „create“ initiiert einen Vorgang mit langer Ausführungszeit. Das Folgende ist ein Beispiel für eine Antwort, wenn der Befehl erfolgreich ist: 

Create request issued for: [mydataset]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created link [mydataset].

REST

Wenn Sie eine Verknüpfung 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 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 nur Buchstaben, Ziffern und Unterstriche enthalten. Außerdem darf er maximal 100 Zeichen lang sein.

  • 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

Weitere Informationen zur Verwendung der Seite Trace Explorer finden Sie unter Traces suchen und untersuchen.

Informationen zum Analysieren von Trace-Spans mit SQL finden Sie unter Traces abfragen und analysieren.