Créer des buckets d'observabilité

Vous pouvez créer manuellement le bucket d'observabilité _Trace avant que votre projet ne reçoive des données de trace pour personnaliser son emplacement de stockage et ses paramètres de clé de chiffrement gérée par le client (CMEK). Si votre projet Google Cloud ingère des données de trace avant l'existence de ce bucket, Google Cloud Observability provisionne automatiquement le bucket à l'aide des paramètres par défaut de votre projet pour les buckets d'observabilité.

Pour savoir comment Google Cloud Observability stocke les données, consultez Présentation du stockage.

Interaction avec les règles d'administration

Une demande de création d'un bucket d'observabilité vérifie que les paramètres de la commande sont conformes aux règles d'administration. Par exemple, si une règle d'administration limite les emplacements des ressources, la création d'un bucket échoue si vous spécifiez un emplacement limité.

Interaction avec les paramètres par défaut des buckets d'observabilité

Lorsque Google Cloud Observability crée automatiquement un bucket d'observabilité en raison de l'ingestion de données, il utilise les paramètres par défaut des buckets d'observabilité qui s'appliquent à la ressource parente du bucket. Ces paramètres par défaut peuvent être définis dans le parent ou dans un ancêtre hiérarchique du parent. Ils spécifient les éléments suivants :

  • Emplacement de stockage.
  • Clé Cloud KMS à utiliser pour les données stockées.

Lorsque vous créez un bucket d'observabilité, vous devez spécifier un emplacement. Google Cloud Observability applique la clé Cloud KMS définie dans vos paramètres par défaut, sauf si vous spécifiez explicitement une autre clé dans votre requête de création.

Vous ne pouvez pas créer de bucket avec le chiffrement par défaut de Google si les paramètres par défaut applicables spécifient une clé Cloud KMS. Pour utiliser le chiffrement par défaut de Google, assurez-vous qu'aucune clé Cloud KMS n'est configurée dans vos paramètres par défaut.

Pour en savoir plus sur les paramètres par défaut des buckets d'observabilité, consultez Définir des valeurs par défaut pour les buckets d'observabilité.

Limites

Les restrictions suivantes s'appliquent :

  • Vous devez spécifier un emplacement compatible.
  • La valeur BUCKET_ID doit être _Trace.
  • Le nom à afficher ne doit pas dépasser 100 octets encodés.
  • La description ne doit pas dépasser 1 000 octets encodés.
  • Les données sont stockées pendant 30 jours. Vous devez omettre la période de conservation ou la définir sur 30.
  • Si vous fournissez une clé Cloud KMS, l'emplacement de la clé doit correspondre exactement à l'emplacement parent du bucket d'observabilité.
  • Vous ne pouvez créer des buckets d'observabilité que dans les projets Google Cloud .
  • Un projet Google Cloud ne peut comporter qu'un seul bucket d'observabilité nommé _Trace.

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 créer des buckets d'observabilité, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Observabilité (roles/observability.editor) 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.

Configurer les interfaces

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.

Terraform

Pour utiliser les exemples Terraform de cette page dans un environnement de développement local, installez et initialisez la gcloud CLI, puis configurez les Identifiants par défaut de l'application avec vos identifiants utilisateur.

  1. Installez la Google Cloud CLI.

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

  3. Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur : 

    gcloud auth application-default login

    Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.

    Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.

Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local dans la documentation sur l'authentification Google Cloud .

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 .

Configurer la clé Cloud KMS

Facultatif. Si vous prévoyez de créer un bucket d'observabilité et de spécifier une clé Cloud KMS, procédez comme suit :

  1. Activez l'API Cloud Key Management Service.

    Rôles requis pour activer les API

    Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer l'API

  2. Créez un trousseau de clés et des clés.

    L'emplacement du bucket d'observabilité doit correspondre à celui de la clé.

  3. Remplacez PROJECT_ID par l'ID de votre projet, puis exécutez la commande suivante :

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    La commande précédente vérifie si vous avez configuré un emplacement de stockage par défaut. Il crée également le compte de service Google Cloud Observability s'il n'existe pas. La réponse de la commande liste l'ID du compte de service.

  4. Accordez le rôle Chiffreur/Déchiffreur de CryptoKey Cloud KMS au compte de service Google Cloud Observability.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability.iam.gserviceaccount.com \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    Avant d'exécuter la commande précédente, effectuez les remplacements suivants :

    • KMS_PROJECT_ID : identifiant alphanumérique unique du projet Google Cloud exécutant Cloud KMS. Il est composé du nom de votre projet Google Cloud et d'un numéro attribué de manière aléatoire. Pour savoir comment obtenir cet identifiant, consultez Identifier des projets.
    • service-PROJECT_NUMBER : nom du compte de service Observability qui figurait dans la réponse de l'étape précédente.
    • KMS_KEY_LOCATION : région de la clé Cloud KMS.
    • KMS_KEY_RING : nom du trousseau de clés Cloud KMS.
    • KMS_KEY_NAME : nom de la clé Cloud KMS. Son format est le suivant : projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Créer un bucket d'observabilité

gcloud

Non compatible

Terraform

Pour créer un bucket d'observabilité, utilisez la ressource Terraform google_observability_bucket et définissez les champs suivants :

  • project : ID de votre projet.
  • location : emplacement du bucket d'observabilité. Pour plus d'informations, consultez Emplacements.
  • bucket_id : ID du bucket d'observabilité. La valeur de ce champ doit être définie sur _Trace.

Vous pouvez également définir une description et un nom à afficher, et fournir une clé CMEK. Pour en savoir plus, consultez la documentation de la ressource.

REST

Pour créer un bucket d'observabilité, envoyez une requête à projects.locations.buckets.create.

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 :

Le corps de la requête est un objet Bucket. Remplissez les champs suivants :

  • name : définissez ce champ sur la valeur suivante :

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • Facultatif : Fournissez des valeurs pour les champs displayName et description.

  • Facultatif : Fournissez une clé CMEK. Si elle est spécifiée, cette clé chiffre les données stockées.

    Si vous ne fournissez pas de CMEK, les paramètres par défaut qui s'appliquent à la ressource parente du bucket déterminent la clé de chiffrement. Si les paramètres par défaut spécifient une clé Cloud KMS, cette clé chiffre les données stockées. Sinon, le chiffrement par défaut de Google est utilisé.

La réponse est un objet Operation. Interrogez la méthode projects.locations.operations.get jusqu'à ce que le champ Operation.done soit défini sur true. D'autres champs de la structure Operation fournissent des informations sur la réussite ou l'échec de la requête.

Lister les buckets d'observabilité

Vous pouvez lister les buckets d'observabilité pour vérifier que la requête de création a abouti.

Cette section explique comment lister vos buckets d'observabilité. Un bucket d'observabilité est l'entité de gestion des ensembles de données, qui stockent les données.

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

Terraform

Vous ne pouvez pas utiliser Terraform pour lister les buckets d'observabilité.

REST

Pour répertorier les buckets d'observabilité qui se trouvent dans votre projet et dans un emplacement spécifique, utilisez la méthode 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

Voici un exemple de réponse :

{
  "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 utiliser 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 en savoir plus, consultez la documentation de référence de l'API Observability.

Étapes suivantes