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 progressif.

Pour obtenir une vue d'ensemble d'une erreur, découvrez comment Google Cloudles outils d'observabilité fonctionnent 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 étendues et identifier exactement 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 exacts et les charges utiles 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 première :

  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

  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 le segment 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 escalader un problème complexe auprès de Google Cloud l'assistance, partagez ce jeton d'assistance pour accélérer l'enquête.

Afficher la charge utile de l'erreur

  1. Cliquez sur le segment ayant échoué dans Explorateur Trace.
  2. Dans le volet de 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 première :

  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 constaterez peut-être 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 parent 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 le invoke_connector segment ayant échoué. Dans le volet de détails de la trace, cliquez sur Afficher les journaux.

  5. Identifiez la cause première : 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 à la ressource de l'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 première 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 première : 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 première : 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 première : 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 première : 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 exactement 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 première : vous envoyez des requêtes plus rapidement que l'API tierce ne l'autorise.
  • 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.

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 première : 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 étendue de requête.

Accès à la ressource de l'utilisateur final manquant

  • Signature d'erreur : permission denied: [user] does not have access to [Resource]
  • Cause première : 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 première : 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 première : 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 résoudre 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 du segment (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 règles pertinents qui ont pu déclencher le problème.