Rechercher et explorer des traces

Pour afficher une représentation agrégée de vos données de trace, ou pour trouver et explorer des traces individuelles ou des traces contenant des libellés spécifiques, utilisez la page Explorateur de traces.

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

Pour exécuter des requêtes qui effectuent une analyse agrégée de vos spans, utilisez la page Analyse de l'observabilité ou BigQuery. Les deux interfaces permettent d'interroger vos données de portée à l'aide de SQL. Lorsque vous utilisez la page Observability Analytics, vous pouvez afficher les résultats des requêtes 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 les 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 de la page Explorateur Trace

Pour vous aider à identifier les tendances et les caractéristiques de 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 spans dans une cellule. Une cellule comportant de nombreuses étendues est plus foncée qu'une cellule en comportant peu. 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.

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 pageview Rechercher une trace de la barre d'outils.

Pour identifier les valeurs aberrantes et afficher les détails des portées individuelles, utilisez la section tabulaire :

• Vous pouvez trier les lignes des onglets Spans et Grouped en fonction de l'en-tête "Duration" (Durée).

• Pour comprendre le nombre de spans générés par différents services, utilisez l'onglet Grouped (Regroupé). Chaque ligne correspond à un nom de service et 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 dans une ligne de la section tabulaire. Un menu volant s'ouvre et affiche le segment dans le contexte de sa trace. Dans cette vue, vous pouvez explorer la portée et ses attributs, et afficher les événements et les données de journaux. 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 les _AllSpans du projet. Cette vue permet d'accéder en lecture à toutes les données de trace stockées par le projet.

• Vos autorisations Identity and Access Management (IAM) sur la vue recherchée. Si vous n'êtes pas autorisé à 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.

• Paramètre de période.

• Les filtres que vous appliquez.

Le reste de cette page fournit plus d'informations sur la façon de trouver et d'explorer 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 pour 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.

   Une fois les premières données de trace écrites dans un projet Google Cloud , il peut s'écouler plusieurs minutes avant qu'elles ne soient disponibles. 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 savoir comment résoudre 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 App Hub ou le projet de gestion.

   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 Scope sur Project 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 affichera pas.

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

   3. Facultatif : Mettez à jour la période à l'aide du sélecteur de période ou en mettant en surbrillance une plage sur l'axe X à l'aide de votre pointeur.

      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 segment sont stockées pendant 30 jours.

