Cómo buscar y explorar registros

Para ver una representación agregada de tus datos de seguimiento, o bien para buscar y explorar seguimientos individuales o que contengan etiquetas específicas, usa la página del Explorador de registros.

En la siguiente captura de pantalla, se muestra cómo se visualizan los datos de seguimiento:

Esta función solo se admite para Google Cloud proyectos. Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.

Acerca de la página Explorador de seguimiento

Para ayudarte a identificar tendencias y patrones en tus datos de seguimiento, los datos de latencia se agregan y se muestran en gráficos. El mapa de calor usa el color para representar la cantidad de intervalos en una celda. Una celda con muchos tramos tiene un color más oscuro que una con pocos tramos. La información sobre herramientas de cada celda muestra la latencia y otra información. También puedes ver los percentiles de latencia y la información de la tasa de intervalo.

Cuando investigues un problema, es posible que quieras ver un registro específico o solo los intervalos con ciertas propiedades:

• Para restringir los intervalos que se muestran, aplica filtros. Por ejemplo, puedes filtrar por servicio, aplicación, estado de error y otras propiedades.

• Para mostrar un registro específico, usa la opción Buscar registro de la barra de herramientas pageview.

Para identificar valores atípicos y ver los detalles de los intervalos individuales, usa la sección tabular:

• Puedes ordenar las filas de las pestañas Intervalos y Agrupados por el encabezado de duración.

• Para comprender cuántos intervalos generan los diferentes servicios, usa la pestaña Agrupado. Cada fila corresponde a un servicio y a un nombre de intervalo, y, para cada entrada, se muestran las estadísticas de latencia.

Para explorar los detalles de un intervalo o una agrupación, selecciona la entrada de una fila en la sección tabular. Se abrirá un menú desplegable que muestra el intervalo en el contexto de su registro. En esta vista, puedes explorar el intervalo, sus atributos y ver los eventos y los datos de registro. También puedes buscar palabras clave en los intervalos y atributos del registro.

Los datos de seguimiento de los que depende la página del Explorador de seguimiento son los siguientes:

• Son los proyectos en los que se buscan datos de seguimiento. De forma predeterminada, el sistema solo busca datos de seguimiento en el proyecto seleccionado por el selector de proyectos. Sin embargo, puedes configurar la página para que busque en la lista de proyectos en un permiso de seguimiento.
• Tus permisos de Identity and Access Management (IAM) en los proyectos buscados Si no tienes permiso para ver los datos de seguimiento de un proyecto, la consola de Google Cloud muestra un mensaje de advertencia y no se muestran los datos de ese proyecto.
• Es el parámetro de configuración del intervalo de tiempo.
• Los filtros que aplicas

En el resto de esta página, se proporciona más información para encontrar y explorar tus datos de registro.

Antes de comenzar

Para obtener los permisos que necesitas para ver los datos de seguimiento con la consola de Google Cloud y seleccionar un alcance de seguimiento, pídele a tu administrador que te otorgue el rol de IAM deUsuario de Cloud Trace (roles/cloudtrace.user) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para ver los datos de seguimiento con la consola de Google Cloud y seleccionar un alcance de seguimiento. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para ver los datos de seguimiento con la consola de Google Cloud y seleccionar un alcance de seguimiento:

• Para seleccionar un alcance de seguimiento, haz lo siguiente: cloudtrace.traceScopes.[get, list]
• Para leer el alcance del registro predeterminado, haz lo siguiente: observability.scopes.get

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre los roles, consulta Controla el acceso con Identity and Access Management.

Cómo ver datos de seguimiento agregados

Para ver la información agregada sobre tus datos de seguimiento, haz lo siguiente:

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.

   Es posible que pasen varios minutos después de que se escriban los primeros datos de seguimiento en un proyecto de Google Cloud antes de que esos datos estén disponibles para su visualización. Si no ves ningún dato de seguimiento después de esperar unos minutos, es posible que tu proyecto no tenga datos para mostrar o que haya un problema de configuración. Si deseas obtener información para resolver estos problemas, consulta Solución de problemas: No hay datos en la interfaz de Trace.

