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 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 des agents.

Vous pouvez afficher les données de trace à l'aide de l'explorateur Trace 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 l'ensemble du cycle de vie d'une requête. Cela inclut un utilisateur posant une question à l' assistant Gemini Enterprise, la réponse de l'assistant Gemini Enterprise 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 dans 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. Ensemble, ces relations ensemble forment une trace.
Journaux de segments	Les journaux de segments sont des messages ou des événements de forme libre horodatés associés à un segment spécifique. Ils fournissent des informations contextuelles détaillées sur l'exécution d'un segment, 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 d'administrateur Gemini Enterprise ou le rôle d'utilisateur Gemini Enterprise de la Google Cloud console.
Une application Web Gemini Enterprise existante. Pour en savoir plus sur la création d'une nouvelle application, consultez Créer une application.
Pour accéder aux traces, vous devez disposer du rôle d'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 pouvez l'activer dans les configurations au niveau de l'application (pour l'agent Assistant principal) ou dans l'onglet Configuration de l'agent (pour les agents créés par les employés Workflow Builder et les agents Recherche approfondie). 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 Google Cloud projet, 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 obtenir les valeurs de conservation faisant autorité et les plus récentes, consultez Périodes 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 Google Cloud console, accédez à la page Explorateur Trace.

Accéder à l'explorateur Trace
Sélectionnez le Google Cloud projet 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 Trace de votre projet, vous pouvez isoler et analyser les exécutions de l'agent Gemini Enterprise et du connecteur de données à l'aide des filtres, des paramètres de requête et des attributs suivants :

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 utilisateur racine, ou recherchez des segments enfants tels que execute_tool <tool_name> et invoke_connector <connector>.
Recherche directe d'ID de trace : recherchez directement les traces à l'aide de l'ID de trace W3C standard à 32 caractères, qui peut être extrait des x-cloud-trace-context en-têtes de réponse de StreamAssist.
Attributs personnalisés : interrogez l'gemini_enterprise.assist_token attribut sur les segments execute_tool ou invoke_connector pour mapper les jetons d'assistance hérités au niveau du tour à la cascade de traces W3C.
Attributs de ressource : chaque segment exporté comporte cloud.region, le
Attributs de ressource : chaque segment exporté comporte l'cloud.region attribut. Cet attribut représente l'emplacement de diffusion de Gemini Enterprise qui a géré 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 dans un emplacement, mais échoue dans 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 directement les segments de trace pour des agents individuels 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 Google Cloud console, 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 segment de trace : identifiant unique du segment de trace. Cliquez sur le lien de l'ID de segment pour afficher ses détails.
Nom du segment : brève description du travail effectué par le segment. Voici quelques exemples de segments pour les connecteurs de données Gemini Enterprise :
- execute_tool <tool_name> : émis lors de la couche de distribution d'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 du connecteur spécifique (par exemple, invoke_connector jira ou invoke_connector servicenow), qui remplace les segments RPC côté service par défaut.
Type de segment : type de segment. Plusieurs options sont disponibles :
- Agent to Tool : invocation de l'agent à un outil externe (réutilisé pour les opérations execute_tool et invoke_connector).
- Invoke Agent : invocation d'un agent.
- Agent to Model : requête de l'agent à un grand modèle de langage.
Durée : temps nécessaire pour terminer le segment 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 le segment, le cas échéant.
Heure de début : code temporel exact du début de l'exécution du segment.

Vue détaillée des traces

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, durée et le nombre total de segments. Vous pouvez cliquer sur Afficher dans Cloud Trace ou basculer entre les boutons d'affichage Graphique et Chronologie.
Visualisations : basculez entre une hiérarchie graphique ou une vue chronologique affichant les relations parent-enfant de tous les segments de trace.
Détails du segment sélectionné : sélectionnez un seul segment 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 tous les résultats d'évaluation, s'ils sont configurés.
- Entrée et sortie : charges utiles complètes de la requête et de la réponse.
- Journaux et événements : liste des événements qui se sont produits lors de l'exécution de ce segment.
- Traces de pile : détails de l'erreur en cas d'échec de l'exécution d'un segment.
- Métadonnées et liens : liens faisant référence à des entités d'explorateur cloud 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'emplacement de la latence ou des erreurs :

/AssistantService.StreamAssist: segment de plate-forme C++ racine qui lance la requête.
invoke_agent core_assistant : segment d'exécution de l'agent.
execute_tool <tool_name> : segment 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) : segment d'exécution des connecteurs, représentant le cycle de vie de la requête jusqu'au point de terminaison tiers.

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

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 d'IA générative OpenTelemetry. OpenTelemetry classe ces conventions comme étant en état de développement Development status. Cet état s'applique aux spécifications de début de phase qui peuvent être modifiées ou supprimées et ne doivent pas être utilisées 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, tels que l'exécution de l'agent et de l'outil, ainsi que les étapes de prompt et de réponse.

Le contenu du prompt et de la réponse dans les segments de trace (tel que 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é.