Soluciona problemas relacionados con los almacenes de datos de Gemini Enterprise

Usa esta página para diagnosticar y resolver cualquier problema con los almacenes de datos de Gemini Enterprise. Cuando un almacén de datos no puede recuperar información, puedes depurar el problema de forma independiente siguiendo un recorrido de observabilidad coherente y paso a paso.

Para obtener un panorama completo de un error, comprende cómo funcionan juntas las herramientas de observabilidad de Google Cloud:

  • Cloud Monitoring: Detecta cuándo hay un problema. Úsala para ver tendencias de alto nivel y tasas de errores, y configurar alertas para tus almacenes de datos.
  • Cloud Trace: Descubre dónde se produce el problema. Úsala para ver el ciclo de vida de una solicitud, analizar los intervalos y, además, identificar con exactitud qué paso causó la latencia alta o la falla.
  • Cloud Logging: Explica por qué se produce el problema. Úsala para leer los mensajes de error y las cargas útiles exactos asociados con una solicitud con errores.
  • Registros de auditoría de Cloud: Identifica quién o qué política bloqueó la acción. Úsala para hacer un seguimiento del cumplimiento de la seguridad, los cambios de permisos y las acciones administrativas que podrían estar causando denegaciones de acceso.

Flujo de trabajo de depuración

Cuando investigues un problema con un almacén de datos, sigue este flujo de trabajo secuencial para aislar y resolver la causa raíz:

  1. Verifica las tendencias de la tasa de errores
  2. Busca la solicitud específica que falla
  3. Visualiza la carga útil del error
  4. Comparar datos mediante referencia cruzada los registros de auditoría de uso

  1. En la consola de Google Cloud , ve a la página Explorador de métricas.

    Ir al Explorador de métricas

  2. Revisa tus paneles y los recuentos de solicitudes de almacén de datos, y filtra por ID de herramienta y por ID de motor. Puedes determinar si el problema es un error único o un aumento sistémico generalizado que requiere atención inmediata.

Busca la solicitud específica que falla

  1. En la consola de Google Cloud , ve a la página Explorador de seguimiento:

    Ve al Explorador de seguimiento

    También puedes usar la barra de búsqueda para encontrar esta página.

  2. Examina el diagrama de dispersión para buscar seguimientos con un ícono de error (un signo de exclamación rojo) o una latencia inusualmente alta.
  3. Haz clic en un seguimiento para ver su diagrama de Gantt.
  4. Verifica el intervalo de invoke_connector para ver dónde se detuvo o falló el proceso.
  5. Además, puedes encontrar el token de asistencia único asociado con una solicitud específica. Si necesitas derivar un problema complejo al equipo de asistencia de Google Cloud , comparte este token de asistencia para acelerar la investigación.

Visualiza la carga útil del error

  1. Haz clic en el intervalo con errores en el Explorador de seguimiento.
  2. En el panel de detalles, haz clic en Mostrar registros.
  3. Esto te lleva automáticamente a Cloud Logging, con un filtro para esa solicitud exacta. Aquí, puedes leer la carga útil del registro sin procesar para identificar la firma exacta del error (como RESOURCE_EXHAUSTED o PERMISSION_DENIED).

Compara los registros de auditoría de uso mediante referencia cruzada

Si la carga útil del registro indica un problema de IAM, un permiso faltante o una denegación de permiso, compara tus Registros de auditoría de Cloud con referencia cruzada:

  1. En la consola de Google Cloud , accede a la página Explorador de registros.

    Ve al Explorador de registros

  2. Revisa el historial administrativo. Verifica si tu administrador modificó recientemente un filtro de acciones o revocó un permiso obligatorio.

Ejemplo: Realiza un seguimiento de una solicitud de almacén de datos con errores

Imagina que un usuario le pide a tu agente de Gemini Enterprise que obtenga el estado de un problema de Jira, pero el agente devuelve un mensaje de error genérico. A continuación, se muestra cómo usarías el flujo de trabajo de observabilidad para encontrar la causa raíz:

  1. Verifica las tendencias de errores: Antes de buscar errores individuales, debes saber qué tan extendido está el problema. Abre el Explorador de métricas en Cloud Monitoring y filtra las métricas de solicitud de tu almacén de datos por tool_id: get_issue. Es posible que veas un aumento repentino y masivo de errores RESOURCE_EXHAUSTED. Esto confirma que se trata de un problema sistémico, no solo de un error tipográfico puntual del usuario.
  2. Busca la solicitud con errores: Abre el Explorador de seguimiento y configura el filtro de tiempo en la última hora. En el diagrama de dispersión, verás un clúster de seguimientos con un ícono de error rojo que indica fallas. Haz clic en uno de estos seguimientos recientes para investigarlo.
  3. Examina el diagrama de Gantt: El diagrama de Gantt visualiza el recorrido de la solicitud. Ves un intervalo superior exitoso para el enrutamiento inicial del agente, pero anidado debajo de él hay un intervalo invoke_connector con errores que se orienta específicamente al almacén de datos de Jira Cloud.
  4. Cambia a los registros: Haz clic en el intervalo invoke_connector con errores. En el panel de detalles de Trace, haz clic en Mostrar registros.

  5. Identifica la causa raíz: Se abre el Explorador de registros, filtrado previamente según el ID de seguimiento exacto. Ahora puedes examinar la carga útil del registro que generó el almacén de datos para identificar el error exacto:

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

    En este mensaje de error de carga útil, puedes ver la herramienta específica (get_issue) que falló y el mensaje explícito que indica que el usuario que ejecuta la solicitud no tiene acceso al recurso específico en el sistema de destino.

  6. Resolución: Con la sección Errores comunes, puedes identificar este error como Falta de acceso a los recursos del usuario final. El agente de Gemini Enterprise se conectó correctamente a Jira Cloud, pero Jira Cloud rechazó la consulta porque el usuario no tiene permisos. Para resolver este problema, pídele al administrador de Jira Cloud que le otorgue al usuario acceso al recurso específico.