2. Configura la página Explorador de seguimiento:

   1. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto de Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host o el proyecto de administración de App Hub.

   2. Opcional: Configura qué proyectos se buscan para obtener datos de seguimiento con el elemento Alcance:

      • Para mostrar los datos de seguimiento almacenados en tu proyecto, configura el primer menú del elemento Scope en Project o en _Default. Estos dos parámetros de configuración son equivalentes.

      • Para mostrar los datos de seguimiento almacenados en varios proyectos, expande el primer menú del elemento Alcance, selecciona Alcance del seguimiento y, luego, selecciona el alcance del seguimiento que enumera esos proyectos. Después de realizar la selección, el menú Alcance muestra un ícono de alcance de seguimiento, , y el nombre del alcance de seguimiento seleccionado.

      Los datos que se muestran dependen de tus roles de IAM en los proyectos buscados. Por ejemplo, si los proyectos en los que se realizó la búsqueda incluyen un proyecto Google Cloud al que no tienes acceso, no se devolverán datos de seguimiento para ese proyecto.

      Para obtener más información, consulta Crea y administra ámbitos de seguimiento.

   3. Opcional: Actualiza el período con el selector de período o con el puntero para destacar un rango en el eje X.

      Por ejemplo, puedes establecer este selector en Últimas 2 semanas cuando quieras ver si hay tendencias en los datos de latencia. Los datos de los tramos se almacenan durante 30 días.

3. Explora el mapa de calor:

   • Usa el color para identificar tendencias y valores atípicos. Una celda con muchos tramos tiene un color más oscuro que una con pocos tramos.

   • Consulta los detalles de la celda con la sugerencia de la celda. La información sobre herramientas enumera la cantidad de tramos, la fecha y la hora, y el intervalo de tiempo de la celda.

     Nota: Si seleccionas una celda en el mapa de calor, se actualizará la tabla que enumera los períodos individuales o las agrupaciones de períodos.

4. Explora los percentiles de latencia y las tasas de error:

   • Para ver las tendencias de latencia, configura el menú Vista del gráfico en Duración del intervalo (percentil). En el gráfico de duración, se muestran los percentiles 50, 90, 95 y 99.

   • Para ver el estado de respuesta como una función del tiempo, configura el menú Vista de gráfico en Tasa de intervalo. En el gráfico, se muestra la tasa de tramos que se envían a tu proyecto.

5. Para encontrar valores atípicos, selecciona la pestaña Intervalos y ordena la tabla por duración.

   Si quieres obtener más información sobre un intervalo en particular, selecciónalo. Se abrirá un menú desplegable que muestra el intervalo en el contexto de su registro. Luego, puedes explorar el intervalo y el registro.

6. Para explorar la cantidad de tramos generados para cada servicio, junto con información estadística, selecciona la pestaña Agrupado:

   • Cada fila corresponde a un servicio y un nombre de intervalo específicos.
   • Puedes ordenar las filas por el encabezado de duración.

   Si quieres obtener más información sobre una agrupación en particular, selecciona el nombre del intervalo de una fila. Se abrirá un menú desplegable que muestra el intervalo en el contexto de su registro. Luego, puedes explorar el intervalo y el registro de seguimiento.

7. Para restringir los intervalos que se muestran, agrega filtros. Para obtener más información sobre cómo filtrar tus datos de registro, consulta la siguiente sección.

Cómo filtrar tus datos de registro

Para mostrar solo la información que te interesa, aplica filtros. Los filtros restringen los datos que se muestran. Por ejemplo, puedes filtrar por nombre del servicio y por estado. O bien, si implementaste aplicaciones en App Hub, es posible que desees ver los datos de seguimiento solo para la aplicación o para un servicio o una carga de trabajo específicos que formen parte de la aplicación.

Cuando agregas o quitas un filtro, se actualizan los datos que se muestran en la página del Explorador de Trace y solo se muestran los intervalos que coinciden con todos los filtros aplicados.

Cómo filtrar un registro por ID

Cuando solucionas problemas relacionados con un incidente o una falla, es posible que conozcas el ID de seguimiento. Para explorar ese registro, ve a la barra de herramientas, haz clic en pageview Buscar registro y, luego, ingresa el ID de registro.

Cuando ingresas un ID válido, se abre el menú desplegable Detalles y se muestra información sobre el registro y sus intervalos. Puedes usar las opciones de ese panel para explorar el registro. Por ejemplo, puedes buscar palabras clave en los tramos.

Nota: Si ingresas un ID de seguimiento que no se encuentra, es posible que los datos de seguimiento se almacenen en un proyecto en el que no se realiza la búsqueda en la página Explorador de registros, o bien es posible que no tengas un rol de IAM que te permita ver los datos de seguimiento. Para resolver estos errores, identifica los proyectos que almacenan los datos de seguimiento. Para cada proyecto, verifica que tu rol de IAM te permita ver los datos de seguimiento y, luego, asegúrate de que el elemento Alcance esté configurado para buscar todos los proyectos que almacenan tus datos de seguimiento. Para obtener más información, consulta Cómo actualizar la lista de proyectos en los que se buscan datos de seguimiento.

