Solução de problemas de armazenamento de dados do Gemini Enterprise

Use esta página para diagnosticar e resolver problemas com os repositórios de dados do Gemini Enterprise. Quando um repositório de dados não consegue recuperar informações, você pode depurar o problema de forma independente seguindo uma jornada de observabilidade coesa e detalhada.

Para ter uma visão completa de um erro, entenda como Google Cloud's as ferramentas de observabilidade funcionam juntas:

  • Cloud Monitoring: detecta quando há um problema. Use essa ferramenta para conferir tendências gerais, taxas de erros e configurar alertas para seus repositórios de dados.
  • Cloud Trace: descobre onde o problema está ocorrendo. Use essa ferramenta para conferir o ciclo de vida de uma solicitação, analisar intervalos e identificar exatamente qual etapa causou alta latência ou falha.
  • Cloud Logging: Explica por que o problema está ocorrendo. Use essa ferramenta para ler as mensagens de erro exatas e os payloads associados a uma solicitação com falha.
  • Registros de auditoria do Cloud: identifica quem ou qual política bloqueou a ação. Use essa ferramenta para acompanhar a conformidade de segurança, as mudanças de permissão e as ações administrativas que podem estar causando negações de acesso.

Fluxo de trabalho de depuração

Ao investigar um problema de repositório de dados, siga este fluxo de trabalho sequencial para isolar e resolver a causa raiz:

  1. Verificar as tendências de taxa de erros
  2. Encontrar a solicitação com falha específica
  3. Conferir o payload de erro
  4. Comparar registros de auditoria de uso

  1. No Google Cloud console do, acesse a página Metrics Explorer.

    Acessar o Metrics Explorer

  2. Confira seus painéis e analise as contagens de solicitações do repositório de dados e filtre por ID da ferramenta e ID do mecanismo. Você pode determinar se o problema é um erro único ou um pico sistêmico generalizado que exige atenção imediata.

Encontrar a solicitação com falha específica

  1. No Google Cloud console do, acesse a página Explorador de traces:

    Acessar o Explorador de traces

    Também é possível encontrar essa página usando a barra de pesquisa.

  2. Examine o gráfico de dispersão para traces com um ícone de erro (um ponto de exclamação vermelho) ou latência muito alta.
  3. Clique em um trace para conferir o gráfico de Gantt.
  4. Confira o intervalo invoke_connector para saber onde o processo foi interrompido ou falhou.
  5. Além disso, você pode encontrar o token de assistência exclusivo associado a uma solicitação específica. Se precisar encaminhar um problema complexo para o Google Cloud suporte, compartilhe esse token de assistência para acelerar a investigação.

Conferir o payload de erro

  1. Clique no intervalo com falha no Explorador de traces.
  2. No painel de detalhes, clique em Mostrar registros.
  3. Isso direciona você automaticamente para o Cloud Logging, filtrado para essa solicitação exata. Aqui, você pode ler o payload de registro bruto para identificar a assinatura de erro exata (como RESOURCE_EXHAUSTED ou PERMISSION_DENIED).

Comparar registros de auditoria de uso

Se o payload de registro indicar um problema do IAM, um escopo ausente ou uma negação de permissão, compare seus Registros de auditoria do Cloud:

  1. No Google Cloud console do, acesse a página Análise de registros.

    Acessar a Análise de registros

  2. Analise o histórico administrativo. Verifique se o administrador modificou recentemente um filtro de ação ou revogou uma permissão necessária.

Exemplo: rastrear uma solicitação de repositório de dados com falha

Imagine que um usuário peça ao agente do Gemini Enterprise o status de um problema do Jira, mas o agente retorne uma mensagem de falha genérica. Veja como usar o fluxo de trabalho de observabilidade para encontrar a causa raiz:

  1. Verificar as tendências de erros:antes de procurar erros individuais, você precisa saber a extensão do problema. Abra o Metrics Explorer no Cloud Monitoring e filtre as métricas de solicitação do repositório de dados por tool_id: get_issue. Você pode notar um pico repentino e enorme nos erros RESOURCE_EXHAUSTED. Isso confirma que é um problema sistêmico, não apenas um erro de digitação do usuário.
  2. Encontrar a solicitação com falha:abra o Explorador de traces e defina o filtro de tempo para a última hora. No gráfico de dispersão, você vai notar um cluster de traces com um ícone de erro vermelho indicando falhas. Clique em um desses traces recentes para investigar.
  3. Examinar o gráfico de Gantt:o gráfico de Gantt visualiza a jornada da solicitação. Você vai notar um intervalo pai bem-sucedido para o roteamento inicial do agente, mas aninhado abaixo dele há um intervalo invoke_connector com falha direcionado especificamente ao repositório de dados do Jira Cloud.
  4. Fazer a transição para os registros:clique no intervalo invoke_connector com falha. No painel de detalhes do trace, clique em Mostrar registros.

  5. Identificar a causa raiz:a Análise de registros é aberta, pré-filtrada para o ID do trace exato. Agora você pode examinar o payload de registro gerado pelo repositório de dados para identificar o erro exato:

    
