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.

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 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é, qui est la visualisation par défaut, utilise la couleur pour représenter le nombre de segments dans une cellule. Une cellule comportant de nombreuses étendues est affichée dans une couleur plus foncée qu'une cellule comportant peu d'étendues. Vous pouvez sélectionner une cellule ou activer l'info-bulle d'une cellule pour obtenir plus d'informations. Les autres visualisations vous permettent d'afficher la latence sous forme de centile et d'obtenir des informations sur le taux de couverture. Pour toutes les visualisations, vous pouvez utiliser votre pointeur pour développer l'axe X. Pour les graphiques en courbes, vous pouvez développer les axes X et Y.

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

  • Lorsque vous connaissez l'ID d'une trace, cliquez sur Rechercher une trace dans la barre d'outils, puis saisissez l'ID de la trace dans la boîte de dialogue. Vous pouvez ensuite rechercher des mots clés dans les spans et les attributs de la trace .

  • Lorsque vous consultez les données agrégées, vous pouvez rechercher des périodes spécifiques en appliquant des filtres. Par exemple, vous pouvez filtrer les données pour n'afficher que les spans d'un service spécifique. Vous pouvez ensuite ajouter un deuxième filtre qui limite l'affichage aux portées d'un service spécifique qui signale une erreur.

Les données tabulaires vous permettent d'afficher les détails des portées individuelles et vous aident à identifier les valeurs aberrantes. Par exemple, pour trouver la portée avec la valeur de latence la plus élevée, sélectionnez l'onglet Portées, puis triez les données par latence. Pour trouver les services qui génèrent des erreurs, filtrez les données par état de segment, puis sélectionnez l'onglet Groupé, qui affiche les données agrégées par segment et par nom de service. Chaque ligne du tableau contient un lien vers des informations détaillées.

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

  • Projets pour lesquels des données de trace sont recherchées. Par défaut, seules les données de trace du projet sélectionné par l'outil de sélection de projet sont recherchées. Toutefois, vous pouvez configurer la page pour rechercher la liste des projets dans un champ d'application de trace.
  • Vos autorisations IAM (Identity and Access Management) 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 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 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é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. 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. 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.

  4. Facultatif : Mettez à jour la période à l'aide du sélecteur de période ou en utilisant votre pointeur pour mettre en évidence une période 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.

  5. Accédez à la barre d'outils et définissez le sélecteur de période sur au moins deux semaines. Les données de couverture sont stockées pendant 30 jours.

  6. Explorez les graphiques qui affichent les caractéristiques et les tendances de vos données de trace :

    • Pour obtenir des informations sur les données de latence des segments, définissez le menu Vue graphique sur Durée du segment (carte de densité). L'intensité de la couleur est proportionnelle au nombre de portées. Pour obtenir des informations sur une cellule, utilisez votre pointeur. L'info-bulle affiche le nombre de périodes, la date et l'heure, ainsi que l'intervalle de temps de la cellule.

    • Pour afficher les tendances de latence, définissez le menu Vue du graphique sur Durée de l'intervalle (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.

  7. Explorez les données tabulaires qui listent les spans individuels dans l'onglet Spans et les spans regroupés par service et par nom dans l'onglet Groupé.

    Chaque ligne des tableaux affiche une période ou un regroupement, ainsi qu'un lien vers des informations détaillées et certaines métriques. Par exemple, dans l'onglet Regroupé, les métriques incluent le taux d'erreur et le nombre de portées dans le groupe.

    Pour trouver les valeurs aberrantes, sélectionnez un en-tête de colonne pour trier le tableau.

  8. Ajoutez des filtres pour limiter les segments affichés. 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.

Pour modifier vos paramètres de filtrage, vous pouvez utiliser le volet Filtres de portée ou la barre Filtrer.

Appliquer des filtres de portée

Le volet Filtres de couverture 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 de l'étendue : nom de l'étendue.
  • É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 par attribut de ressource gcp.apphub.application.id.
  • Service App Hub : filtre par 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}

Pour trouver les données de trace de votre application, accédez à l'explorateur de traces, puis au volet Filtres de portée et ajoutez des filtres pour votre application App Hub :

  • Pour filtrer par ID application (gcp.apphub.application.id), utilisez le menu Application App Hub.
  • Pour filtrer par service d'application (gcp.apphub.service.id), utilisez le menu Service App Hub.
  • Pour filtrer par charge de travail d'une application (gcp.apphub.workload.id), utilisez le menu Charge de travail App Hub.
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.

Trouver 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, 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.

  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. Accédez à la barre d'outils, cliquez sur 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.

Explorer une trace

