Créer et gérer des champs d'application de trace

Ce document explique comment créer et gérer un champ d'application de trace, qui permet à la page Explorateur de traces de trouver les spans de trace que vous souhaitez afficher ou analyser. Si vous souhaitez uniquement afficher et analyser les spans qui proviennent de votre projet Google Cloud , vous n'avez pas besoin de configurer de niveaux d'accès aux traces. Toutefois, si vos données de trace sont stockées dans plusieurs projets, comme cela peut se produire lorsque vous utilisez une architecture de microservices, vous devez effectuer certaines activités de configuration pour afficher toutes les portées d'un seul projet Google Cloud .

Ce document n'explique pas comment afficher vos traces et vos spans. Pour en savoir plus, consultez Rechercher et explorer des traces.

Cette fonctionnalité n'est disponible que pour les projets Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.

À propos des champs d'application de trace

Les champs d'application de trace sont des ressources persistantes au niveau du projet qui listent les vues, lesquelles permettent d'accéder à vos données de trace. Vous pouvez configurer la page Explorateur Trace pour effectuer une recherche par champ d'application de trace. Cela signifie que la page recherche les vues listées dans le champ d'application sélectionné. Vos rôles Identity and Access Management (IAM) sur la vue recherchée et le paramètre de plage de dates déterminent les données que le système récupère du stockage, puis affiche.

Vous pouvez créer des portées de trace, et modifier ou supprimer celles que vous créez. Vous souhaitez créer un champ d'application de trace lorsque vous disposez d'un service qui écrit des données de portée dans plusieurs projets Google Cloud .

Un champ d'application de trace liste des vues, et non des projets. Google Cloud Bien que vous sélectionniez des projets lorsque vous configurez un champ d'application de trace, le système ajoute à ce champ d'application la vue de trace par défaut de ces projets. La vue de trace par défaut d'un projet correspond à la vue avec le chemin d'accès _Trace/Spans/_AllSpans, où les champs _Trace, Spans et _AllSpans font référence à un bucket, un ensemble de données et une vue d'observabilité. L'ensemble de données Spans stocke vos données de trace.

À moins que vous n'ouvriez la page Explorateur Trace avec une URL qui inclut un champ d'application de trace ou un ID de trace et de span, la page Explorateur Trace recherche les données de trace dans les vues listées dans le champ d'application de trace par défaut. Lorsque vous créez votre projet, le champ d'application de trace nommé _Default est défini comme champ d'application de trace par défaut. Toutefois, vous pouvez sélectionner une autre portée de trace à utiliser comme portée de trace par défaut.

À propos du champ d'application de l'observabilité

Le champ d'application de l'observabilité spécifie les champs d'application de trace et de journaux à utiliser lorsque les pages d'explorateur correspondantes s'ouvrent. Si vous ne configurez pas le champ d'observabilité pour lister les ressources qui stockent vos données, vous risquez de ne pas pouvoir corréler vos données de trace et de journal. Pour en savoir plus, consultez Configurer des champs d'application de l'observabilité pour les requêtes multiprojets.

Applications App Hub et étendues de trace

Vos applications App Hub peuvent écrire des données de trace dans plusieurs projets. Pour obtenir une vue agrégée de ces données, créez un champ d'application de trace, configurez-le pour qu'il liste la vue de trace par défaut de tous les projets qui stockent des données de trace, puis configurez-le comme champ d'application de trace par défaut. Une fois ces étapes effectuées, la page Trace Explorer affiche automatiquement les données écrites par votre application, même si elles sont stockées dans différents projets.

Créez le champ d'application de trace personnalisé dans le projet à partir duquel vous allez afficher vos données de trace. Ce projet est votre projet hôte App Hub ou votre projet de gestion. Par exemple, si le nom à afficher d'un dossier est My Folder, celui du projet de gestion du dossier est My Folder-mp.

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 créer et afficher des portées de trace, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de portées d'observabilité (roles/observability.scopesEditor) 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.

    Le rôle "Éditeur de portées d'observabilité" inclut des autorisations privées qui vous permettent de créer et d'afficher des portées de trace. Ces autorisations ne peuvent pas être incluses dans des rôles IAM personnalisés.

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

    Console

    Lorsque vous utilisez la console Google Cloud pour accéder aux services Google Cloud et aux API, vous n'avez pas besoin de configurer l'authentification.

    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 .

