Gérer le stockage des traces

Ce document explique comment utiliser l'API Observability pour obtenir des informations sur le bucket d'observabilité qui stocke vos données de trace. Il explique comment lister les ensembles de données, les liens et les vues. Pour en savoir plus sur la façon dont vos données de trace sont stockées, consultez Présentation du stockage des traces.

Avant de commencer

Configurez votre projet et vos rôles IAM, puis sélectionnez l'interface que vous prévoyez d'utiliser.

Configurer votre projet et vos rôles

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

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

    8.

  8. Pour obtenir les autorisations nécessaires pour lister les buckets, les liens et les vues, demandez à votre administrateur de vous accorder le rôle IAM Lecteur Observabilité (roles/observability.viewer) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Sélectionnez l'interface que vous prévoyez d'utiliser.

gcloud

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

REST

Pour utiliser les exemples API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à la gcloud CLI.

    Installez la Google Cloud CLI.

    Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud .

Lister les buckets d'observabilité

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • LOCATION : emplacement des buckets d'observabilité. Pour lister tous les buckets d'observabilité, quel que soit leur emplacement, définissez l'emplacement sur un tiret (-).
  • PROJECT_ID : identifiant du projet.

Exécutez la commande gcloud beta observability buckets list  :

Linux, macOS ou 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

La réponse liste le nom, la description et l'heure de création de chaque bucket d'observabilité. Voici un exemple de réponse lorsque la commande est exécutée avec succès : 

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

REST

Pour répertorier les buckets d'observabilité qui se trouvent dans votre projet et dans un emplacement spécifique, envoyez une requête au point de terminaison projects.locations.buckets.list.

Vous devez spécifier le paramètre parent, qui se présente comme suit :

projects/PROJECT_ID/locations/LOCATION

Les champs de l'expression précédente ont les significations suivantes :

  • PROJECT_ID : identifiant du projet.
  • LOCATION : emplacement du bucket d'observabilité. Si vous définissez LOCATION sur un tiret ((-)), tous les buckets d'observabilité de votre projet sont listés.

La réponse est un tableau d'objets Bucket. Pour chaque objet, la valeur du champ name est au format suivant :

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Par exemple, lorsqu'une commande a été émise au point de terminaison buckets.list avec le paramètre parent défini sur projects/my-project/locations/us, la réponse était la suivante :

{
  "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
    }
  ]
}

Vous pouvez envoyer des commandes à d'autres points de terminaison de l'API Observability pour obtenir plus d'informations sur le bucket dont l'ID est BUCKET_ID. Par exemple, vous pouvez lister les ensembles de données du bucket, ainsi que les vues et les liens de chaque ensemble de données. Pour obtenir la liste complète des points de terminaison de l'API Observability, consultez la documentation de référence de l'API Observability.

Lister les ensembles de données dans un bucket d'observabilité

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • BUCKET_ID : ID du bucket d'observabilité. Par exemple, cet ID peut être _Trace.
  • LOCATION : emplacement des buckets d'observabilité.
  • PROJECT_ID : identifiant du projet.

Exécutez la commande gcloud beta observability buckets datasets list  :

Linux, macOS ou 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

La réponse liste le nom, la description et la date de création de chaque ensemble de données. Voici un exemple de réponse lorsque la commande aboutit : 

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

Pour lister les ensembles de données d'un bucket d'observabilité, envoyez une requête au point de terminaison projects.locations.buckets.datasets.list.

Vous devez spécifier le paramètre parent, qui se présente comme suit :

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Les champs de l'expression précédente ont les significations suivantes :

La réponse est un tableau d'objets Dataset. Pour chaque objet, la valeur du champ name est au format suivant :

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

Par exemple, lorsqu'une commande a été émise au point de terminaison buckets.datasets.list avec le paramètre parent défini sur projects/my-project/locations/us/buckets/_Trace, la réponse était la suivante :

{
  "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",
    }
  ]
}

Vous pouvez exécuter des commandes sur d'autres points de terminaison de l'API Observability pour obtenir des informations sur l'ensemble de données dont l'ID est DATASET_ID. Par exemple, vous pouvez lister les vues et les liens sur chaque ensemble de données. Pour obtenir la liste complète des points de terminaison de l'API Observability, consultez la documentation de référence de l'API Observability.

Lister les vues d'un ensemble de données

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • DATASET_ID : ID de l'ensemble de données. Vos données de trace sont stockées dans un ensemble de données nommé Spans.
  • BUCKET_ID : ID du bucket d'observabilité. Par exemple, cet ID peut être _Trace.
  • LOCATION : emplacement des buckets d'observabilité.
  • PROJECT_ID : identifiant du projet.

Exécutez la commande gcloud beta observability buckets datasets views list  :

Linux, macOS ou 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