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 :

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 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 spans dans une cellule. Une cellule comportant de nombreuses portées est plus foncée qu'une cellule comportant peu de portées. 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 (Portées et Groupées) 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'une étendue ou d'un regroupement, sélectionnez l'entrée dans une ligne de la section tabulaire. Un menu volant s'ouvre et affiche la portée 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 spans et les attributs de la trace.

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

• Projets pour lesquels des données de trace sont recherchées. Par défaut, le système ne recherche les données de trace que dans le projet sélectionné par l'outil de sélection de projet. Toutefois, vous pouvez configurer la page pour rechercher la liste des projets dans un champ d'application de trace.
• Vos autorisations Identity and Access Management (IAM) sur les projets recherchés. 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 des informations supplémentaires 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 la 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édez à l'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 , l'affichage de ces données peut prendre plusieurs minutes. 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 ou le projet de gestion App Hub.

   2. Facultatif : Configurez les projets dans lesquels les données de trace sont recherchées à l'aide de l'élément Scope :

      • Pour afficher les données de trace stockées dans 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 dans plusieurs projets, développez le premier menu de l'élément Champ d'application, sélectionnez Champ d'application de la trace, puis sélectionnez le champ d'application de la trace qui liste 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 renvoyées dépendent de vos rôles IAM dans les projets recherchés. Par exemple, si les projets recherchés incluent un projet Google Cloud auquel vous n'avez pas accès, aucune donnée de trace pour ce projet n'est renvoyée.

      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 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 portée 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 portées, 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 étendues individuelles ou les groupes d'étendues 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. Pour identifier les valeurs aberrantes, sélectionnez l'onglet Spans et triez le tableau par durée.

   Si vous souhaitez obtenir plus d'informations sur un segment spécifique, sélectionnez-le. Un menu volant s'ouvre et affiche la portée dans le contexte de sa trace. Vous pouvez ensuite explorer la portée et la trace.

6. Pour explorer le nombre de spans générés pour chaque service, ainsi que des informations statistiques, sélectionnez l'onglet Groupé :

   • Chaque ligne correspond à un nom de service et de span spécifiques.
   • Vous pouvez trier les lignes en fonction de l'en-tête "Durée".

   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 la portée dans le contexte de sa trace. Vous pouvez ensuite explorer la portée et la trace.

7. 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. Ou, si vous avez déployé des applications sur App Hub, vous pouvez afficher les données de trace uniquement pour l'application, ou pour un service ou une charge de travail spécifiques qui font 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 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 un projet qui n'est pas recherché par la page Explorateur de traces, 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 Scope (Champ d'application) est configuré pour rechercher tous les projets qui stockent vos données de trace. Pour en savoir plus, consultez Mettre à jour la liste des projets dans lesquels rechercher les données de trace.

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 span : nom du span.
• État du segment : état de la demande. Pour en savoir plus sur les valeurs, consultez la documentation OpenTelemetry sur SpanStatus.
• Duration : durée de la période.
• 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 en fonction de 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 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 qu'une clé pour un attribut sur une étendue.

  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

Les spans Trace générés par l'instrumentation que vous avez ajoutée à vos applications peuvent inclure les attributs de ressources suivants :

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

La page Explorateur de traces inclut les filtres d'étendue suivants, dont les menus listent les applications, les services et les charges de travail enregistrés dans App Hub :

• Application App Hub : filtre en fonction de 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.

Pour savoir comment instrumenter votre application afin que les spans de trace incluent des attributs spécifiques à l'application, consultez Instrumenter pour la surveillance des applications.

Explorer une trace

Cette section explique comment explorer une portée dans le contexte de sa trace :

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 span ou d'une trace, effectuez l'une des opérations suivantes :

   • Accédez à la section des tableaux de la page Explorateur Trace, puis sélectionnez une entrée dans la section des tableaux. 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 étendues. Les détails de la portée ou de la trace que vous avez sélectionnée s'affichent :

   • La colonne Nom affiche la hiérarchie des appels. La première entrée inclut l'ID de trace. Cette colonne peut également inclure des annotations indiquant si des événements d'IA générative ou des données de journaux sont disponibles.
   • La colonne Service est extraite de l'attribut OpenTelemetry service.name, lorsque cet attribut est défini. Si cet attribut n'est pas défini et que le service est en cours d'exécution sur App Engine, le nom du service App Engine s'affiche. Sinon, aucun service n'est spécifié.
   • La longueur de la barre de latence est représentative de la valeur de latence.
   • La couleur de la barre de latence indique l'état. Une barre de latence bleue indique que l'opération s'est terminée correctement, tandis qu'une barre de latence rouge indique qu'une erreur s'est produite.
   • Un cercle sur une barre de latence indique qu'une entrée de journal ou un événement sont associés à la portée. Pour modifier ce comportement, utilisez le menu Journaux et événements.

3. Pour explorer la trace, procédez comme suit :

   • Utilisez votre pointeur pour sélectionner différentes étendues. Lorsque vous sélectionnez une étendue, les onglets de la page sont actualisés pour afficher les attributs, les entrées de journaux et les événements de l'étendue.

   • 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" 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 du nom de span, du nom de service ou du volet Attributs qui affiche GET (sans tenir compte de la casse) est mis en surbrillance.

   Remarque : Trace Explorer affiche 10 000 couvertures au maximum pour une trace.

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 :

• Attributs : cet onglet liste les libellés associés aux spans. 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 à la portée sélectionnée. 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, une étendue 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 la période :

  • 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 pour la portée associée.
    • ID de trace pour 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.

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

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

Preview

Cette fonctionnalité est soumise(s) 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 de 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 afficher les événements liés aux agents d'IA générative, utilisez l'onglet Entrées/Sorties. Cet onglet affiche les événements qui suivent les conventions sémantiques OpenTelemetry pour l'IA générative.

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.

• 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 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 montre comment la page Trace Explorer (Explorateur de traces) affiche les événements d'IA générative basés sur du texte qui sont associés aux spans :

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.

Étapes suivantes

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