Lister les champs d'application de Trace

Console

Pour lister les portées de trace, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page  Paramètres :

    Accéder aux paramètres

    Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

  2. Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.

  3. Sélectionnez l'onglet Étendues de trace.

    La fenêtre affiche la liste de vos portées de trace. L'entrée qui inclut une icône "Par défaut", , correspond au champ d'application de trace par défaut.

  4. Pour afficher les détails d'un champ d'application de trace, développez-le.

    Si vous développez un champ d'application de trace, vous pouvez voir la liste des vues qu'il inclut. Chaque ligne liste un ID de projet ainsi qu'une entrée telle que _Trace/Spans/_AllSpans, qui identifie l'emplacement de stockage par défaut de vos données de trace. Les champs _Trace, Spans et _AllSpans font référence au bucket, à l'ensemble de données et à la vue d'observabilité pour vos données de trace. La vue _AllSpans correspond à chaque entrée du bucket :

    Nom Description Type Ressources
    _Default Trace scope 1
    myscope My description Trace scope 2
      _Trace/Spans/_AllSpans myproject Trace view
      _Trace/Spans/_AllSpans project-b Trace view

gcloud

Non compatible

Terraform

Vous pouvez utiliser Terraform pour créer et modifier un champ d'application de trace. Toutefois, vous ne pouvez pas utiliser Terraform pour lister les portées de trace.

REST

Pour lister tous les champs d'application de trace dans un projet Google Cloud , utilisez la commande projects.locations.traceScopes.list. Vous devez spécifier un paramètre de chemin d'accès.

Le paramètre de chemin d'accès pour ce point de terminaison utilise la syntaxe suivante :

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

  • PROJECT_ID : identifiant du projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  • LOCATION_ID doit être défini sur global.

La réponse est un tableau d'objets TraceScope. Chaque objet inclut un nom et une liste de ressources.

Pour obtenir des informations sur un champ d'application de trace spécifique, utilisez la commande projects.locations.traceScopes.get.

Créer un champ d'application de trace

Les portées affichées par la page Explorateur de traces dépendent des vues recherchées, de vos rôles IAM sur ces vues, du paramètre de plage de dates et des filtres que vous appliquez.

Vous pouvez créer 100 portées de trace par projet. Un champ d'application de trace peut inclure un total de 20 vues.

Console

Pour créer un champ d'application de trace :

  1. Dans la console Google Cloud , accédez à la page  Paramètres :

    Accéder aux paramètres

    Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

  2. Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  3. Sélectionnez l'onglet Étendues de trace, puis cliquez sur Créer une étendue de trace.

  4. Cliquez sur Ajouter des projets et remplissez la boîte de dialogue.

  5. Dans la section Nommer le champ d'application de la trace, saisissez le nom et la description que vous souhaitez afficher dans l'onglet Champs d'application de la trace.

    Le nom d'un champ d'application de trace ne peut pas être modifié et doit être unique dans le projet.

  6. Cliquez sur Créer un champ d'application de trace.

    Par défaut, le tableau Étendues de trace liste vos étendues de trace sous forme réduite. Pour chaque champ d'application, le tableau indique un nom, une description, un type et un nombre de ressources.

    Si vous développez un champ d'application de trace, vous pouvez voir la liste des vues qu'il inclut. Chaque ligne liste un ID de projet ainsi qu'une entrée telle que _Trace/Spans/_AllSpans, qui identifie l'emplacement de stockage par défaut de vos données de trace. Les champs _Trace, Spans et _AllSpans font référence au bucket, à l'ensemble de données et à la vue d'observabilité pour vos données de trace. La vue _AllSpans correspond à chaque entrée du bucket :

    Nom Description Type Ressources
    _Default Trace scope 1
    myscope My description Trace scope 2
      _Trace/Spans/_AllSpans myproject Trace view
      _Trace/Spans/_AllSpans project-b Trace view

