Remarque : Cet ensemble de documentation concerne les éditions Standard, Plus, paiement à l'usage et Frontline de Gemini Enterprise. Pour la documentation de l'édition Business, consultez le Centre d'aide Gemini Enterprise - Business edition.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Accéder aux traces et aux spans

Ce document explique comment accéder aux traces et aux segments générés par votre application Gemini Enterprise, et comment les afficher. Les traces et les segments fournissent des insights détaillés sur les performances et le flux d'exécution des requêtes dans votre application, par exemple lorsque vous utilisez l'assistant ou les agents.

Vous pouvez afficher les données de trace à l'aide de l'explorateur de traces ou directement dans des agents individuels à l'aide de l'onglet Traces de l'agent.

Concepts clés

Cette section présente les concepts clés liés à l'observabilité dans Gemini Enterprise.

Concept	Description
Trace	Une trace est un ensemble de segments qui représente une seule requête ou transaction lorsqu'elle transite par différents services et composants. Par exemple, une trace représente le cycle de vie complet d'une requête. Cela inclut un utilisateur qui pose une question à l'assistant Gemini Enterprise, l'assistant Gemini Enterprise qui répond et toutes les actions ultérieures déclenchées par la réponse, comme l'envoi d'un e-mail.
Segment	Un segment est une unité de travail unique et chronométrée au sein d'une trace. Il représente une opération spécifique, telle qu'un appel de fonction, une requête API ou une requête de base de données. Chaque segment inclut des détails tels que ses heures de début et de fin, un identifiant unique et sa relation avec d'autres segments. Ces relations forment ensemble une trace.
Journaux de délais	Les journaux de segment sont des messages ou des événements de forme libre, horodatés et associés à un segment spécifique. Ils fournissent des informations détaillées et contextuelles sur l'exécution d'un span, ce qui aide les utilisateurs à déboguer les problèmes et à comprendre le flux d'une requête.

Avant de commencer

Assurez-vous de disposer des éléments suivants :

Le rôle Administrateur Gemini Enterprise ou le rôle Utilisateur Gemini Enterprise de la console Google Cloud .
Une application Web Gemini Enterprise existante. Pour en savoir plus sur la création d'une application, consultez Créer une application.
Pour accéder aux traces, vous devez disposer du rôle Utilisateur Cloud Trace (roles/cloudtrace.user).
Activez le paramètre d'observabilité Activer l'instrumentation des traces et des journaux OpenTelemetry. Selon le type d'agent, vous l'activez dans les configurations au niveau de l'application (pour l'agent Core Assistant) ou dans l'onglet Configuration de l'agent (pour les agents créés par les employés dans Workflow Builder et les agents Deep Research). Pour en savoir plus, consultez Gérer les paramètres d'observabilité.

Conservation des données

Les traces et les segments générés par votre application Gemini Enterprise sont stockés dans Cloud Trace dans votre projet Google Cloud , et leur conservation est régie par Cloud Trace. Par défaut, Cloud Trace conserve les données de segment pendant 30 jours. Les données antérieures à la période de conservation sont automatiquement supprimées. Pour connaître les valeurs de conservation officielles et les plus récentes, consultez Délais de conservation de Cloud Trace dans la documentation Quotas et limites de Cloud Trace.

Accéder aux traces dans l'explorateur Trace

Pour accéder aux traces et aux segments à l'aide de l'explorateur Trace, procédez comme suit :

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

Accéder à l'explorateur Trace
Sélectionnez le projet Google Cloud dans lequel votre application Gemini Enterprise a été créée. Tous les segments de votre projet s'affichent.
Dans le tableau, cliquez sur un ID de segment pour afficher les détails de la trace, y compris la durée du segment et d'autres attributs.

Remarque : Pour en savoir plus sur l'utilisation de l'explorateur Trace, consultez Rechercher et explorer des traces.

Filtrer et rechercher des traces

Dans l'explorateur de traces de votre projet, vous pouvez isoler et analyser les exécutions de l'agent Gemini Enterprise et du connecteur de données à l'aide de ces filtres, paramètres de requête et attributs :

Filtres à facettes :
- Service : filtrez par AssistantService ou connectorsexecution pour isoler les chemins de requête de l'agent de plate-forme et du connecteur de données.
- Segment : filtrez par /AssistantService.StreamAssist pour localiser les segments de tour de parole de l'utilisateur racine, ou recherchez des segments enfants tels que execute_tool <tool_name> et invoke_connector <connector>.
Recherche directe d'ID de trace : recherchez des traces directement à l'aide de l'ID de trace W3C standard de 32 caractères, qui peut être extrait des en-têtes de réponse x-cloud-trace-context de StreamAssist.
Attributs personnalisés : interrogez l'attribut gemini_enterprise.assist_token sur les segments execute_tool ou invoke_connector pour mapper les anciens jetons d'assistance au niveau du tour à la cascade de traces W3C.
Attributs de ressource : chaque segment exporté comporte cloud.region,
Attributs de ressource : chaque segment exporté comporte l'attribut cloud.region. Cet attribut représente l'emplacement de diffusion Gemini Enterprise qui a traité la requête, par exemple global, us ou eu. Vous pouvez filtrer par cet attribut pour comparer les performances entre les régions. Cette comparaison est utile lorsqu'un connecteur de données réussit à un emplacement, mais échoue à un autre. Cette valeur représente l'emplacement qui diffuse votre application, et non la région qui héberge la source de données tierce. Pour appliquer ce filtre, consultez Appliquer des filtres de segment.

