Gérer les buckets d'observabilité

Preview

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment utiliser l'API Observability pour obtenir des informations sur vos buckets d'observabilité. Il contient également des informations sur la façon de lister les ensembles de données, les liens et les vues. Pour en savoir plus sur la façon dont Google Cloud Observability stocke les données, consultez Présentation du stockage.

Vos données de trace sont stockées dans des buckets d'observabilité. Ce document explique comment gérer le stockage de vos données de trace, mais ne décrit pas le format des données stockées. Pour en savoir plus, consultez Schéma de trace.

Ce document ne s'applique pas au stockage des données de journaux ni de métriques. Les données de journaux et de métriques ne sont pas stockées dans les buckets d'observabilité.

Avant de commencer

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.
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 initialiser la gcloud CLI, exécutez la commande suivante :
gcloud init
Créez ou sélectionnez un projet Google Cloud .
Rôles requis pour sélectionner ou créer un projet
• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .
Vérifiez que la facturation est activée pour votre projet Google Cloud .
Activez l'API Observability :
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
gcloud services enable observability.googleapis.com
Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/observability.viewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Remplacez les éléments suivants :
• PROJECT_ID : ID de votre projet
• USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, [e-mail].
• ROLE : rôle IAM que vous accordez à votre compte utilisateur.

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 initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

Vérifiez que la facturation est activée pour votre projet Google Cloud .

Activez l'API Observability :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

gcloud services enable observability.googleapis.com

Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, [e-mail].
• ROLE : rôle IAM que vous accordez à votre compte utilisateur.

Lister les buckets d'observabilité

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

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 :

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

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

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.

Lister les liens sur un ensemble de données

REST

Pour lister les liens d'un ensemble de données, envoyez une requête au point de terminaison projects.locations.buckets.datasets.links.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

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 Link. Pour chaque objet, la valeur du champ name est au format suivant :

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

LINK_ID correspond au nom de l'ensemble de données BigQuery. Ce champ est unique au niveau mondial pour votre projet Google Cloud .

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

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

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.

Créer un lien vers un ensemble de données

Vous pouvez créer un lien sur un ensemble de données, ce qui permet d'interroger vos données de trace à partir de BigQuery. Vous pouvez également supprimer l'objet Link associé à un ensemble de données.

Avant de commencer

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 :

• Éditeur Observability (roles/observability.editor)
• Utilisateur BigQuery (roles/bigquery.user)

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é

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 comporter au maximum 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 savoir comment interroger votre télémétrie, consultez Afficher et analyser la télémétrie.