3. Explorez la carte de densité :

   • Utilisez la couleur pour identifier les tendances et les valeurs aberrantes. Une cellule comportant de nombreuses étendues est 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 périodes, la date et l'heure, ainsi que l'intervalle de temps de la cellule.

     Remarque : Si vous sélectionnez une cellule dans la carte de densité, le tableau qui liste les portées individuelles ou les groupes de portées est mis à jour.

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

   • Pour afficher les tendances de latence, définissez le menu Vue du graphique sur Durée de la période (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 graphique sur Taux de couverture. Le graphique affiche le taux d'envoi des spans à votre projet.

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

   • Pour afficher les anomalies ou trouver un nom de segment, triez le tableau. Vous pouvez trier les données en fonction de n'importe quel en-tête de colonne.

     Par exemple, trier le tableau Spans par durée vous permet de trouver les spans 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 de surveillance des applications correspondant.

   Si vous souhaitez obtenir plus d'informations sur un regroupement spécifique, sélectionnez le nom de la portée pour une ligne. Un menu volant 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 en savoir plus sur le filtrage de 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écifiques qui en font partie.

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 spans qui correspondent à tous les filtres appliqués.

Filtrer une trace par ID

Lorsque vous résolvez 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 pageview Rechercher une trace, puis saisissez l'ID de trace.

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

Remarque : 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 portée liste les filtres les plus courants. Vous pouvez sélectionner plusieurs entrées dans n'importe quelle sous-catégorie. À mesure que vous ajoutez ou supprimez des filtres, la barre Filtrer 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, cette option fait référence aux étendues qui n'incluent pas l'attribut correspondant.

Les filtres de portée suivants sont généralement disponibles :

• Service OpenTelemetry : filtre par 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.
• Duration : durée du segment.
• Type de span : décrit les relations entre les spans. 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 portée, utilisez la barre Filtre.

Utiliser la barre de filtre

La barre Filtrer vous permet d'appliquer un filtre avec une clé et une valeur prédéfinies que vous sélectionnez, ou vous pouvez saisir 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 l'étendue, 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 qu'une clé pour un 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 Toute valeur.

Filtrer par application

Pour trouver ou afficher les spans générés par les services et les charges de travail que vous avez enregistrés dans App Hub, vos spans doivent contenir les attributs de ressource suivants :

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

Les attributs de ressources précédents sont générés par l'instrumentation que vous ajoutez à vos applications. Vous pouvez filtrer vos données de trace par n'importe quel attribut de ressource. Toutefois, les filtres de portée suivants filtrent par ID d'application, de service et de 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 :

1. Accédez au tableau Portées ou Groupé, puis recherchez le service ou la charge de travail. Vous pouvez rechercher l'icône de service , 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 Trace Explorer. 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 span 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 spans affichés dans les tableaux.

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

     Le menu déroulant Détails s'ouvre et affiche une trace et ses spans au format chronologique, ainsi que des informations sur le span sélectionné :

     

     Le menu volant contient un écran partagé. Un côté affiche le segment dans le contexte de sa trace. L'autre côté affiche des onglets qui vous permettent d'afficher des informations spécifiques à la portée, telles que les attributs, les métadonnées, ainsi que les requêtes et les 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 chronologie sont dynamiques. Pour explorer une autre portée, sélectionnez-la 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 indique les éléments suivants :

• La colonne Nom affiche un nom, ainsi qu'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é à la portée. 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 Graph (Graphique) dans la barre d'outils :

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

Rechercher les spans d'une trace

Pour rechercher des mots clés dans les portées 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 que par texte brut. Vous ne pouvez pas rechercher de journaux, d'événements ni de métadonnées.

Par exemple, si vous saisissez GET, le texte GET (sans tenir compte de la casse) est mis en surbrillance dans les volets Nom, Service/Charge de travail et Attributs.

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

Le menu déroulant Détails d'une étendue 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 le délai contient ces événements. Pour vous aider à identifier ces spans, la vue chronologique affiche une icône GenAI, , avec le nom du span, 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 spans. L'explorateur de traces indique les spans qui 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 journaux 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 présentées.

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

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

  Remarque : Les événements d'IA générative sont affichés dans l'onglet Entrées/Sorties. Pour en savoir plus, consultez Afficher les événements d'IA générative.

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

• Métadonnées et liens : liste les informations générales sur le segment :

  • ID de span : il s'agit d'un entier de 64 bits autre que 0. Pour en savoir plus, consultez TraceSpan.
  • ID du segment parent.
  • ID du projet.
  • Heures de début et de fin

  • Tableau listant les liens vers d'autres portées. Pour chaque lien, ce tableau liste les éléments suivants :

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

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

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

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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

• L'onglet Attributs affiche les attributs associés au segment. Pour n'afficher que les attributs d'IA générative, activez l'option 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 mettant en corrélation vos données de trace et de journaux. Pour en savoir plus sur les configurations compatibles, consultez Collecter et afficher les requêtes et réponses multimodales.

    La capture d'écran suivante illustre la façon dont Entrées/Sorties affiche les événements d'IA générative basés sur du texte associés à des portées :

    

    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 LangGraph ReAct avec OpenTelemetry.

Afficher les appels aux serveurs MCP distants

Pour afficher les spans 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 permet de trouver des spans 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, il peut s'agir du texte suivant : roll_dice.

Pour savoir quels serveurs MCP Google Cloud distants sont compatibles avec la génération de traces et comment configurer votre application pour demander à ces serveurs de générer des spans, consultez Examiner les appels MCP à l'aide de Trace.

Étapes suivantes

• Créer et gérer des portées de trace
• Partager des traces et des spans
• Résoudre les problèmes