Accéder aux traces des agents

Vous pouvez également afficher les segments de trace directement pour chaque agent dans l'onglet Traces de l'agent, qui affiche un résumé chronologique détaillé des enregistrements de trace de segment et des structures d'exécution parent-enfant.

Pour accéder aux traces d'un agent :

Dans la console Google Cloud , accédez à votre application, puis cliquez sur Agents.
Sélectionnez l'agent que vous souhaitez inspecter, puis cliquez sur l'onglet Traces.

Tableau récapitulatif des traces

Le tableau principal de l'onglet Traces affiche les informations suivantes pour chaque segment de trace :

État : état actuel de la trace (affiche actuellement Non défini).
ID de l'intervalle de trace : identifiant unique de l'intervalle de trace. Cliquez sur le lien de l'ID de l'intervalle pour afficher ses détails.
Nom de l'intervalle : brève description du travail effectué par l'intervalle. Voici quelques exemples de périodes pour les connecteurs de données Gemini Enterprise :
- execute_tool <tool_name> : émis pendant la couche de distribution des outils dans l'Agent Runtime (par exemple, execute_tool federated_search).
- invoke_connector <connector> : généré par la couche d'exécution des connecteurs pour représenter la logique de requête vers le connecteur spécifique (par exemple, invoke_connector jira ou invoke_connector servicenow), qui remplace les segments RPC par défaut côté service.
Type de segment : type de segment. Plusieurs options sont disponibles :
- Agent to Tool : appel de l'agent vers un outil externe (réutilisé pour les opérations execute_tool et invoke_connector).
- Invoke Agent : appel d'un agent.
- Agent to Model : requête envoyée par l'agent à un grand modèle de langage.
Durée : temps nécessaire pour terminer l'intervalle de trace (en minutes).
Entrée : données d'entrée ou message envoyé au segment, le cas échéant.
Sortie : résultat de sortie renvoyé par l'intervalle, le cas échéant.
Heure de début : code temporel exact du début de l'exécution de l'intervalle.

Vue détaillée de la trace

Cliquez sur un ID de segment de trace pour ouvrir une page d'informations contenant les éléments suivants :

Résumé : affichez les métadonnées de référence, y compris l'heure de début, la durée et le nombre total de segments. Vous pouvez cliquer sur Afficher dans Cloud Trace ou basculer entre les boutons de vue Graphique et Chronologie.
Visualisations : basculez entre une hiérarchie graphique ou une vue chronologique montrant les relations parent-enfant de tous les segments de trace.
Détails de l'intervalle sélectionné : sélectionnez un seul intervalle pour afficher des sections détaillées, qui peuvent inclure les éléments suivants :
- Résumé : affiche le nom du segment, le service cible, le nombre total de segments avec cette action et la durée totale (en secondes).
- Journaux : affichez les détails des événements pertinents s'ils sont configurés. Cliquez sur Afficher les journaux pour accéder directement aux journaux standards.
- Évaluation : affiche les résultats de l'évaluation, si elle est configurée.
- Entrée et sortie : charges utiles complètes des requêtes et des réponses.
- Journaux et événements : liste des événements qui se sont produits pendant l'exécution de ce segment.
- Traces de la pile : détails de l'erreur en cas d'échec de l'exécution d'un span.
- Métadonnées et liens : liens référençant les entités Cloud Explorer associées.
- Attributs : tags de ressources et paramètres d'observabilité clé-valeur supplémentaires.

Capture d'écran de l'onglet "Traces" dans la console Google Cloud , montrant une chronologie des segments et le résumé des segments

Hiérarchie des segments parent-enfant

Pour l'exécution des connecteurs de données, l'imbrication des segments parent-enfant dans une seule trace W3C permet d'identifier précisément l'origine de la latence ou des erreurs :

/AssistantService.StreamAssist : intervalle de plate-forme C++ racine initiant la requête.
invoke_agent core_assistant : intervalle d'exécution de l'agent.
execute_tool <tool_name> : intervalle d'exécution de l'outil actif (par exemple, execute_tool federated_search).
invoke_connector <connector_name> (par exemple, invoke_connector jira ou invoke_connector servicenow) : intervalle d'exécution des connecteurs, représentant le cycle de vie de la requête vers le point de terminaison tiers.

Télémétrie expérimentale de la convention sémantique de l'IA générative

En plus de la télémétrie stable, les segments de trace Gemini Enterprise incluent des métadonnées plus riches basées sur les conventions sémantiques de l'IA générative OpenTelemetry. OpenTelemetry classe ces conventions dans la catégorie État de développement. Cet état s'applique aux spécifications en phase de démarrage qui peuvent être modifiées ou supprimées, et sur lesquelles vous ne devez pas vous appuyer en production. Comme ces conventions ne sont pas encore stables, cette télémétrie Gemini Enterprise est expérimentale. Ces segments incluent des attributs gen_ai.* qui décrivent l'activité de l'agent, du modèle et de l'outil, comme l'exécution de l'agent et de l'outil, ainsi que les étapes de requête et de réponse.

Le contenu des prompts et des réponses dans les segments de trace (comme le texte du prompt et les réponses générées) n'apparaît que lorsque vos paramètres d'observabilité autorisent la journalisation des entrées de prompt et des sorties de réponse. Sinon, le contenu est masqué ou omis. Pour modifier ces paramètres, consultez Gérer les paramètres d'observabilité.