Rechercher et explorer des traces

La page Explorateur Trace vous permet d'afficher les tendances de latence agrégées, de filtrer les données Cloud Trace et d'inspecter les traces et les spans individuels pour résoudre les problèmes de performances et les erreurs. Par défaut, la page Explorateur Trace interroge les données de trace stockées dans votre projetGoogle Cloud . Toutefois, vous pouvez configurer la page pour interroger les données de trace stockées dans plusieurs projets.

Pour effectuer une analyse agrégée personnalisée de vos segments à l'aide de SQL, utilisez la page Analyse de l'observabilité ou BigQuery. Lorsque vous utilisez la page Analyse de l'observabilité, vous pouvez afficher les résultats de la requête sous forme de tableau ou de graphique. Pour en savoir plus sur l'utilisation de SQL pour interroger vos données de trace, consultez Interroger et analyser des traces.

À propos de la page Explorateur Trace

Pour vous aider à identifier les tendances et les schémas dans vos données de trace, les données de latence sont agrégées et affichées dans des graphiques. La carte de densité utilise des couleurs pour représenter le nombre de segments dans une cellule. Une cellule avec de nombreux intervalles a une couleur plus foncée qu'une cellule avec peu d'intervalles. L'info-bulle de chaque cellule affiche la latence et d'autres informations. Vous pouvez également afficher les centiles de latence et des informations sur le taux de couverture.

La capture d'écran suivante montre comment les données de trace sont affichées :

Exemple d'affichage des données de trace.

Lorsque vous examinez un problème, vous pouvez afficher une trace spécifique ou uniquement les spans présentant certaines propriétés :

  • Pour limiter les segments affichés, appliquez des filtres. Par exemple, vous pouvez filtrer par service, application, état d'erreur et autres propriétés.

  • Pour afficher une trace spécifique, utilisez l'option Trace ID (ID de trace) de la barre d'outils.

Pour identifier les anomalies et afficher les détails des segments individuels, utilisez la section tabulaire :

  • Vous pouvez trier les lignes des onglets Segments et Groupés par en-tête de durée.

  • Pour connaître le nombre de segments générés par différents services, utilisez l'onglet Groupé. Chaque ligne correspond à un service et à un nom de segment. Des statistiques de latence sont affichées pour chaque entrée.

Pour explorer les détails d'un segment ou d'un regroupement, sélectionnez l'entrée d'une ligne dans la section tabulaire. Un menu déroulant s'ouvre et affiche l'étendue dans le contexte de sa trace. Dans cette vue, vous pouvez explorer l'intervalle, ses attributs, et afficher les événements et les données de journal. Vous pouvez également rechercher des mots clés dans les portées et les attributs de la trace.

Les données de trace affichées sur la page Explorateur Trace dépendent des éléments suivants :

  • Le paramètre Champ d'application, qui détermine les vues dans lesquelles le système recherche des données de trace. Lorsque la page s'ouvre, l'élément Champ d'application est défini sur le champ d'application de trace par défaut, et le système interroge les vues listées dans ce champ d'application pour obtenir des données de trace.

    Dans un nouveau projet, le champ d'application de trace par défaut liste la vue _AllSpans du projet. Cette vue fournit un accès en lecture à toutes les données de trace stockées par le projet.

    Vous pouvez créer des champs d'application de trace qui vous permettent d'interroger les données stockées dans plusieurs projets. Pour en savoir plus, consultez Afficher les traces de plusieurs projets.

  • Vos autorisations IAM (Identity and Access Management) sur la vue recherchée. Si vous ne disposez pas des autorisations nécessaires pour afficher les données de trace d'un projet, la console Google Cloud affiche un message d'avertissement et les données de ce projet ne sont pas affichées.

  • Le paramètre de période.

  • Les filtres que vous appliquez.

Vous pouvez enregistrer vos données de trace dans un tableau de bord personnalisé. Pour en savoir plus, consultez Afficher les données de trace sur un tableau de bord personnalisé.

Le reste de cette page fournit plus d'informations sur la recherche et l'exploration de vos données de trace.

Avant de commencer

Pour obtenir les autorisations nécessaires pour afficher les données de trace à l'aide de la console Google Cloud et sélectionner un champ d'application de trace, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Cloud Trace (roles/cloudtrace.user) 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.