Pour afficher une trace ou un segment :

  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. 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. Effectuez l'une des opérations suivantes :

    • Accédez à la section "Tableau" de la page Trace Explorer, puis sélectionnez une entrée dans le tableau qui liste les portées ou les informations récapitulatives après avoir regroupé les données par service et nom de portée.

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

    Le panneau volant Détails s'ouvre et affiche une trace et ses spans :

    • La colonne Nom affiche la hiérarchie des appels. La première entrée inclut l'ID de trace.
    • 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.

  4. Facultatif : Recherchez le nom de l'étendue, le nom du service et les attributs dans une trace à l'aide du champ Rechercher dans la trace.

    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.

    Vous ne pouvez pas effectuer de recherche à l'aide d'une expression régulière, ni rechercher des journaux, des événements ou des métadonnées.

  5. Pour afficher les détails d'une portée spécifique, sélectionnez-la, puis affichez ses attributs et ses événements. Pour en savoir plus, consultez la section suivante.

Afficher les attributs et les événements

Cette section explique comment afficher les libellés, les journaux et les événements.

Afficher les étiquettes

Pour afficher les libellés associés au segment, accédez à l'onglet Attributs. Pour en savoir plus sur les libellés, consultez Libellés de trace.

Afficher les journaux et les événements

Pour afficher les journaux et les événements liés à la portée, accédez à l'onglet Journaux et événements.

Pour afficher une entrée de journal, cliquez sur  Plus.

Vous pouvez également sélectionner le bouton Afficher les journaux, qui ouvre la page de l'explorateur de journaux avec la requête définie pour filtrer une trace, une étendue et une plage de temps spécifiques. Il se peut que cette requête ne renvoie aucune entrée de journal.

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

Pour afficher les événements liés aux agents d'IA générative, utilisez l'onglet GenAI. Cet onglet est disponible lorsque les spans envoyés à Trace suivent les conventions sémantiques OpenTelemetry pour les systèmes d'IA générative, ce qui génère des messages dont le nom commence par gen_ai.

La capture d'écran suivante montre comment la page Trace Explorer (Explorateur de traces) affiche les événements d'IA générative :

Affichage des spans de trace.

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.

Les attributs sont des paires clé-valeur qui décrivent une caractéristique. Voici quelques exemples d'attributs d'un système d'IA générative :

  • gen_ai.system : identifie le système qui fournit les fonctionnalités d'IA générative.
  • gen_ai.request.model : identifie le modèle auquel la requête est envoyée.

Les événements dont le nom commence par "gen_ai" décrivent généralement les entrées ou sorties individuelles d'un système d'IA générative. Ces entrées et sorties incluent les requêtes système et utilisateur, les entrées et sorties des outils, ainsi que les réponses du modèle. Voici des exemples d'événements provenant d'un système d'IA générative :

  • gen_ai.system.message : événement enregistrant la requête système envoyée à un modèle d'IA générative. L'invite système fournit au modèle des instructions qui ne sont généralement pas visibles par l'utilisateur final et qui guident l'interprétation de la requête de l'utilisateur par le modèle.
  • gen_ai.user.message : événement enregistrant la requête fournie par l'utilisateur et envoyée au modèle.
  • gen_ai.assistant.message : événement enregistrant la sortie du modèle, qui peut inclure l'enregistrement d'un appel d'outil ou contenir une sortie de réponse textuelle. Un message peut inclure des réponses candidates qui ne sont pas utilisées par l'application.
  • gen_ai.choice : événement utilisé pour indiquer les sorties candidates utilisées par l'application.

Afficher les traces de la pile

Pour afficher les traces de pile, utilisez l'onglet Traces de pile.

Afficher des informations générales et d'autres métadonnées

Pour obtenir des informations générales sur la couverture et un tableau de liens vers d'autres couvertures, consultez l'onglet Métadonnées et liens. Voici quelques exemples :

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

Chaque ligne du tableau Liens liste un lien entre la portée actuelle et une autre portée. Le champ Attributs liste les paires clé-valeur pour la portée associée. Le champ Trace renvoie à la trace de la portée associée. Lorsque ce champ contient Trace actuelle, la portée associée se trouve dans la même trace que la portée actuelle. Dans le cas contraire, le champ contient un ID de trace. Pour en savoir plus sur les liens, consultez la page de référence de l'API Links.

Après avoir déployé une mise à jour d'une application, vous pouvez déterminer si elle a affecté la latence de réponse. Vous pouvez afficher les tendances des données de latence en définissant le sélecteur de période de sorte que les données de latence s'affichent avant et après la mise à niveau.

Pour afficher les tendances dans 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.

  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. Facultatif : Ajoutez des filtres pour configurer les spans affichés.
  4. Accédez à la barre d'outils et définissez le sélecteur de période sur au moins deux semaines. Les données de portée sont stockées pendant 30 jours.
  5. Facultatif : Modifiez la sélection du menu Vue du graphique.

Étapes suivantes