gcloud

Non compatible

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base. Pour en savoir plus, lisez la documentation de référence du fournisseur Terraform.

Pour créer un champ d'application de trace dans un projet à l'aide de Terraform, procédez comme suit :

  1. Utilisez la ressource Terraform google_observability_trace_scope.

    Dans la commande, définissez les champs suivants :

    • project : nom de votre projet, dossier ou organisation. Exemple :my-project Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.

    • Définissez provider sur google-beta.

    • trace_scope_id : définie sur un ID de champ d'application. Exemple :my-trace-scope

    • Définissez location sur "global".

    • resource_names : tableau de projets, où chaque projet est spécifié à l'aide de son nom complet.

    • description : brève description. Par exemple, "Portée des ressources de production".

  2. Après avoir mis à jour votre fichier main.tf, mettez à niveau votre installation de Terraform :

    terraform -init upgrade

    La mise à niveau est nécessaire, car la ressource google_observability_trace_scope est en version bêta.

REST

Pour créer un champ d'application de trace, utilisez la commande projects.locations.traceScopes.create. Vous devez spécifier un paramètre de chemin d'accès et fournir un objet TraceScope. La réponse est un objet TraceScope.

Le paramètre de chemin d'accès pour ce point de terminaison utilise la syntaxe suivante :

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

  • PROJECT_ID : identifiant du projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  • LOCATION_ID doit être défini sur global.

Modifier ou supprimer un champ d'application de trace

Vous ne pouvez pas supprimer ni modifier le champ d'application de trace nommé _Default. Vous pouvez modifier ou supprimer tous les autres champs d'application de trace.

Console

Pour modifier ou supprimer un champ d'application de trace :

  1. Dans la console Google Cloud , accédez à la page  Paramètres :

    Accéder aux paramètres

    Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

  2. Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  3. Sélectionnez l'onglet Étendues de trace.

  4. Recherchez le champ d'application de la trace que vous souhaitez modifier ou supprimer, cliquez sur  Plus, puis effectuez l'une des actions suivantes :

    • Pour le modifier, sélectionnez Modifier le champ d'application, puis remplissez la boîte de dialogue.
    • Pour supprimer une portée, sélectionnez Supprimer la portée, puis remplissez les champs de la boîte de dialogue.

gcloud

Non compatible

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base. Pour en savoir plus, lisez la documentation de référence du fournisseur Terraform.

Pour modifier un champ d'application de trace dans un projet à l'aide de Terraform, procédez comme suit :

  1. Utilisez la ressource Terraform google_observability_trace_scope.

  2. Après avoir mis à jour votre fichier main.tf, mettez à niveau votre installation de Terraform :

    terraform -init upgrade

    La mise à niveau est nécessaire, car la ressource google_observability_trace_scope est en version bêta.

REST

Modifier un champ d'application

Pour modifier un champ d'application de trace, utilisez la commande projects.locations.traceScopes.patch. Vous devez spécifier un paramètre de chemin et des paramètres de requête, et fournir un objet TraceScope. Les paramètres de requête identifient les champs modifiés. La réponse est un objet TraceScope.

Le paramètre de chemin d'accès pour ce point de terminaison utilise la syntaxe suivante :

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

  • PROJECT_ID : identifiant du projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  • LOCATION_ID doit être défini sur global.
  • TRACE_SCOPE_NAME : nom d'un champ d'application de trace. Exemple :my-trace-scope

Supprimer un champ d'application

Pour supprimer un champ d'application de trace, utilisez la commande projects.locations.traceScopes.delete. Vous devez spécifier un paramètre de chemin d'accès.

Le paramètre de chemin d'accès pour ce point de terminaison utilise la syntaxe suivante :

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

  • PROJECT_ID : identifiant du projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  • LOCATION_ID doit être défini sur global.
  • TRACE_SCOPE_NAME : nom d'un champ d'application de trace. Exemple :my-trace-scope

Configurer le champ d'application de trace par défaut