Cómo aplicar filtros de tramo

En el panel Span filters, se enumeran los filtros más comunes. Puedes seleccionar varias entradas de cualquier subcategoría. A medida que agregas o quitas filtros, también se actualiza la barra de Filtro.

Los valores de todos los menús se derivan de los datos de registro. Cuando un menú incluye una opción sin texto, esa opción hace referencia a los tramos que no incluyen el atributo correspondiente.

Por lo general, están disponibles los siguientes filtros de intervalo:

• Servicio de OpenTelemetry: Filtra por el atributo service.name.
• Nombre del intervalo: Es el nombre del intervalo.
• Estado del intervalo: Es el estado de la solicitud. Para obtener información sobre los valores, consulta la documentación de SpanStatus de OpenTelemetry.
• Duración: Es la duración del intervalo.
• Tipo de tramo: Describe las relaciones entre los tramos. Para obtener información sobre los valores, consulta la documentación de SpanKind de OpenTelemetry.
• Solicitud de App Hub: Filtra por el atributo de recurso gcp.apphub.application.id.
• Servicio de App Hub: Filtra por el atributo de recurso gcp.apphub.service.id.
• Carga de trabajo de App Hub: Filtra por el atributo de recurso gcp.apphub.workload.id.

Si deseas filtrar por un atributo que no aparece en el panel Span filters, usa la barra Filter.

Usa la barra de filtros

La barra de Filtro te permite aplicar un filtro con una clave y un valor predefinidos que selecciones, o bien puedes ingresar la clave y el valor.

Para agregar un filtro, selecciona Agregar filtro y, luego, haz una de las siguientes acciones:

• Selecciona una clave definida, como Nombre del tramo, y, luego, selecciona un valor del menú secundario.

• Selecciona Agregar filtro de atributo y, luego, agrega tu clave y valor personalizados. Si ingresas tu propia clave de filtro, usa la misma sintaxis que una clave para un atributo en un tramo.

  Por ejemplo, para filtrar por el identificador de host, establece la clave en host.id. Del mismo modo, para filtrar por código de estado, establece la clave en /http/status_code. En este caso, puedes establecer el valor en 200, lo que genera el filtro /http/status_code: 200. Para que el filtro coincida con cualquier valor, selecciona Cualquier valor.

Filtrar por aplicación

Los intervalos de Trace generados por la instrumentación que agregaste a tus aplicaciones pueden incluir los siguientes atributos de recursos:

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

La página Trace Explorer incluye los siguientes filtros de tramo, cuyos menús enumeran las aplicaciones, los servicios y las cargas de trabajo que están registrados en App Hub:

• Solicitud de App Hub: Filtra por el atributo de recurso gcp.apphub.application.id.
• Servicio de App Hub: Filtra por el atributo de recurso gcp.apphub.service.id.
• Carga de trabajo de App Hub: Filtra por el atributo de recurso gcp.apphub.workload.id.

Para obtener información sobre cómo instrumentar tu aplicación de modo que los intervalos de seguimiento incluyan atributos específicos de la aplicación, consulta Instrumentación para la supervisión de aplicaciones.

Explora un registro

En esta sección, se proporciona información sobre cómo puedes explorar un intervalo en el contexto de su registro:

1. Abre y configura la página Trace Explorer. Para obtener información sobre estos pasos, consulta Cómo ver los datos de seguimiento agregados.

2. Para ver los detalles de un intervalo o un registro, realiza una de las siguientes acciones:

   • Ve a la sección de tablas de la página Explorador de seguimiento y selecciona una entrada de la sección tabular. Puedes ordenar las filas de las tablas por cualquier encabezado de tabla. Puedes aplicar filtros para restringir los intervalos que muestran las tablas.

   • Ve a la barra de herramientas de la página Explorador de seguimiento, haz clic en pageview Buscar seguimiento y, luego, ingresa el ID de seguimiento.

   Se abrirá el menú desplegable Detalles y se mostrará un registro y sus intervalos. Se muestran los detalles del intervalo o el registro que seleccionaste:

   • La columna Nombre muestra la jerarquía de llamadas, y la primera entrada incluye el ID de seguimiento. Esta columna también puede incluir anotaciones que indican si hay disponibles eventos de IA generativa o datos de registro.
   • La columna Service se extrae del atributo service.name de OpenTelemetry cuando se establece ese atributo. Si ese atributo no está configurado y si el servicio se ejecuta en App Engine, se muestra el nombre del servicio de App Engine. De lo contrario, no se especificará ningún servicio.
   • La longitud de la barra de latencia representa el valor de la latencia.
   • El color de la barra de latencia indica el estado. Una barra de latencia azul indica que la operación se completó correctamente, mientras que una barra de latencia roja indica que se produjo un error.
   • Un círculo en una barra de latencia indica que una entrada de registro o un evento están asociados con el intervalo. Para cambiar este comportamiento, usa el menú Registros y eventos.

