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

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

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

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.