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 le stockage de vos données de trace, consultez Présentation du stockage des traces.

Avant de commencer

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

  9. Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

    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 la date 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 lister 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 se présente 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 de ce 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

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

La réponse liste le nom, la date de création et la date de mise à jour de chaque vue 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'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

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

  • PROJECT_ID : identifiant du projet.
  • LOCATION : emplacement du bucket d'observabilité.
  • BUCKET_ID : ID du bucket d'observabilité. Par exemple, cet ID peut être _Trace.
  • DATASET_ID : ID de l'ensemble de données interrogé. Par exemple, cet ID peut être Spans.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

Dans l'exemple précédent, l'ID d'une vue est représenté par OBS_VIEW_ID. Par exemple, ce champ peut avoir la valeur _AllSpans.

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

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

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.

Cette section explique comment créer un lien sur un ensemble de données, ce qui permet d'interroger vos données de trace depuis BigQuery.

  1. Effectuez la configuration requise pour lister les liens.

  2. Pour obtenir les autorisations nécessaires pour créer un lien vers un ensemble de données, demandez à votre administrateur de vous accorder les rôles IAM suivants 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.

Créer un ensemble de données BigQuery associé

gcloud

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

  • LINK_ID : nom de l'ensemble de données BigQuery.
  • 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 links create  :

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

La commande "create" lance une opération de longue durée. Voici un exemple de réponse lorsque la commande aboutit : 

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

Pour créer un lien vers un ensemble de données BigQuery, envoyez une requête au point de terminaison projects.locations.buckets.datasets.links.create.

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

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

Les champs de l'expression précédente ont la signification suivante :

  • PROJECT_ID : identifiant du projet.
  • LOCATION : emplacement du bucket d'observabilité.
  • BUCKET_ID : ID du bucket d'observabilité. Par exemple, cet ID peut être _Trace.
  • DATASET_ID : ID de l'ensemble de données interrogé. Par exemple, cet ID peut être Spans.

Cette commande nécessite un paramètre de requête et un corps de requête :

  • Le paramètre de requête linkId doit être spécifié et défini sur le nom de l'ensemble de données BigQuery. Exemple :linkId="my_link" Le nom de l'ensemble de données BigQuery doit être unique pour votre projet Google Cloud . Il doit être limité à 100 caractères et ne peut inclure que des lettres, des chiffres et des traits de soulignement.

  • Le corps de la requête est un objet Link. La valeur du champ name a le format suivant :

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

    La valeur que vous fournissez pour le champ name doit correspondre à l'ensemble de données BigQuery associé référencé par le paramètre de requête.

    Le champ LINK_ID correspond au nom de l'ensemble de données BigQuery.

La réponse est un objet Operation. Cet objet contient des informations sur la progression de la méthode. Une fois la méthode terminée, l'objet Operation contient des données d'état.

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.

Étapes suivantes

Pour en savoir plus sur l'utilisation de la page Explorateur de traces, consultez Rechercher et explorer des traces.

Pour savoir comment analyser vos spans de trace avec SQL, consultez Interroger et analyser les traces.