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 ou le projet de gestion App Hub.

À 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. Cela signifie que la page recherche 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 vous pouvez modifier et 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 d'un dossier est My Folder, celui du projet de gestion du dossier 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.

    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 (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 (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 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 ou le projet de gestion App Hub.

    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 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 ou le projet de gestion App Hub.
    • 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 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 ou le projet de gestion App Hub.
    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.

    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 ou le projet de gestion App Hub.
    • 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 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 ou le projet de gestion App Hub.
    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 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 ou le projet de gestion App Hub.
    • 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 ou le projet de gestion App Hub.
    • 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 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 ou le projet de gestion App Hub.

    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

    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 ou le projet de gestion App Hub.
    • 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 projets par champ d'application de trace 20

    Étapes suivantes