Cómo acceder a los seguimientos y los intervalos

En este documento, se describe cómo acceder y ver los seguimientos y los intervalos que genera tu app de Gemini Enterprise. Los seguimientos y los intervalos proporcionan estadísticas detalladas sobre el rendimiento y el flujo de ejecución de las solicitudes dentro de tu aplicación, como cuando usas el asistente o los agentes.

Puedes ver los datos de seguimiento con el Explorador de seguimiento o directamente en los agentes individuales con la pestaña Seguimientos del agente.

Conceptos clave

En esta sección, se presentan conceptos clave relacionados con la observabilidad en Gemini Enterprise.

Concepto	Descripción
Seguimiento	Un seguimiento es una colección de intervalos que representa una sola solicitud o transacción a medida que fluye por diferentes servicios y componentes. Por ejemplo, un seguimiento representa todo el ciclo de vida de una solicitud. Esto incluye que un usuario haga una pregunta al asistente de Gemini Enterprise, que el asistente de Gemini Enterprise responda y cualquier acción posterior que se active con la respuesta, como enviar un correo electrónico.
Intervalo	Un intervalo es una sola unidad de trabajo cronometrada dentro de un seguimiento. Representa una operación específica, como una llamada a función, una solicitud a la API o una consulta a la base de datos. Cada intervalo incluye detalles como sus horas de inicio y finalización, un ID único y su relación con otros intervalos. Estas relaciones forman un seguimiento.
Registros de intervalos	Los registros de intervalos son mensajes o eventos de formato libre con marca de tiempo asociados con un intervalo específico. Proporcionan información contextual detallada sobre la ejecución de un intervalo, lo que ayuda a los usuarios a depurar problemas y comprender el flujo de una solicitud.

Antes de comenzar

Asegúrate de tener lo siguiente:

• El rol de administrador de Gemini Enterprise o el rol de usuario de Gemini Enterprise de la consola de Google Cloud .

• Una app web de Gemini Enterprise existente. Para obtener información sobre cómo crear una app nueva, consulta Crea una app.

• Para acceder a los seguimientos, debes tener el rol de Usuario de Cloud Trace (roles/cloudtrace.user).

• Habilita el parámetro de configuración de observabilidad Habilitar la instrumentación de seguimientos y registros de OpenTelemetry. Según el tipo de agente, puedes habilitar esta opción en los parámetros de configuración a nivel de la app (para el agente Asistente principal) o en la pestaña Configuración del agente (para los agentes creados por empleados de Workflow Builder y los agentes de Deep Research). Para obtener más información, consulta Administra la configuración de observabilidad.

Retención de datos

Los seguimientos y los intervalos que genera tu app de Gemini Enterprise se almacenan en Cloud Trace en tu proyecto de Google Cloud , y su retención se rige por Cloud Trace. De forma predeterminada, Cloud Trace conserva los datos de intervalos durante 30 días. Los datos más antiguos que el período de retención se borran automáticamente. Para conocer los valores de retención autorizados y más actualizados, consulta Períodos de retención de Cloud Trace en la documentación de Cuotas y límites de Cloud Trace.

Accede a los seguimientos en el Explorador de seguimiento

Para acceder a los seguimientos y los intervalos con el Explorador de Trace, sigue estos pasos:

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

   Ir al Explorador de seguimiento

2. Selecciona el proyecto de Google Cloud en el que se creó tu app de Gemini Enterprise. Verás todos los intervalos de tu proyecto.

3. En la tabla, haz clic en un ID de intervalo para ver los detalles del seguimiento, incluida la duración del intervalo y otros atributos.

   Nota: Para obtener más información sobre el uso del Explorador de Trace, consulta Busca y explora seguimientos.

   

Filtra y busca seguimientos

En el Explorador de seguimiento de tu proyecto, puedes aislar y analizar las ejecuciones del agente de Gemini Enterprise y del conector de datos con estos filtros, parámetros de consulta y atributos:

• Filtros por facetas:
  • Servicio: Filtra por AssistantService o connectorsexecution para aislar las rutas de solicitud del agente de la plataforma y del conector de datos.
  • Tramo: Filtra por /AssistantService.StreamAssist para ubicar los tramos de turno del usuario raíz o busca tramos secundarios como execute_tool <tool_name> y invoke_connector <connector>.
• Búsqueda directa de ID de seguimiento: Encuentra seguimientos directamente con el ID de seguimiento estándar de W3C de 32 caracteres, que se puede extraer de los encabezados de respuesta x-cloud-trace-context de StreamAssist.
• Atributos personalizados: Realiza consultas por el atributo gemini_enterprise.assist_token en los intervalos execute_tool o invoke_connector para asignar tokens de asistencia heredados a nivel de turno a la cascada de seguimiento de W3C.
• Atributos de recursos: Cada intervalo exportado lleva cloud.region, el
• Atributos de recursos: Cada intervalo exportado lleva el atributo cloud.region. Este atributo representa la ubicación de entrega de Gemini Enterprise que controló la solicitud, como global, us o eu. Puedes filtrar por este atributo para comparar el rendimiento en distintas regiones. Esta comparación es útil cuando un conector de datos tiene éxito en una ubicación, pero falla en otra. Este valor representa la ubicación que entrega tu app, no la región que aloja la fuente de datos de terceros. Para aplicar este filtro, consulta Cómo aplicar filtros de intervalos.

Accede a los seguimientos de los agentes

También puedes ver los intervalos de seguimiento directamente para agentes individuales en la pestaña Seguimientos del agente, que muestra un resumen cronológico detallado de los registros de seguimiento de intervalos y las estructuras de ejecución de elementos superiores y secundarios.