Ce rôle prédéfini contient les autorisations requises pour afficher les données de trace à l'aide de la console Google Cloud et pour sélectionner un champ d'application de trace. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour afficher les données de trace à l'aide de la console Google Cloud et pour sélectionner un champ d'application de trace :

  • Pour sélectionner un champ d'application de trace : cloudtrace.traceScopes.[get, list]
  • Pour lire le champ d'application de trace par défaut : observability.scopes.get

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur les rôles, consultez Contrôler les accès avec Identity and Access Management.

Afficher les données de trace agrégées

Pour afficher les informations agrégées sur vos données de trace, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page  Explorateur Trace :

    Accéder à Explorateur Trace

    Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

    Après l'écriture des premières données de trace dans un projet Google Cloud , plusieurs minutes peuvent s'écouler avant que ces données ne soient disponibles pour l'affichage. Si aucune donnée de trace ne s'affiche après quelques minutes, il est possible que votre projet ne contienne aucune donnée à afficher ou qu'il y ait un problème de configuration. Pour en savoir plus sur la résolution de ces problèmes, consultez Dépannage : aucune donnée dans l'interface Trace.

  2. Configurez la page Explorateur Trace :

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

    2. Facultatif : configurez les vues dans lesquelles le système recherche les données de trace à l'aide de l'élément Scope :

      • Pour afficher les données de trace stockées par votre projet, définissez le premier menu de l'élément Champ d'application sur Projet ou sur _Default. Ces deux paramètres sont équivalents.

      • Pour afficher les données de trace stockées par plusieurs projets, développez le premier menu de l'élément Champ d'application, sélectionnez Champ d'application de Trace, puis sélectionnez le champ d'application de Trace qui liste la vue _AllSpans pour ces projets. Une fois votre sélection effectuée, le menu Champ d'application affiche une icône de champ d'application de trace, , et le nom du champ d'application de trace sélectionné.

      Les données affichées par le système dépendent de vos rôles IAM sur les vues recherchées. Par exemple, si vous ne disposez pas des autorisations nécessaires pour afficher les données d'une vue, le système ne les affiche pas.

      Pour en savoir plus, consultez la section Créer et gérer des champs d'action de trace.

    3. Facultatif : Modifiez la période à l'aide du sélecteur de période ou en utilisant votre pointeur pour mettre en surbrillance une plage sur l'axe X.

      Par exemple, vous pouvez définir ce sélecteur sur 2 dernières semaines lorsque vous souhaitez voir s'il existe des tendances dans les données de latence. Les données de couverture sont stockées pendant 30 jours.

  3. Explorez la carte de densité :

    • Utilisez des couleurs pour identifier les tendances et les valeurs aberrantes. Une cellule comportant de nombreuses étendues est d'une couleur plus foncée qu'une cellule comportant peu d'étendues.

    • Affichez les détails de la cellule à l'aide de son info-bulle. L'info-bulle indique le nombre de plages, la date et l'heure, ainsi que l'intervalle de temps de la cellule.

  4. Explorez les centiles de latence et les taux d'erreur :

    • Pour afficher les tendances de latence, définissez le menu Vue graphique sur Durée du segment (centile). Le graphique de durée affiche les 50e, 90e, 95e et 99e centiles.

    • Pour afficher l'état de la réponse en fonction du temps, définissez le menu Vue du graphique sur Taux de couverture. Le graphique affiche le taux de segments envoyés à votre projet.

  5. Utilisez les tableaux Spans (Couverture) et Grouped (Regroupées) pour identifier les valeurs aberrantes ou afficher des informations statistiques. Le tableau Segments liste les segments individuels. La table Groupé regroupe les segments par nom et par nom de service ou de charge de travail.

    • Pour afficher les valeurs aberrantes ou trouver un nom de portée, triez le tableau. Vous pouvez trier les données selon n'importe quel en-tête de colonne.

      Par exemple, trier la table Segments par durée vous permet de trouver les segments présentant une latence élevée.

    • Pour afficher des statistiques telles que la latence moyenne, utilisez le tableau Regroupé.

    • Pour trouver les services et les charges de travail enregistrés dans App Hub, recherchez dans la colonne Service/charge de travail les entrées qui incluent l'icône de service  ou l'icône de charge de travail . Le lien fourni avec un service ou une charge de travail enregistrés dans App Hub ouvre le tableau de bord Application Monitoring correspondant.

    Si vous souhaitez obtenir plus d'informations sur un regroupement particulier, sélectionnez le nom de l'intervalle pour une ligne. Un menu contextuel s'ouvre et affiche le segment dans le contexte de sa trace. Vous pouvez ensuite explorer la portée et la trace.

  6. Pour limiter les segments affichés, ajoutez des filtres. Pour savoir comment filtrer vos données de trace, consultez la section suivante.

