Dépannage des bases de données Gemini Enterprise

Utilisez cette page pour diagnostiquer et résoudre les problèmes liés aux datastores Gemini Enterprise. Lorsqu'un data store ne parvient pas à récupérer des informations, vous pouvez déboguer le problème de manière indépendante en suivant un parcours d'observabilité cohérent et étape par étape.

Pour obtenir une vue d'ensemble d'une erreur, découvrez comment les outils d'observabilité de Google Cloudfonctionnent ensemble :

  • Cloud Monitoring : détecte quand un problème survient. Utilisez-le pour afficher les tendances générales et les taux d'erreur, et pour configurer des alertes pour vos datastores.
  • Cloud Trace : découvre où le problème se produit. Utilisez-le pour afficher le cycle de vie d'une requête, analyser les segments et identifier précisément l'étape à l'origine d'une latence élevée ou d'un échec.
  • Cloud Logging : explique pourquoi le problème se produit. Utilisez-le pour lire les messages d'erreur et les charges utiles exacts associés à une requête ayant échoué.
  • Cloud Audit Logs : identifie qui ou quelle règle a bloqué l'action. Utilisez-le pour suivre la conformité de la sécurité, les modifications d'autorisations et les actions administratives susceptibles de provoquer des refus d'accès.

Workflow de débogage

Lorsque vous examinez un problème de data store, suivez ce workflow séquentiel pour isoler et résoudre la cause principale :

  1. Vérifier les tendances du taux d'erreur
  2. Identifier la requête spécifique qui échoue
  3. Afficher la charge utile d'erreur
  4. Croiser les journaux d'audit d'utilisation

  1. Dans la console Google Cloud , accédez à la page Explorateur de métriques.

    Accéder à l'explorateur de métriques

  2. Consultez vos tableaux de bord et examinez le nombre de requêtes de data store, puis filtrez par ID d'outil et ID de moteur. Vous pouvez déterminer s'il s'agit d'une erreur ponctuelle ou d'un pic systémique généralisé qui nécessite une attention immédiate.

Rechercher la requête spécifique qui échoue

  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. Examinez le graphique à nuage de points pour identifier les traces comportant une icône d'erreur (un point d'exclamation rouge) ou une latence anormalement élevée.
  3. Cliquez sur une trace pour afficher son graphique de Gantt.
  4. Vérifiez la trace invoke_connector pour voir où le processus s'est arrêté ou a échoué.
  5. Vous pouvez également trouver le jeton d'assistance unique associé à une demande spécifique. Si vous devez escalader un problème complexe à l'assistance Google Cloud , partagez ce jeton d'assistance pour accélérer l'investigation.

Afficher la charge utile d'erreur

  1. Cliquez sur le segment défaillant dans l'explorateur Trace.
  2. Dans le volet Détails, cliquez sur Afficher les journaux.
  3. Vous êtes alors automatiquement redirigé vers Cloud Logging, avec un filtre appliqué à cette requête exacte. Vous pouvez y lire la charge utile du journal brut pour identifier la signature d'erreur exacte (par exemple, RESOURCE_EXHAUSTED ou PERMISSION_DENIED).

Croiser les journaux d'audit d'utilisation

Si la charge utile du journal indique un problème IAM, un champ d'application manquant ou un refus d'autorisation, croisez les données avec vos journaux Cloud Audit Logs :

  1. Dans la console Google Cloud , accédez à la page Explorateur de journaux.

    Accéder à l'explorateur de journaux

  2. Examinez l'historique administratif. Vérifiez si votre administrateur a récemment modifié un filtre d'action ou révoqué une autorisation requise.

Exemple : Tracer une requête de data store ayant échoué