Errores comunes

Cuando revises las cargas útiles de error en Cloud Logging, concéntrate en las firmas de error generales. La mayoría de los errores de almacén de datos se pueden resolver por completo de forma automática. Busca el error que encontraste en la siguiente lista para determinar la causa raíz y corregirlo.

Errores de autenticación y acceso

Estos errores ocurren cuando hay problemas con las credenciales, los permisos o las políticas administrativas que impiden el acceso a los recursos requeridos. Si encuentras estos errores, los Registros de auditoría de Cloud son útiles para depurar cambios recientes de IAM, actualizaciones de filtros de acciones o permisos revocados.

Token de OAuth vencido o no válido

  • Firma del error: HTTP request failed with status code 401 / 401 Unauthorized
  • Causa raíz: El token de OAuth venció o no es válido.
  • Resolución: Vuelve a autorizar el almacén de datos en la configuración de Gemini Enterprise para generar un token nuevo.

Herramienta bloqueada por un filtro de acciones

  • Firma del error: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Causa raíz: El administrador bloqueó la herramienta con un filtro de acciones.
  • Resolución: El administrador debe actualizar la lista de acciones o herramientas permitidas.

Faltan permisos de OAuth

  • Firmas de error: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted O Cause: Insufficient Permission
  • Causa raíz: Al registro de la aplicación en la plataforma de terceros le faltan los permisos necesarios.
  • Solución: Un administrador debe otorgar los permisos exactos que se indican en el registro y volver a autorizar la app.

Faltan permisos de IAM del proyecto

  • Firma del error: Access Denied: User does not have [permission] / mcp.tools.call permission
  • Causa raíz: Al emisor o a la cuenta de servicio le faltan los permisos de IAM de Google Cloud necesarios en el proyecto de destino.
  • Resolución: Otorga el permiso de IAM indicado al emisor.

Errores de rendimiento y limitación

Estos errores se activan cuando los volúmenes de solicitudes superan los límites establecidos por la API o el servicio de destino. Cloud Trace ayuda a identificar exactamente cuánto tiempo se detienen estas solicitudes limitadas antes de fallar.

Limitación de la API de terceros 429

  • Firma del error: Cause: Request has been rate limited
  • Causa raíz: Estás realizando solicitudes más rápido de lo que permite la API de terceros.
  • Resolución: Reduce el porcentaje de solicitudes, implementa estrategias de retirada o solicita un aumento de cuota al proveedor externo.

No se ve el botón "Habilitar acciones"

  • Firma del error: El botón Habilitar acciones no se ve o está inhabilitado en la consola después de crear un almacén de datos.
  • Causa raíz: El almacén de datos tiene una funcionalidad limitada (como solo búsqueda federada, solo transferencia o solo búsqueda) y no admite acciones.
  • Resolución: No se pueden habilitar las acciones en estos tipos de almacén de datos.

Errores de visibilidad y de recursos

Estos errores indican que, si bien la autenticación puede ser correcta, el usuario o la aplicación no tienen los derechos específicos para ver los datos solicitados o interactuar con ellos.

Restricción de visibilidad de terceros

  • Firma del error: 422 ... you do not have permission to view [Resource/Users]
  • Causa raíz: Una restricción de visibilidad o una política de la organización en la plataforma de terceros impide la recuperación de datos.
  • Resolución: Ajusta la membresía de tu organización de terceros o reduce el límite del alcance de tu consulta.

Falta el acceso a los recursos del usuario final

  • Firma del error: permission denied: [user] does not have access to [Resource]
  • Causa raíz: El usuario final que ejecuta la solicitud no tiene acceso al componente o recurso específico en el sistema de destino.
  • Resolución: Otorga al usuario acceso al recurso directamente dentro del sistema de destino.

Errores del sistema y del servidor

Estos errores se deben a problemas de infraestructura, tiempos de espera o parámetros de configuración incorrectos del backend, y, por lo general, no se resuelven por sí solos.

Extremo de terceros lento o sobrecargado

  • Firma del error: context deadline exceeded
  • Causa raíz: El extremo de terceros es lento o está sobrecargado, lo que provoca que se agote el tiempo de espera de la solicitud de Google.
  • Solución: Vuelve a intentar ejecutar la solicitud. Si el error persiste, comunícate con el equipo de asistencia de Google Cloud para ajustar el tiempo de espera.

Configuración incorrecta de la vinculación de credenciales del servidor de MCP

  • Firma del error: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Causa raíz: Hay un problema de política del servidor en el que la vinculación de credenciales del servidor de MCP está mal configurada. El cliente no puede realizar ninguna acción al respecto.
  • Resolución: Comunícate con el equipo de asistencia de Google Cloud .

Obtén asistencia

Si encuentras un error context deadline exceeded o CredsPermissionException persistente, es posible que debas enviar un ticket de asistencia al equipo de asistencia de Google Cloud .

Para agilizar la resolución, recopila los siguientes artefactos de tus herramientas de observabilidad antes de abrir un ticket:

  • Desde Cloud Logging: Es la carga útil completa del registro JSON del error.
  • Desde Cloud Trace: El token de asistencia y los detalles específicos del intervalo (incluido el ID de seguimiento) asociados con la solicitud con errores.
  • De los registros de auditoría de uso: Cualquier marca de tiempo de modificación de IAM o cambio de política pertinente que pueda haber activado el problema.