Lorsque la page Explorateur de traces s'ouvre, elle recherche des données de trace dans les vues listées dans le champ d'application de trace par défaut. Si ce champ d'application de trace n'est pas accessible, la page Explorateur Trace interroge la vue _AllSpans de votre projet sur l'ensemble de données par défaut.

Lorsque des projets sont créés, le champ d'application de trace nommé _Default est créé et désigné comme champ d'application de trace par défaut. Toutefois, vous pouvez créer votre propre champ d'application de trace et le désigner comme champ d'application de trace par défaut.

Console

Pour définir le champ d'application de trace par défaut, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page  Paramètres :

    Accéder aux paramètres

    Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

  2. Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.

  3. Sélectionnez l'onglet Étendues de trace.

    L'onglet affiche vos portées de trace et inclut un bouton permettant de créer une portée de trace personnalisée. Le champ d'application de trace affiché avec l'icône "Par défaut", , est le champ d'application de trace par défaut actuel.

  4. Pour modifier le champ d'application de trace par défaut, recherchez celui que vous souhaitez définir comme champ d'application de trace par défaut, cliquez sur son  Plus, puis sélectionnez Définir par défaut.

    Le champ d'application de la trace que vous avez sélectionné est indiqué par une icône "Par défaut", .

gcloud

Non compatible

Terraform

Vous pouvez utiliser Terraform pour créer et modifier un champ d'application de trace. Toutefois, vous ne pouvez pas utiliser Terraform pour définir le champ d'application de trace par défaut.

REST

Pour obtenir et définir le champ d'application des journaux par défaut ou le champ d'application du traçage par défaut à l'aide d'un appel d'API, configurez le champ d'application de l'observabilité. Le champ d'application de l'observabilité liste le champ d'application des journaux par défaut et le champ d'application de trace par défaut :

  • Pour obtenir le champ d'application de l'observabilité par défaut d'un projet, envoyez une requête au point de terminaison projects.locations.scopes.get. Vous devez spécifier un paramètre de chemin d'accès. La réponse est un objet Scope, qui liste le champ d'application des journaux par défaut et le champ d'application du traçage par défaut.

  • Pour modifier le champ d'application de l'observabilité par défaut d'un projet, envoyez une requête au point de terminaison projects.locations.scopes.patch. Vous devez spécifier un paramètre de chemin d'accès et des paramètres de requête, et fournir un objet Scope. Les paramètres de requête identifient les champs qui ont été modifiés. La réponse est un objet Scope.

Le paramètre de chemin d'accès pour les deux points de terminaison se présente comme suit :

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

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

  • PROJECT_ID : identifiant du projet. Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion.
  • LOCATION : le champ "Emplacement" doit être défini sur global.
  • OBSERVABILITY_SCOPE_ID : nom d'un objet Scope. La valeur de ce champ doit être définie sur _Default. L'objet Scope portant le nom _Default, qui est créé automatiquement, stocke des informations sur le champ d'application des journaux par défaut et le champ d'application des traces par défaut.

Pour envoyer une commande à un point de terminaison d'API, vous pouvez utiliser APIs Explorer, qui vous permet d'envoyer une commande depuis une page de référence. Par exemple, pour obtenir le champ d'application par défaut actuel, vous pouvez procéder comme suit :

  1. Cliquez sur projects.locations.scopes.get.

  2. Dans le widget Try this method (Essayer cette méthode), saisissez ce qui suit dans le champ name :

    projects/PROJECT_ID/locations/global/scopes/_Default

    Avant de copier le champ précédent, remplacez PROJECT_ID par le nom de votre projet.

  3. Sélectionnez Execute (Exécuter).

  4. Dans la boîte de dialogue d'autorisation, effectuez les étapes requises.

    La réponse est semblable à ce qui suit :

    {
"name": "projects/my-project/locations/global/scopes/_Default",
"logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
"traceScope": "projects/my-project/locations/global/traceScopes/_Default"
}

Limites concernant les champs d'application des traces

Limites concernant les champs d'application des traces Valeur
Nombre maximal de portées de trace par projet 100
Nombre maximal de vues par portée de trace 20

Étapes suivantes