Imaginons qu'un utilisateur demande à votre agent Gemini Enterprise d'obtenir l'état d'un ticket Jira, mais que l'agent renvoie un message d'échec générique. Voici comment utiliser le workflow d'observabilité pour trouver la cause principale :

  1. Vérifiez les tendances des erreurs : avant de rechercher des erreurs individuelles, vous devez déterminer l'ampleur du problème. Ouvrez l'explorateur de métriques dans Cloud Monitoring et filtrez les métriques de requête de votre data store par tool_id: get_issue. Vous pouvez constater un pic massif et soudain d'erreurs RESOURCE_EXHAUSTED. Cela confirme qu'il s'agit d'un problème systémique, et non d'une simple faute de frappe ponctuelle de l'utilisateur.
  2. Recherchez la requête ayant échoué : ouvrez l'explorateur Trace et définissez le filtre de temps sur la dernière heure. Dans le graphique à nuage de points, vous remarquez un groupe de traces avec une icône d'erreur rouge indiquant des échecs. Cliquez sur l'une de ces traces récentes pour l'examiner.
  3. Examinez le diagramme de Gantt : le diagramme de Gantt visualise le parcours de la requête. Vous voyez un segment parent réussi pour le routage initial de l'agent, mais un segment invoke_connector défaillant est imbriqué en dessous, ciblant spécifiquement le data store Jira Cloud.
  4. Passer aux journaux : cliquez sur l'intervalle invoke_connector défaillant. Dans le volet "Détails de la trace", cliquez sur Afficher les journaux.

  5. Identifier la cause principale : l'explorateur de journaux s'ouvre, préfiltré sur l'ID de trace exact. Vous pouvez maintenant examiner la charge utile du journal générée par le data store pour identifier l'erreur exacte :

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    Dans ce message d'erreur de charge utile, vous pouvez voir l'outil spécifique (get_issue) qui a échoué et le message explicite indiquant que l'utilisateur qui exécute la requête n'a pas accès à la ressource spécifique dans le système cible.

  6. Résolution : À l'aide de la section Erreurs courantes, vous pouvez identifier cette erreur comme une erreur d'accès aux ressources de l'utilisateur final manquant. L'agent Gemini Enterprise s'est connecté à Jira Cloud, mais Jira Cloud a rejeté la requête, car l'utilisateur ne dispose pas des autorisations nécessaires. Pour résoudre ce problème, demandez à votre administrateur Jira Cloud d'accorder à l'utilisateur l'accès à la ressource spécifique.

Erreurs fréquentes

Lorsque vous examinez vos charges utiles d'erreur dans Cloud Logging, concentrez-vous sur les signatures d'erreur générales. La plupart des erreurs de data store peuvent être résolues par l'utilisateur. Recherchez l'erreur que vous avez rencontrée dans la liste suivante pour en déterminer la cause principale et la corriger.

Erreurs d'authentification et d'accès

Ces erreurs se produisent lorsque des problèmes liés aux identifiants, aux champs d'application ou aux règles d'administration empêchent l'accès aux ressources requises. Si vous rencontrez ces erreurs, Cloud Audit Logs est utile pour déboguer les modifications IAM récentes, les mises à jour des filtres d'action ou les autorisations révoquées.

Jeton OAuth expiré ou non valide

  • Signature de l'erreur : HTTP request failed with status code 401 / 401 Unauthorized
  • Cause principale : Le jeton OAuth a expiré ou n'est pas valide.
  • Résolution : Autorisez à nouveau le data store dans vos paramètres Gemini Enterprise pour générer un nouveau jeton.

Outil bloqué par un filtre d'action

  • Signature de l'erreur : Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Cause principale : l'administrateur a bloqué l'outil à l'aide d'un filtre d'action.
  • Solution : L'administrateur doit mettre à jour la liste d'autorisation des actions ou des outils.

Champs d'application OAuth manquants

  • Signatures d'erreur : Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted OU Cause: Insufficient Permission
  • Cause principale : l'enregistrement de l'application sur la plate-forme tierce ne comporte pas les champs d'application requis.
  • Solution : un administrateur doit accorder les champs d'application exacts nommés dans le journal et autoriser à nouveau l'application.