Filtrer vos données de trace

Pour n'afficher que les informations qui vous intéressent, appliquez des filtres. Les filtres permettent de limiter les données affichées. Par exemple, vous pouvez filtrer par nom de service et par état. Si vous avez déployé des applications sur App Hub, vous pouvez également afficher les données de trace uniquement pour l'application, ou pour un service ou une charge de travail spécifique faisant partie de l'application.

Lorsque vous ajoutez ou supprimez un filtre, les données affichées sur la page Explorateur Trace sont actualisées et n'affichent que les segments correspondant à tous les filtres appliqués.

Filtrer par ID de trace

Lorsque vous résolvez des problèmes liés à un incident ou à un échec, vous pouvez connaître l'ID de trace. Pour explorer cette trace, accédez à la barre d'outils, cliquez sur ID de trace, puis saisissez l'ID de trace.

Lorsque vous saisissez un ID valide, le menu volant Détails s'ouvre et affiche des informations sur la trace et ses segments. Vous pouvez utiliser les options de ce volet pour explorer la trace. Par exemple, vous pouvez rechercher des mots clés dans les étendues.

Si vous saisissez un ID de trace introuvable, il est possible que les données de trace soient stockées dans une vue qui n'est pas recherchée par la page Explorateur Trace, ou que vous ne disposiez pas d'un rôle IAM vous permettant d'afficher les données de trace. Pour résoudre ces échecs, identifiez les projets qui stockent les données de trace. Pour chaque projet, vérifiez que votre rôle IAM vous permet d'afficher les données de trace, puis assurez-vous que l'élément Champ d'application liste la vue par défaut du projet pour les données de trace. Pour en savoir plus, consultez Configurer les vues dans lesquelles l'explorateur de traces effectue des recherches.

Appliquer des filtres de portée

Le volet Filtres de segment liste les filtres les plus courants. Vous pouvez sélectionner plusieurs entrées dans n'importe quelle sous-catégorie. Lorsque vous ajoutez ou supprimez des filtres, la barre Filtre est également mise à jour.

Les valeurs de tous les menus sont issues de vos données de trace. Lorsqu'un menu inclut une option sans texte, celle-ci fait référence aux étendues qui n'incluent pas l'attribut correspondant.

Les filtres de segment suivants sont généralement disponibles :

  • Service OpenTelemetry : filtre en fonction de l'attribut service.name.
  • Nom du segment : nom du segment.
  • État du segment : état de la demande. Pour en savoir plus sur les valeurs, consultez la documentation OpenTelemetry sur SpanStatus.
  • Durée : durée de la période.
  • Type de portée : décrit les relations entre les portées. Pour en savoir plus sur les valeurs, consultez la documentation OpenTelemetry sur SpanKind.
  • Application App Hub : filtre par l'attribut de ressource gcp.apphub.application.id.
  • Service App Hub : filtre par l'attribut de ressource gcp.apphub.service.id.
  • Charge de travail App Hub : filtre par attribut de ressource gcp.apphub.workload.id.

Si vous souhaitez filtrer par un attribut qui ne figure pas dans le volet Filtres de segment, utilisez la barre Filtre.

Utiliser la barre de filtre

La barre Filtre vous permet d'appliquer un filtre avec une clé de filtre prédéfinie et une valeur que vous sélectionnez, ou vous pouvez saisir à la fois la clé et la valeur.

Pour ajouter un filtre, sélectionnez Ajouter un filtre, puis effectuez l'une des opérations suivantes :

  • Sélectionnez une clé définie, comme Nom de la portée, puis sélectionnez une valeur dans le menu secondaire.

  • Sélectionnez Ajouter un filtre d'attribut, puis ajoutez votre clé et votre valeur personnalisées. Si vous saisissez votre propre clé de filtre, utilisez la même syntaxe que pour une clé d'attribut sur un segment.

    Par exemple, pour filtrer par identifiant d'hôte, définissez la clé sur host.id. De même, pour filtrer par code d'état, définissez la clé sur /http/status_code. Dans ce scénario, vous pouvez définir la valeur sur 200, ce qui génère le filtre /http/status_code: 200. Pour que le filtre corresponde à n'importe quelle valeur, sélectionnez N'importe quelle valeur.

Filtrer par application

Vous pouvez filtrer vos données de trace par application, charge de travail ou service App Hub lorsque ces données contiennent les attributs de ressources suivants :

  • gcp.apphub.application.{container,id,location}
  • gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