3. Para explorar el registro, haz lo siguiente:

   • Usa el puntero para seleccionar diferentes tramos. Cuando seleccionas un intervalo, se actualizan las pestañas de la página para mostrar los atributos, las entradas de registro y los eventos del intervalo.

   • Para buscar palabras clave en los tramos del registro, usa el campo Buscar en el registro.

     La búsqueda solo se aplica a los campos de nombre del intervalo, nombre del servicio y atributos. Solo puedes buscar por texto sin formato y no puedes buscar registros, eventos ni metadatos.

     Por ejemplo, si ingresas GET, se destacará el texto en el nombre del intervalo, el nombre del servicio o en el panel Atributos que muestre GET, sin tener en cuenta las mayúsculas y minúsculas.

   Nota: El Explorador de registros muestra un máximo de 10,000 intervalos para un registro.

Visualiza atributos, entradas de registro y eventos

El menú desplegable Detalles de un intervalo contiene una pestaña para cada uno de los siguientes elementos:

• Attributes: En esta pestaña, se enumeran las etiquetas adjuntas a los intervalos. Para obtener información sobre las etiquetas, consulta Etiquetas de seguimiento.

• Registros y eventos: En esta pestaña, se muestran los eventos y las entradas de registro cuyos campos trace_id y span_id coinciden con el intervalo seleccionado. Solo se muestran las entradas de registro que tienes permiso para ver.

  Para explorar una entrada en esta pestaña, haz clic en Mostrar más.

  Si prefieres usar la página del Explorador de registros para ver los datos de registro, haz clic en Ver registros. La consulta está configurada para filtrar un registro, un intervalo y un período específicos.

  Nota: Los eventos de IA generativa se muestran en la pestaña Entradas/Salidas. Para obtener más información, consulta Cómo ver eventos de IA generativa.

• Stacktraces: Muestra una lista de los registros de seguimiento de pila disponibles.

• Metadatos y vínculos: Muestra información general sobre el tramo:

  • ID de tramo: El ID de tramo es un número entero de 64 bits distinto de 0. Para obtener más información, consulta TraceSpan.
  • ID del intervalo principal.
  • ID del proyecto.
  • Hora de inicio y hora de finalización

  • Tabla que enumera vínculos a otros intervalos. En cada vínculo, esta tabla enumera lo siguiente:

    • Son los pares clave-valor del intervalo vinculado.
    • Es el ID de seguimiento del intervalo vinculado. Cuando este campo muestra Current trace, el intervalo se vincula a otro intervalo en el mismo registro.

    Para obtener información sobre los vínculos, consulta la página de referencia de la API de Links.

Los Detalles también pueden incluir una pestaña etiquetada como Entradas/Salidas. En esta pestaña, se muestran los eventos de IA generativa.

Cómo ver eventos de IA generativa

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para ver los eventos relacionados con los agentes de IA generativa, usa la pestaña Entradas/Salidas. En esta pestaña, se muestran los eventos que siguen las convenciones semánticas de OpenTelemetry GenAI.

Existen dos configuraciones admitidas:

• Instrucciones y respuestas basadas en texto que se adjuntan a los tramos como atributos, que son pares clave-valor que describen alguna característica o un evento. Por ejemplo, el valor de la clave gen_ai.system identifica el sistema que proporciona las capacidades de IA generativa. Las claves de los atributos de la IA generativa comienzan con gen_ai.

• Instrucciones y respuestas multimodales que se almacenan en un bucket de Cloud Storage Cloud Trace identifica estos eventos correlacionando tus datos de registro y seguimiento. Para obtener información sobre las configuraciones compatibles, consulta Cómo recopilar y ver mensajes y respuestas multimodales.

En la siguiente captura de pantalla, se ilustra cómo la página del Explorador de registros renderiza eventos de IA generativa basados en texto que se adjuntan a los intervalos:

Para obtener información sobre la aplicación de ejemplo que generó la captura de pantalla anterior, consulta Instrumenta un agente de LangGraph ReAct con OpenTelemetry.

¿Qué sigue?

• Crea y administra ámbitos de seguimiento
• Comparte seguimientos e intervalos
• Solucionar problemas