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 résoudre le problème de manière indépendante en suivant un parcours d'observabilité cohérent et progressif.

Pour obtenir une image complète d'une erreur, découvrez comment Google Cloud's les outils d'observabilité fonctionnent ensemble :

• Cloud Monitoring: détecte quand un problème se produit. 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 étendues et identifier précisément l'étape qui a entraîné une latence élevée ou un échec.
• Cloud Logging : explique pour/quoi 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é en matière de sécurité, les modifications d'autorisations et les actions administratives susceptibles d'entraîner 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 racine :

1. Vérifier les tendances du taux d'erreur
2. Rechercher la requête spécifique ayant échoué
3. Afficher la charge utile de l'erreur
4. Croiser les journaux d'audit d'utilisation

Vérifier les tendances du taux d'erreur

1. Dans la Google Cloud console, 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 votre data store. Filtrez par ID d'outil et ID de moteur. Vous pouvez ainsi 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 ayant échoué

1. Dans la Google Cloud console, 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 les traces comportant une icône d'erreur (point d'exclamation rouge) ou une latence inhabituellement élevée.
3. Cliquez sur une trace pour afficher son graphique de Gantt.
4. Vérifiez l'étendue 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 requête spécifique. Si vous devez transmettre un problème complexe à l' Google Cloud assistance, partagez ce jeton d'assistance pour accélérer l'enquête.

Afficher la charge utile de l'erreur

1. Cliquez sur l'étendue ayant échoué dans Explorateur Trace.
2. Dans le volet Détails, cliquez sur Afficher les journaux.
3. Vous êtes alors automatiquement redirigé vers Cloud Logging, filtré sur 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, une étendue manquante ou un refus d'autorisation, croisez vos Cloud Audit Logs :

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

   Accéder à l'explorateur de journaux

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

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

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

1. Vérifiez les tendances des erreurs : avant de rechercher des erreurs individuelles, vous devez savoir à quel point le problème est répandu. 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 soudain et massif d'erreurs RESOURCE_EXHAUSTED. Cela confirme qu'il s'agit d'un problème systémique, et pas seulement d'une faute de frappe ponctuelle de l'utilisateur.
2. Recherchez la requête ayant échoué : ouvrez l'explorateur Trace et définissez le filtre temporel 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 graphique de Gantt : le graphique de Gantt visualise le parcours de la requête. Vous voyez une étendue parente réussie pour le routage initial de l'agent, mais une étendue invoke_connector ayant échoué est imbriquée en dessous et cible spécifiquement le data store Jira Cloud.
4. Passez aux journaux : cliquez sur l'étendue invoke_connector ayant échoué. Dans le volet Détails de la trace, cliquez sur Afficher les journaux.

5. Identifiez la cause racine : 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ésolvez le problème : dans la section Erreurs fréquentes, vous pouvez identifier cette erreur comme une erreur d'accès à une ressource d'utilisateur final manquante. 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 sont entièrement auto-résolvables. Recherchez l'erreur que vous avez rencontrée dans la liste suivante pour déterminer la cause racine et la corriger.

Erreurs d'authentification et d'accès

Ces erreurs se produisent lorsque des problèmes liés aux identifiants, aux étendues ou aux règles administratives 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 d'erreur : HTTP request failed with status code 401 / 401 Unauthorized
• Cause racine : le jeton OAuth a expiré ou n'est pas valide.
• Solution : réautorisez le data store dans les paramètres Gemini Enterprise pour générer un nouveau jeton.

Outil bloqué par un filtre d'action

• Signature d'erreur : Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
• Cause racine : 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.

Étendues OAuth manquantes

• Signatures d'erreur : Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted OU Cause: Insufficient Permission
• Cause racine : l'enregistrement de l'application sur la plate-forme tierce ne comporte pas les étendues requises.
• Solution : un administrateur doit accorder les étendues exactes nommées dans le journal et réautoriser l'application.

Autorisations IAM du projet manquantes

• Signature d'erreur : Access Denied: User does not have [permission] / mcp.tools.call permission
• Cause racine : l'appelant ou le compte de service ne dispose pas des autorisations Google Cloud IAM 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 précisément la durée pendant laquelle ces requêtes limitées sont suspendues avant d'échouer.

Limitation de l'API tierce 429

• Signature d'erreur : Cause: Request has been rate limited
• Cause racine : vous envoyez des requêtes plus rapidement que l'API tierce ne l'autorise.
• Solution : réduisez votre taux de requêtes, mettez en œuvre des stratégies de backoff ou demandez une augmentation de quota au fournisseur tiers.

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

• Signature d'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 racine : le data store dispose de fonctionnalités limitées (par exemple, recherche fédérée uniquement, ingestion uniquement ou recherche uniquement) et ne prend pas en charge les actions.
• 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, bien que l'authentification puisse réussir, 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é tierce

• Signature d'erreur : 422 ... you do not have permission to view [Resource/Users]
• Cause racine : 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 à l'organisation tierce ou réduisez la limite de votre champ d'application de requête.

Accès à une ressource d'utilisateur final manquant

• Signature d'erreur : permission denied: [user] does not have access to [Resource]
• Cause racine : 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 résultent de problèmes d'infrastructure, de délais d'attente ou d'erreurs de configuration du backend, et ne sont généralement pas auto-résolvables.

Point de terminaison tiers lent ou surchargé

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

Erreur de configuration de la liaison des identifiants du serveur MCP

• Signature d'erreur : CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
• Cause racine : il existe un problème de règle côté serveur où la liaison des identifiants du serveur MCP est mal configurée. L'utilisateur ne peut pas agir sur ce problème.
• Solution : contactez l' Google Cloud assistance.

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 collecter les artefacts suivants à partir de vos outils d'observabilité avant d'ouvrir une demande :

• À partir de Cloud Logging : la charge utile complète du journal JSON de l'erreur.
• À partir de Cloud Trace : le jeton d'assistance et les détails spécifiques de l'étendue (y compris l'ID de trace) associés à la requête ayant échoué.
• À partir des journaux d'audit d'utilisation : tous les horodatages de modification IAM ou les modifications de règles pertinents qui ont pu déclencher le problème.