Autorisations IAM du projet manquantes

  • Signature de l'erreur : Access Denied: User does not have [permission] / mcp.tools.call permission
  • Cause principale : l'appelant ou le compte de service ne dispose pas des autorisations IAM Google Cloud requises dans le projet cible.
  • Solution : Accordez l'autorisation IAM nommée à l'appelant.

Erreurs de performances et de limitation

Ces erreurs sont déclenchées lorsque le volume de requêtes dépasse les limites définies par l'API ou le service cible. Cloud Trace permet d'identifier exactement combien de temps ces requêtes limitées restent en attente avant d'échouer.

Limitation des API tierces (erreur 429)

  • Signature de l'erreur : Cause: Request has been rate limited
  • Cause principale : vous envoyez des requêtes plus rapidement que l'API tierce ne le permet.
  • Résolution : Réduisez votre taux de demandes, mettez en œuvre des stratégies d'intervalle entre les tentatives ou demandez une augmentation de quota au fournisseur tiers.

Le bouton "Activer les actions" n'est pas visible

  • Signature de l'erreur : le bouton Activer les actions n'est pas visible ou est désactivé dans la console après la création d'un data store.
  • Cause principale : Le data store dispose de fonctionnalités limitées (par exemple, recherche fédérée uniquement, ingestion uniquement ou recherche uniquement) et n'est pas compatible avec les actions.
  • Résolution : Les actions ne peuvent pas être activées sur ces types de data store.

Erreurs de visibilité et de ressources

Ces erreurs indiquent que, même si l'authentification a réussi, l'utilisateur ou l'application ne dispose pas des droits spécifiques pour afficher les données demandées ou interagir avec elles.

Restriction de visibilité par un tiers

  • Signature de l'erreur : 422 ... you do not have permission to view [Resource/Users]
  • Cause principale : une restriction de visibilité ou une règle d'administration sur la plate-forme tierce empêche la récupération des données.
  • Solution : Ajustez votre appartenance à une organisation tierce ou réduisez la limite de votre champ d'application de requête.

Accès aux ressources de l'utilisateur final manquant

  • Signature de l'erreur : permission denied: [user] does not have access to [Resource]
  • Cause principale : l'utilisateur final qui exécute la requête n'a pas accès au composant ou à la ressource spécifique dans le système cible.
  • Solution : Accordez à l'utilisateur l'accès à la ressource directement dans le système cible.

Erreurs système et côté serveur

Ces erreurs sont dues à des problèmes d'infrastructure, à des délais d'expiration ou à des erreurs de configuration du backend. En général, elles ne se résolvent pas d'elles-mêmes.

Point de terminaison tiers lent ou surchargé

  • Signature de l'erreur : context deadline exceeded
  • Cause principale : le point de terminaison tiers est lent ou surchargé, ce qui entraîne l'expiration de la requête côté Google.
  • Résolution : réessayez d'envoyer la requête. Si l'erreur persiste, contactez l'assistance Google Cloud pour régler le délai avant expiration.

Mauvaise configuration de la liaison des identifiants du serveur MCP

  • Signature de l'erreur : CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Cause principale : un problème de règle côté serveur est survenu, car la liaison des identifiants du serveur MCP est mal configurée. Le client ne peut pas résoudre ce problème lui-même.
  • Solution : Contactez l'assistance Google Cloud .

Obtenir de l'aide

Si vous rencontrez une erreur context deadline exceeded ou CredsPermissionException persistante, vous devrez peut-être envoyer une demande d'assistance à l'assistance Google Cloud .

Pour accélérer la résolution, veuillez rassembler les artefacts suivants à partir de vos outils d'observabilité avant d'ouvrir une demande :

  • Depuis Cloud Logging : charge utile JSON complète du journal de l'erreur.
  • Depuis Cloud Trace : le jeton d'assistance et les détails spécifiques de l'intervalle (y compris l'ID de trace) associés à la requête ayant échoué.
  • À partir des journaux d'audit d'utilisation : tous les codes temporels de modification IAM ou les modifications de stratégie pertinents susceptibles d'avoir déclenché le problème.