Ces attributs de ressource sont générés par l'instrumentation que vous ajoutez à vos applications.

Sur la page Explorateur de traces, utilisez les menus Filtres d'étendue suivants pour limiter les étendues par application, service ou charge de travail :

  • Application App Hub
  • Service App Hub
  • Charge de travail App Hub

Pour ouvrir le tableau de bord de surveillance des applications pour un service et une charge de travail enregistrés dans App Hub, procédez comme suit :

  1. Accédez au tableau Spans ou Grouped (Regroupé), puis recherchez le service ou la charge de travail. Vous pouvez rechercher l'icône de service ou l'icône de charge de travail , ou filtrer le tableau.

  2. Sélectionnez le lien dans la colonne Service/charge de travail.

Explorer une trace

Pour explorer un segment dans le contexte de sa trace, procédez comme suit :

  1. Ouvrez et configurez la page Explorateur Trace. Pour en savoir plus sur ces étapes, consultez Afficher les données de trace agrégées.

  2. Pour afficher les détails d'un segment ou d'une trace, effectuez l'une des opérations suivantes :

    • Accédez à la page Explorateur Trace et sélectionnez une entrée dans le tableau. Vous pouvez trier les lignes des tableaux en fonction de n'importe quel en-tête de tableau. Vous pouvez appliquer des filtres pour limiter les segments affichés dans les tableaux.

    • Accédez à la barre d'outils de la page Explorateur Trace, cliquez sur ID de trace, puis saisissez l'ID de trace.

      Le menu volant Détails s'ouvre et affiche une trace et ses segments dans un format chronologique, ainsi que des informations sur le segment sélectionné :

      Exemple de menu déroulant de trace.

      Le menu volant contient un écran partagé. Un côté affiche l'étendue dans le contexte de sa trace. L'autre côté affiche des onglets qui vous permettent d'afficher des informations spécifiques à l'intervalle, telles que les attributs, les métadonnées, ainsi que les requêtes et réponses associées. Pour en savoir plus sur ces onglets, consultez Afficher les attributs, les entrées de journal et les événements.

      Les éléments de la timeline sont dynamiques. Sélectionnez un span pour afficher ses attributs, ses entrées de journal et ses événements.

Explorer la hiérarchie des appels

Par défaut, la hiérarchie des appels s'affiche sous forme de chronologie. La première entrée représente la trace, et chaque entrée suivante représente un segment. Chaque entrée affiche les éléments suivants :

  • La colonne Nom affiche un nom et un ID de segment ou de trace. Une icône GenAI, , indique qu'un span inclut des événements ou des attributs d'IA générative.
  • La colonne Service/Charge de travail affiche le nom d'un service ou d'une charge de travail. Le système définit cette valeur à l'aide de l'attribut OpenTelemetry service.name. En dernier recours, pour les services App Engine, le système affiche le nom du service App Engine.
  • La couleur et la longueur de la barre de latence reflètent l'état et la durée de la commande.
  • Un cercle sur une barre de latence indique qu'une entrée de journal ou un événement est associé au segment. Pour modifier ce comportement, utilisez le menu Journaux et événements.

Pour afficher la hiérarchie des appels sous forme de graphe orienté acyclique (DAG), sélectionnez Graphique dans la barre d'outils :

Trace montrant un graphe orienté acyclique.

Dans la vue DAG, le nom et la latence s'affichent avec chaque élément. La couleur reflète l'état de l'intervalle. Vous pouvez utiliser la molette de défilement de votre pointeur pour modifier la taille du graphique.

Rechercher les segments d'une trace

Pour rechercher des mots clés dans les segments de la trace, utilisez le champ Rechercher dans la trace.

La recherche ne s'applique qu'aux champs "Nom du segment", "Nom du service ou de la charge de travail" et "Attributs". Vous ne pouvez effectuer des recherches qu'en texte brut, et vous ne pouvez pas rechercher de journaux, d'événements ni de métadonnées.

Par exemple, si vous saisissez GET, toute correspondance non sensible à la casse pour GET dans les champs Nom, Service/charge de travail et Attributs est mise en surbrillance.

Afficher les attributs, les entrées de journal et les événements