Nota: La pestaña Seguimientos está disponible para el agente Asistente principal, los agentes creados por empleados de Workflow Builder y los agentes de Deep Research.

Para acceder a los seguimientos de un agente, haz lo siguiente:

1. En la consola de Google Cloud , navega a tu app y, luego, haz clic en Agentes.
2. Selecciona el agente que deseas inspeccionar y, luego, haz clic en la pestaña Seguimientos.

Tabla de resumen de seguimientos

En la tabla principal de la pestaña Seguimientos, se muestra la siguiente información para cada intervalo de seguimiento:

• Estado: Es el estado actual del seguimiento (en este momento, se muestra Sin configurar).
• ID del intervalo de seguimiento: Es el identificador único del intervalo de seguimiento. Haz clic en el vínculo del ID del intervalo para desglosar sus detalles.
• Nombre del intervalo: Es una breve descripción del trabajo que realiza el intervalo. Estos son algunos ejemplos de intervalos para los conectores de datos de Gemini Enterprise:
  • execute_tool <tool_name>: Se emite durante la capa de envío de herramientas en el entorno de ejecución del agente (por ejemplo, execute_tool federated_search).
  • invoke_connector <connector>: Generado por la capa de ejecución de conectores para representar la lógica de solicitud al conector específico (por ejemplo, invoke_connector jira o invoke_connector servicenow), que reemplaza los intervalos de RPC predeterminados del lado del servicio.
• Tipo de intervalo: Es el tipo de intervalo. Estas son algunas opciones:
  • Agent to Tool: Es una invocación del agente a una herramienta externa (se reutiliza para las operaciones execute_tool y invoke_connector).
  • Invoke Agent: Es una invocación de un agente.
  • Agent to Model: Es una solicitud del agente a un modelo de lenguaje grande.
• Duración: Es el tiempo que se tarda en completar el intervalo de seguimiento (en minutos).
• Entrada: Son los datos o el mensaje de entrada que se envían al intervalo, si los hay.
• Resultado: El resultado que devuelve el intervalo, si lo hay.
• Hora de inicio: Es la marca de tiempo exacta en la que comenzó la ejecución del intervalo.

Vista detallada del seguimiento

Si haces clic en un ID de intervalo de seguimiento, se abrirá una página de detalles con lo siguiente:

1. Resumen: Consulta los metadatos del modelo de referencia, incluidos la Hora de inicio, la Duración y el recuento total de Intervalos. Puedes hacer clic en Ver en Cloud Trace o cambiar entre los botones de vista Gráfico y Línea de tiempo.
2. Visualizaciones: Alterna entre una jerarquía gráfica o una vista de línea de tiempo que muestre las relaciones de superior-secundario de todos los intervalos de seguimiento.
3. Detalles del intervalo seleccionado: Selecciona un solo intervalo para mostrar secciones detalladas, que pueden incluir lo siguiente:
   • Resumen: Muestra el nombre del intervalo, el servicio de destino, el recuento de intervalos totales con esta acción y la duración total (en segundos).
   • Registros: Consulta los detalles de los eventos relevantes si están configurados. Haz clic en Ver registros para navegar directamente a los registros estándar.
   • Evaluación: Muestra los resultados de la evaluación, si se configuró.
   • Entrada y salida: Cargas útiles completas de solicitud y respuesta.
   • Registros y eventos: Es una lista de los eventos que ocurrieron durante la ejecución de este intervalo.
   • Seguimientos de pila: Son los detalles del error si falla la ejecución de un intervalo.
   • Metadatos y vínculos: Son vínculos que hacen referencia a entidades relacionadas del explorador de Cloud.
   • Atributos: Son etiquetas de recursos y parámetros adicionales de observabilidad de pares clave-valor.

Jerarquía de intervalos superior-secundario

Para la ejecución de conectores de datos, el anidamiento de intervalos superiores e inferiores dentro de un solo seguimiento de W3C ayuda a identificar con exactitud dónde se producen la latencia o los errores:

1. /AssistantService.StreamAssist: Es el intervalo raíz de la plataforma de C++ que inicia la solicitud.
2. invoke_agent core_assistant: Es el intervalo de ejecución del agente.
3. execute_tool <tool_name>: Es el intervalo de ejecución de la herramienta activa (por ejemplo, execute_tool federated_search).
4. invoke_connector <connector_name> (por ejemplo, invoke_connector jira o invoke_connector servicenow): Es el intervalo de ejecución de los conectores, que representa el ciclo de vida de la solicitud al extremo de terceros.

Telemetría de la convención semántica de IA generativa experimental

Advertencia: La telemetría de la convención semántica de IA generativa que se describe en esta sección es experimental. Los atributos, los esquemas y los formatos están sujetos a cambios en versiones futuras.

Además de la telemetría estable, los intervalos de seguimiento de Gemini Enterprise incluyen metadatos más enriquecidos basados en las convenciones semánticas de IA generativa de OpenTelemetry. OpenTelemetry clasifica estas convenciones como Estado de desarrollo. Ese estado se aplica a las especificaciones en etapa inicial que pueden cambiar o quitarse, y no se debe confiar en ellas en producción. Debido a que estas convenciones aún no son estables, esta telemetría de Gemini Enterprise es experimental. Estos intervalos incluyen atributos de gen_ai.* que describen la actividad del agente, el modelo y la herramienta, como la ejecución del agente y la herramienta, y los pasos de instrucción y respuesta.

El contenido de las instrucciones y las respuestas en los intervalos de seguimiento (como el texto de las instrucciones y las respuestas generadas) solo aparece cuando la configuración de observabilidad permite el registro de las entradas de instrucciones y las salidas de respuestas. De lo contrario, el contenido se oculta o se omite. Para cambiar estos parámetros de configuración, consulta Administra la configuración de observabilidad.