Cómo acceder a los seguimientos y los intervalos

En este documento, se describe cómo acceder a los seguimientos y los intervalos generados por tu app de Gemini Enterprise y cómo visualizarlos. 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, por ejemplo, cuando se usa 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 los 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 a través de diferentes servicios y componentes. Por ejemplo, un seguimiento representa todo el ciclo de vida de una solicitud. Esto incluye un usuario que hace una pregunta al asistente de Gemini Enterprise, el asistente de Gemini Enterprise que responde, 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 una 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 juntas 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 a 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 Google Cloud consola.

• 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 las configuraciones a nivel de la app (para el agente Core Assistant) o dentro de 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 generados por tu app de Gemini Enterprise se almacenan en Cloud Trace en tu Google Cloud proyecto, y su retención se rige por Cloud Trace. De forma predeterminada, Cloud Trace retiene 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 obtener los valores de retención autorizados y más recientes, 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 seguimiento, sigue estos pasos:

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

   Ir al Explorador de seguimiento

2. Selecciona el Google Cloud proyecto 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 seguimiento, 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 facetados:
  • Servicio: Filtra por AssistantService o connectorsexecution para aislar las rutas de solicitud del agente de la plataforma y del conector de datos.
  • Intervalo: Filtra por /AssistantService.StreamAssist para ubicar los intervalos raíz de la interacción del usuario o busca intervalos secundarios como execute_tool <tool_name> y invoke_connector <connector>.
• Búsqueda directa de ID de seguimiento: Busca seguimientos directamente con el ID de seguimiento W3C estándar de 32 caracteres, que se puede extraer de los encabezados de respuesta x-cloud-trace-context de StreamAssist.
• Atributos personalizados: Realiza consultas con el gemini_enterprise.assist_token atributo en los intervalos execute_tool o invoke_connector para asignar tokens de asistencia heredados a nivel de interacción a la cascada de seguimiento W3C.
• Atributos de recursos: Cada intervalo exportado incluye cloud.region, el
• Atributos de recursos: Cada intervalo exportado incluye el cloud.region atributo. Este atributo representa la ubicación de servicio de Gemini Enterprise que controló la solicitud, como global, us o eu. Puedes filtrar por este atributo para comparar el rendimiento en diferentes 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 Aplica 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 Core Assistant, los agentes creados por empleados de Workflow Builder y los agentes de Deep Research.

Para acceder a los seguimientos de un agente, sigue estos pasos:

1. En la Google Cloud consola, 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 (actualmente, se muestra Sin configurar).
• ID de intervalo de seguimiento: Es el identificador único del intervalo de seguimiento. Haz clic en el vínculo del ID de intervalo para obtener más detalles.
• Nombre del intervalo: Es una breve descripción del trabajo que realiza el intervalo. Algunos ejemplos de intervalos para los conectores de datos de Gemini Enterprise incluyen los siguientes:
  • 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>: La capa de ejecución de conectores lo genera para representar la lógica de solicitud al conector específico (por ejemplo, invoke_connector jira o invoke_connector servicenow), que reemplaza los intervalos RPC predeterminados del servidor.
• Tipo de intervalo: Es el tipo de intervalo. Las opciones incluyen las siguientes:
  • 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 de entrada o el mensaje que se envía al intervalo, si corresponde.
• Salida: Es el resultado de salida que devuelve el intervalo, si corresponde.
• Hora de inicio: Es la marca de tiempo exacta en la que el intervalo comenzó a ejecutarse.

Vista detallada del seguimiento

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

1. Resumen: Consulta los metadatos de referencia, incluidos la Hora de inicio, la Duración y el recuento total de Intervalos. Puedes hacer clic para Ver en Cloud Trace o alternar entre los botones de vista Gráfico y Cronograma.
2. Visualizaciones: Alterna entre una jerarquía gráfica o una vista de línea de tiempo que muestre las relaciones de elementos superiores y secundarios 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 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 están configurados.
   • Entrada y salida: Cargas útiles completas de solicitud y respuesta.
   • Registros y eventos: Lista de eventos que ocurrieron durante la ejecución de este intervalo.
   • Seguimientos de pila: Detalles del error si falla la ejecución de un intervalo.
   • Metadatos y vínculos: Vínculos que hacen referencia a entidades relacionadas del Explorador de Cloud.
   • Atributos: Etiquetas de recursos y parámetros de observabilidad adicionales de par clave-valor.

Jerarquía de intervalos de elementos superiores y secundarios

Para la ejecución de conectores de datos, el anidamiento de intervalos de elementos superiores y secundarios dentro de un solo seguimiento W3C ayuda a identificar exactamente dónde se producen la latencia o los errores:

1. /AssistantService.StreamAssist: Es el intervalo raíz de la plataforma 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 convenciones semánticas de IA generativa experimental

Advertencia: La telemetría de convenciones semánticas 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 deben usar 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 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 la instrucción y la respuesta en los intervalos de seguimiento (como el texto de la instrucción y las respuestas generadas) solo aparece cuando la configuración de observabilidad permite el registro de las entradas de la instrucción y las salidas de la respuesta. De lo contrario, el contenido se redacta o se omite. Para cambiar esta configuración, consulta Administra la configuración de observabilidad.