"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\":{}}"

    Nessa mensagem de erro do payload, você pode conferir a ferramenta específica (get_issue) que falhou e a mensagem explícita indicando que o usuário que executa a solicitação não tem acesso ao recurso específico no sistema de destino.

  6. Resolver:usando a seção Erros comuns, você pode identificar isso como um erro de acesso ao recurso do usuário final ausente. O agente do Gemini Enterprise se conectou ao Jira Cloud, mas o Jira Cloud rejeitou a consulta porque o usuário não tem permissões. Para resolver isso, peça ao administrador do Jira Cloud para conceder ao usuário acesso ao recurso específico.

Erros comuns

Ao analisar os payloads de erro no Cloud Logging, concentre-se nas assinaturas de erro gerais. A maioria dos erros de repositório de dados pode ser resolvida por conta própria. Encontre o erro que ocorreu na lista a seguir para determinar a causa raiz e a correção.

Erros de autenticação e acesso

Esses erros ocorrem quando há problemas com credenciais, escopos ou políticas administrativas que impedem o acesso aos recursos necessários. Se você encontrar esses erros, os registros de auditoria do Cloud serão úteis para depurar mudanças recentes do IAM, atualizações de filtro de ação ou permissões revogadas.

Token OAuth expirado ou inválido

  • Assinatura de erro:HTTP request failed with status code 401 / 401 Unauthorized
  • Causa raiz:o token OAuth expirou ou é inválido.
  • Solução:reautorize o repositório de dados nas configurações do Gemini Enterprise para gerar um novo token.

Ferramenta bloqueada por um filtro de ação

  • Assinatura de erro: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Causa raiz:o administrador bloqueou a ferramenta usando um filtro de ação.
  • Solução:o administrador precisa atualizar a lista de permissões de ação ou ferramenta.

Escopos do OAuth ausentes

  • Assinaturas de erro:Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted OU Cause: Insufficient Permission
  • Causa raiz:o registro do aplicativo na plataforma de terceiros não tem os escopos necessários.
  • Solução:um administrador precisa conceder os escopos exatos nomeados no registro e reautorizar o app.

Permissões de projeto do IAM ausentes

  • Assinatura de erro:Access Denied: User does not have [permission] / mcp.tools.call permission
  • Causa raiz: o autor da chamada ou a conta de serviço não tem as permissões necessárias do Google Cloud IAM no projeto de destino.
  • Solução:conceda a permissão do IAM nomeada ao autor da chamada.

Erros de desempenho e limitação

Esses erros são acionados quando os volumes de solicitação excedem os limites definidos pela API ou serviço de destino. O Cloud Trace ajuda a identificar exatamente quanto tempo essas solicitações limitadas ficam pendentes antes de falharem.

Limitação da API de terceiros 429

  • Assinatura de erro:Cause: Request has been rate limited
  • Causa raiz:você está fazendo solicitações mais rápido do que a API de terceiros permite.
  • Solução:reduza a taxa de solicitações, implemente estratégias de espera ou peça um aumento de cota ao provedor de terceiros.

Erros de visibilidade e recursos

Esses erros indicam que, embora a autenticação possa ser bem-sucedida, o usuário ou aplicativo não tem os direitos específicos para visualizar ou interagir com os dados solicitados.

Restrição de visibilidade de terceiros

  • Assinatura de erro:422 ... you do not have permission to view [Resource/Users]
  • Causa raiz:uma restrição de visibilidade ou política da organização na plataforma de terceiros está impedindo a recuperação de dados.
  • Solução:ajuste a participação da organização de terceiros ou reduza o limite do escopo da consulta.

Acesso ao recurso do usuário final ausente

  • Assinatura de erro:permission denied: [user] does not have access to [Resource]
  • Causa raiz:o usuário final que executa a solicitação não tem acesso ao componente ou recurso específico no sistema de destino.
  • Solução:conceda ao usuário acesso ao recurso diretamente no sistema de destino.

Erros de sistema e do lado do servidor

Esses erros resultam de problemas de infraestrutura, tempos limite ou configurações incorretas de back-end e normalmente não podem ser resolvidos por conta própria.

Endpoint de terceiros lento ou sobrecarregado

  • Assinatura de erro:context deadline exceeded
  • Causa raiz:o endpoint de terceiros está lento ou sobrecarregado, fazendo com que a solicitação do Google atinja o tempo limite.
  • Solução:tente fazer a solicitação novamente. Se o erro persistir, entre em contato com o Google Cloud suporte para ajustar o tempo limite.

Configuração incorreta da vinculação de credenciais do servidor MCP

  • Assinatura de erro:CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Causa raiz:há um problema de política do lado do servidor em que a vinculação de credenciais do servidor MCP está configurada incorretamente. Isso não pode ser resolvido pelo cliente.
  • Solução:entre em contato com o Google Cloud suporte.

Receber suporte

Se você encontrar um erro persistente context deadline exceeded ou um erro CredsPermissionException, talvez seja necessário registrar um tíquete de suporte com Google Cloud o suporte.

Para acelerar a resolução, colete os seguintes artefatos das ferramentas de observabilidade antes de abrir um tíquete:

  • Do Cloud Logging:o payload de registro JSON completo do erro.
  • Do Cloud Trace:o token de assistência e os detalhes específicos do intervalo (incluindo o ID do trace) associados à solicitação com falha.
  • Dos registros de auditoria de uso:todos os carimbos de data/hora de modificação do IAM relevantes ou mudanças de política que possam ter acionado o problema.