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 du dossier compatible avec les applications.

À propos des champs d'application de traces

Les champs d'application de trace sont des ressources persistantes au niveau du projet qui listent un ensemble de projets Google Cloud . Vous pouvez configurer la page Explorateur Trace pour effectuer une recherche par champ d'application de trace. La page recherche alors les projets listés dans le champ d'application sélectionné. Vos rôles IAM (Identity and Access Management) dans les projets recherchés et le paramètre de plage de dates déterminent les données extraites du stockage, puis affichées.

Lorsque vous créez un projet Google Cloud , un champ d'application de trace nommé _Default est créé. Ce champ d'application n'inclut que le projet Google Cloud . Vous ne pouvez pas ajouter de projets à ce champ d'application ni le supprimer.

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 .

À moins que vous n'ouvriez la page Explorateur Trace avec une URL incluant 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 projetsGoogle Cloud listés 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.

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 tous les projets qui stockent vos 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 consulterez vos données de journaux. Il s'agit soit de votre projet hôte App Hub, soit du projet de gestion de votre dossier compatible avec les applications. Par exemple, si le nom à afficher du dossier est My Folder, celui du projet de gestion est My Folder-mp.

Avant de commencer

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Enable the API

    8.

  8. Pour obtenir les autorisations nécessaires pour créer et afficher des périmètres de trace, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de périmètres d'observabilité (roles/observability.scopesEditor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez la page 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. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    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. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante : 

      gcloud init

      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 du dossier compatible avec les applications.

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

      Le tableau liste vos portées de trace. Lorsque vous avez sélectionné un projet Google Cloud , une entrée s'affiche avec une icône "Par défaut", , qui indique qu'il s'agit du champ d'application de trace par défaut. Lorsque la page Explorateur Trace s'ouvre, elle recherche des données de trace dans les projets listés dans le champ d'application de trace par défaut.

    gcloud

    Non compatible

    REST

    Pour répertorier tous les champs d'application de trace dans un projet Google Cloud , exécutez 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 du dossier compatible avec les applications.
    • 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 une portée de trace spécifique, utilisez la commande projects.locations.traceScopes.get.

    Créer un champ d'application de trace

    Les spans affichés sur la page Explorateur Trace dépendent des projets recherchés, de vos rôles IAM dans ces projets, du paramètre de plage de temps 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 projets.

    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 du dossier compatible avec les applications.
    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.

      Si vous ne savez pas quels projets inclure dans un champ d'application, vous pouvez utiliser l'ancienne page Explorateur Trace pour vous aider à les identifier. Pour en savoir plus, consultez la section Migrer vers les portées de trace de ce document.

    5. Dans la section Nommer le champ de trace, saisissez le nom et la description que vous souhaitez afficher dans l'onglet Champs de 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.

    gcloud

    Non compatible

    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 du dossier compatible avec les applications.
    • LOCATION_ID doit être défini sur global.

    Migrer vers les champs d'application de Trace

    La page Explorateur Trace vous demande de spécifier les projetsGoogle Cloud dans lesquels rechercher des données de trace. Il s'agit d'un changement de comportement par rapport à l'ancienne page Explorateur Trace. L'ancienne page Explorateur Trace recherche dans tous les projets d'une organisation. En raison de ces différences, il est possible que la page Explorateur de traces n'affiche pas les portées que les anciennes pages Explorateur de traces affichent.

    Vous pouvez utiliser la section Détails des traces de l'ancienne page Explorateur Trace pour compiler une liste desGoogle Cloud projets qui stockent vos données de trace :

    1. Accédez à l'ancienne page Explorateur Trace :

      Accéder à l'ancien explorateur Trace

    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 du dossier compatible avec les applications.

    3. Sélectionnez une trace.

      Vous pouvez essayer les solutions suivantes :

      • Affichez une trace en saisissant son ID dans le champ ID de trace.
      • Ajouter des filtres.

    4. Dans le volet Détails des traces, sélectionnez la trace, puis accédez à l'onglet Projets.

      Cet onglet liste les projets qui stockent les spans de la trace.

    5. Pour créer un champ d'application de trace contenant les projets listés, accédez à la barre d'outils de l'onglet Projets, sélectionnez Créer un champ d'application avec ces projets, puis remplissez la boîte de dialogue.

    6. Répétez les étapes précédentes jusqu'à ce que vous ayez compilé une liste de projets.

    Une fois que vous avez compilé une liste de projets, créez un champ d'application de trace. Vous pouvez également le définir comme champ d'application de trace par défaut.

    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 niveaux 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 du dossier compatible avec les applications.
    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

    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 qui ont été 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 du dossier compatible avec les applications.
    • LOCATION_ID doit être défini sur global.
    • TRACE_SCOPE_NAME : nom d'un champ 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 du dossier compatible avec les applications.
    • LOCATION_ID doit être défini sur global.
    • TRACE_SCOPE_NAME : nom d'un champ de trace. Exemple :my-trace-scope

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

    Lorsque la page Explorateur Trace s'ouvre, elle recherche des données de trace dans les projets listés dans le champ d'application de trace par défaut. Si ce champ d'application de trace n'est pas accessible, des données de trace sont recherchées dans votre projet.

    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 du dossier compatible avec les applications.

    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 trace que vous avez sélectionné est indiqué par une icône "Par défaut", .

    gcloud

    Non compatible

    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 et le champ d'application des traces 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 du dossier compatible avec les applications.
    • 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 et 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 projets par champ d'application de trace 20

    Étapes suivantes