Le menu volant Détails d'un segment contient un onglet pour chacun des éléments suivants :

  • Entrées/Sorties : affiche les événements qui suivent les conventions sémantiques OpenTelemetry pour l'IA générative. Cet onglet ne s'affiche que lorsque la période contient ces événements. Pour vous aider à identifier ces segments, la vue chronologique affiche une icône GenAI, , avec le nom du segment, lorsque celui-ci contient des événements ou des attributs qui suivent ces conventions. Pour en savoir plus, consultez Afficher les événements et les attributs de l'IA générative.

  • Attributs : liste les attributs associés aux segments. Trace Explorer indique quels segments contiennent des attributs d'IA générative en affichant une icône GenAI, . Pour en savoir plus sur les libellés, consultez Libellés de trace.

  • Journaux et événements : cet onglet liste les événements et les entrées de journal dont les champs trace_id et span_id correspondent au segment sélectionné. Seules les entrées de journal que vous êtes autorisé à afficher sont affichées.

    Pour explorer une entrée dans cet onglet, cliquez sur  Plus.

    Si vous préférez utiliser la page de l'explorateur de journaux pour afficher les données des journaux, cliquez sur Afficher les journaux. La requête est configurée pour filtrer une trace, une étendue et une plage de temps spécifiques.

  • Traces de la pile : liste les traces de la pile disponibles.

  • Métadonnées et liens : liste des informations générales, des informations sur le champ d'application de l'instrumentation et des liens vers le schéma.

    La section Métadonnées affiche les informations suivantes :

    • ID de segment : l'ID de segment est un entier de 64 bits différent de 0. Pour en savoir plus, consultez TraceSpan.
    • ID du segment parent.
    • ID du projet.
    • Heures de début et de fin.

    • Tableau répertoriant les liens vers d'autres segments. Pour chaque lien, ce tableau liste les éléments suivants :

      • Paires clé-valeur de la portée associée.
      • ID de trace du segment associé. Lorsque ce champ indique Trace actuelle, le segment est associé à un autre segment de la même trace.

      Pour en savoir plus sur les liens, consultez la page de documentation de référence de l'API Links.

    Les sections Champ d'instrumentation et Informations sur le schéma affichent le nom et la version du champ, et fournissent des liens vers le schéma. Ces sections sont omises lorsqu'une étendue ne contient pas ces informations.

Le menu volant Détails peut également inclure un onglet intitulé Entrées/Sorties. Cet onglet affiche les événements d'IA générative.

Afficher les événements d'IA générative

Pour identifier les segments contenant des attributs ou des événements conformes aux conventions sémantiques de l'IA générative OpenTelemetry, recherchez l'icône GenAI,  :

  • L'onglet Attributs affiche les attributs associés à la portée. Pour ne lister que les attributs d'IA générative, activez Attributs d'IA générative uniquement.

  • L'onglet Entrées/Sorties affiche les événements qui suivent ces conventions et les attributs associés, qui sont également affichés dans l'onglet Attributs. Deux configurations sont acceptées :

    • Les requêtes et les réponses textuelles sont associées aux spans en tant qu'attributs, qui sont des paires clé-valeur décrivant une caractéristique ou un événement. Par exemple, la valeur de la clé gen_ai.system identifie le système qui fournit les fonctionnalités d'IA générative. Les clés des attributs d'IA générative commencent par gen_ai.

    • Les requêtes et réponses multimodales stockées dans un bucket Cloud Storage. Cloud Trace identifie ces événements en corrélant vos données de trace et de journal. Pour en savoir plus sur les configurations compatibles, consultez Collecter et afficher des promptings multimodaux et des réponses.

      La capture d'écran suivante illustre la façon dont l'onglet Entrées/Sorties affiche les événements d'IA générative textuels associés aux segments :

      Événements d'IA générative textuelle dans l'explorateur de traces.

      Pour en savoir plus sur l'exemple d'application qui a généré la capture d'écran précédente, consultez Instrumenter un agent ReAct LangGraph avec OpenTelemetry.

Afficher les appels aux serveurs MCP distants

Pour afficher les segments générés par les serveurs MCP, effectuez l'une des opérations suivantes :

  • Filtrez vos données de trace par nom de span.

  • Ajoutez un filtre d'attribut dont la clé est mcp.method.name et la valeur tools/call.

    Ce filtre est spécifique à la recherche de segments dont le nom suit les conventions sémantiques OpenTelemetry pour MCP. Le nom est semblable à :

    tools/call NAME

    Dans l'expression précédente, NAME fait référence au point de terminaison appelé. Par exemple, cela peut ressembler à roll_dice.

Pour en savoir plus sur les serveurs MCP Google Cloud qui génèrent des traces et sur la configuration de votre application pour demander aux serveurs MCP de générer des segments, consultez Examiner les appels MCP à l'aide de Trace.

Étapes suivantes