Buscar y explorar trazas

Para ver una representación agregada de sus datos de traza o para buscar y explorar trazas individuales o trazas que contengan etiquetas específicas, use la página Explorador de trazas.

En la siguiente captura de pantalla se muestra cómo se muestran los datos de la traza:

Esta función solo se admite en proyectos de Google Cloud . En las configuraciones de App Hub, selecciona el proyecto host o el proyecto de gestión de App Hub.

Acerca de la página Explorador de trazas

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

Cuando investigues un problema, puede que quieras ver un rastreo específico o solo los intervalos con determinadas 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 rastreo específico, usa la opción vista de página Buscar rastreo de la barra de herramientas.

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

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

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

Para ver los detalles de un intervalo o una agrupación, seleccione la entrada de una fila de la sección tabular. Se abre una ventana emergente que muestra el intervalo en el contexto de su trace. En esta vista, puedes explorar el intervalo, sus atributos y ver eventos y datos de registro. También puedes buscar palabras clave en los intervalos y atributos del rastreo.

Los datos de traza de los que depende la página Explorador de trazas son los siguientes:

• Los proyectos en los que se han buscado datos de traza. De forma predeterminada, el sistema solo busca datos de traza en el proyecto seleccionado en el selector de proyectos. Sin embargo, puedes configurar la página para que busque en la lista de proyectos en un ámbito de seguimiento.
• Tus permisos de gestión de identidades y accesos (IAM) en los proyectos buscados. Si no tienes permiso para ver los datos de traza de un proyecto, la consola Google Cloud muestra un mensaje de advertencia y no se muestran los datos de ese proyecto.
• El ajuste del intervalo de tiempo.
• Los filtros que apliques.

En el resto de esta página se proporciona más información sobre cómo encontrar y explorar los datos de la traza.

Antes de empezar

Para obtener los permisos que necesitas para ver los datos de traza mediante la consola de Google Cloud y seleccionar un ámbito de traza, pide a tu administrador que te asigne el rol de gestión de identidades y accesos Usuario de Cloud Trace (roles/cloudtrace.user) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para ver datos de traza mediante la consola Google Cloud y para seleccionar un ámbito de traza. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Se necesitan los siguientes permisos para ver los datos de traza mediante la consola Google Cloud y para seleccionar un ámbito de traza:

• Para seleccionar un ámbito de traza, sigue estos pasos: cloudtrace.traceScopes.[get, list]
• Para leer el ámbito de la traza predeterminado, haz lo siguiente: observability.scopes.get

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

Para obtener más información sobre los roles, consulta Controlar el acceso con Gestión de Identidades y Accesos.

Ver datos de trazas agregados

Para ver la información agregada sobre los datos de la traza, haga lo siguiente:

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

   Ir a Explorador de trazas

   También puedes acceder a esta página mediante la barra de búsqueda.

   Puede que transcurran varios minutos después de que se escriban los primeros datos de la traza en un proyecto de Google Cloud antes de que se puedan ver. Si no ves ningún dato de seguimiento después de esperar unos minutos, es posible que tu proyecto no tenga datos que mostrar o que haya un problema de configuración. Para obtener información sobre cómo resolver estos problemas, consulta el artículo Solucionar problemas: no hay datos en la interfaz de Trace.

2. Configura la página Explorador de trazas:

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

   2. Opcional: Configura en qué proyectos se buscarán datos de traza mediante el elemento Scope:

      • Para mostrar los datos de la traza almacenados en tu proyecto, asigna al primer menú del elemento Ámbito el valor Proyecto o _Predeterminado. Estos dos ajustes son equivalentes.

      • Para mostrar los datos de la traza que se almacenan en varios proyectos, despliega el primer menú del elemento Ámbito, selecciona Ámbito de la traza y, a continuación, selecciona el ámbito de la traza que incluya esos proyectos. Después de hacer la selección, se muestra el menú Ámbito con un icono de ámbito de traza, , y el nombre del ámbito de traza seleccionado.

      Los datos que se devuelven dependen de los roles de gestión de identidades y accesos que tengas en los proyectos buscados. Por ejemplo, si los proyectos buscados incluyen un proyecto Google Cloud al que no tienes acceso, no se devolverán datos de seguimiento de ese proyecto.

      Para obtener más información, consulta Crear y gestionar ámbitos de traza.

   3. Opcional: Actualiza el intervalo de tiempo con el selector de intervalo o con el puntero para destacar un intervalo en el eje X.

      Por ejemplo, puedes definir este selector en Últimas 2 semanas si quieres ver si hay alguna tendencia en los datos de latencia. Los datos de intervalo 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 elementos span tiene un color más oscuro que una con pocos elementos span.

   • Consulta los detalles de la celda mediante la descripción emergente de la celda. En la descripción emergente se indica el número de intervalos, la fecha y la hora, y el intervalo de tiempo de la celda.

     Nota: Si seleccionas una celda del mapa de calor, se actualizará la tabla que muestra los intervalos individuales o las agrupaciones de intervalos.

4. Consulta los percentiles de latencia y las tasas de errores:

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

   • Para ver el estado de la respuesta en función del tiempo, selecciona Tasa de intervalo en el menú Vista de gráfico. El gráfico muestra la tasa de intervalos 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 concreto, selecciónalo. Se abre una ventana emergente que muestra el intervalo en el contexto de su seguimiento. Después, puedes explorar el intervalo y el trazado.

6. Para consultar el número de intervalos 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.
   • Puede ordenar las filas por el encabezado de duración.

   Si quieres obtener más información sobre una agrupación concreta, selecciona el nombre del intervalo de una fila. Se abrirá una ventana emergente que muestra el intervalo en el contexto de su traza. A continuación, puedes explorar el intervalo y el rastreo.

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

Filtrar los datos de la traza

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 de servicio y por estado. O bien, si has implementado aplicaciones en App Hub, puede que quieras ver los datos de la traza solo de la aplicación o de un servicio o una carga de trabajo específicos que formen parte de la aplicación.

Cuando añade o quita un filtro, los datos que se muestran en la página Explorador de trazas se actualizan y solo se muestran los intervalos que coinciden con todos los filtros aplicados.

Filtrar por un rastreo por ID

Cuando solucionas un incidente o un fallo, es posible que conozcas el ID de la traza. Para consultar ese rastreo, vaya a la barra de herramientas, haga clic en vista de página Buscar rastreo e introduzca el ID de rastreo.

Cuando introduces un ID válido, se abre la ventana emergente Detalles, que muestra información sobre el rastreo y sus intervalos. Puedes usar las opciones de ese panel para explorar el registro. Por ejemplo, puedes buscar palabras clave en los intervalos.

Nota: Si introduce un ID de seguimiento que no se encuentra, es posible que los datos de seguimiento se hayan almacenado en un proyecto en el que no se realiza la búsqueda en la página Explorador de seguimientos o que no tenga un rol de gestión de identidades y accesos que le permita ver los datos de seguimiento. Para resolver estos fallos, identifique los proyectos que almacenan los datos de la traza. En cada proyecto, compruebe que su rol de gestión de identidades y accesos le permite ver los datos de traza y, a continuación, asegúrese de que el elemento Scope (Ámbito) esté configurado para buscar todos los proyectos que almacenen sus datos de traza. Para obtener más información, consulta Actualizar la lista de proyectos en los que se buscan datos de traza.

Aplicar filtros de intervalo

En el panel Filtros de intervalo se muestran los filtros más habituales. Puedes seleccionar varias entradas de cualquier subcategoría. A medida que añades o quitas filtros, la barra Filtrar también se actualiza.

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

Normalmente, están disponibles los siguientes filtros de intervalo:

• Servicio OpenTelemetry: filtra por el atributo service.name.
• Nombre del intervalo: nombre del intervalo.
• Estado del intervalo: el estado de la solicitud. Para obtener información sobre los valores, consulta la documentación de SpanStatus de OpenTelemetry.
• Duración: duración del intervalo.
• Tipo de intervalo: describe las relaciones entre los intervalos. Para obtener información sobre los valores, consulta la documentación de SpanKind de OpenTelemetry.
• Aplicación App Hub: filtra por el atributo de recurso gcp.apphub.application.id.
• Servicio 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 quieres filtrar por un atributo que no aparece en el panel Filtros de intervalo, usa la barra Filtrar.

Usar la barra de filtros

La barra Filtrar te permite aplicar un filtro con una clave de filtro predefinida y un valor que selecciones. También puedes introducir tanto la clave como el valor.

Para añadir un filtro, seleccione Añadir filtro y, a continuación, haga una de las siguientes acciones:

• Selecciona una clave definida, como Nombre del intervalo, y, a continuación, selecciona un valor del menú secundario.

• Selecciona Añadir filtro de atributo y, a continuación, añade tu clave y valor personalizados. Si introduces tu propia clave de filtro, utiliza la misma sintaxis que una clave de un atributo en un intervalo.

  Por ejemplo, para filtrar por el identificador de host, asigna la clave host.id. Del mismo modo, para filtrar por código de estado, defina la clave como /http/status_code. En este caso, puede asignar el valor 200, lo que da como resultado 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 hayas añadido a tus aplicaciones pueden incluir los siguientes atributos de recurso:

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

La página Explorador de trazas incluye los siguientes filtros de intervalo, cuyos menús muestran las aplicaciones, los servicios y las cargas de trabajo registrados en App Hub:

• Aplicación App Hub: filtra por el atributo de recurso gcp.apphub.application.id.
• Servicio 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 para que los intervalos de traza incluyan atributos específicos de la aplicación, consulta Instrumentación para la monitorización de aplicaciones.

Consultar una traza

En esta sección se explica cómo puede explorar un intervalo en el contexto de su traza:

1. Abre y configura la página Explorador de trazas. Para obtener información sobre estos pasos, consulta Ver datos de trazas agregados.

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

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

   • Ve a la barra de herramientas de la página Explorador de trazas, haz clic en vista de página Buscar traza, e introduce el ID de traza.

   Se abre el menú desplegable Detalles, que muestra una traza y sus intervalos. Se muestran los detalles del intervalo o la traza que ha seleccionado:

   • En la columna Nombre se muestra la jerarquía de llamadas y la primera entrada incluye el ID de la traza. Esta columna también puede incluir anotaciones que indiquen si hay disponibles eventos de IA generativa o datos de registro.
   • La columna Servicio se extrae del atributo service.name de OpenTelemetry cuando se define ese atributo. Si no se define ese atributo y el servicio se ejecuta en App Engine, se muestra el nombre del servicio de App Engine. De lo contrario, no se especifica 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 se ha completado correctamente, mientras que una barra de latencia roja indica que se ha producido un error.
   • Un círculo en una barra de latencia indica que una entrada de registro o un evento están asociados al intervalo. Para cambiar este comportamiento, usa el menú Registros y eventos.

3. Para consultar el rastreo, haz lo siguiente:

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

   • Para buscar palabras clave en los intervalos del rastreo, usa el campo Buscar en rastreo.

     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 introduces GET, se resaltará el texto del nombre del intervalo, del nombre del servicio o del panel Atributos que muestre GET, sin tener en cuenta las mayúsculas y minúsculas.

   Nota: Explorador de trazas muestra un máximo de 10.000 intervalos por traza.

Ver atributos, entradas de registro y eventos

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

• Atributos: en esta pestaña se muestran las etiquetas que se han adjuntado a los intervalos. Para obtener información sobre las etiquetas, consulta Etiquetas de traza.

• 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 consultar una entrada de esta pestaña, haz clic en Mostrar más.

  Si prefieres usar la página Explorador de registros para ver los datos de registro, haz clic en Ver registros. La consulta se ha configurado para filtrar una traza, un intervalo y un periodo específicos.

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

• Stacktraces: muestra las trazas de pila disponibles.

• Metadatos y enlaces: muestra información general sobre el intervalo:

  • 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 muestra enlaces a otros intervalos. En esta tabla se indica lo siguiente de cada enlace:

    • Pares clave-valor del intervalo vinculado.
    • El ID de la traza del intervalo vinculado. Si en este campo se muestra Trace actual, significa que el intervalo está vinculado a otro intervalo del mismo trace.

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

La sección Detalles también puede incluir una pestaña llamada Entradas/Salidas. En esta pestaña se muestran los eventos de IA generativa.

Ver eventos de IA generativa

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases 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 GenAI de OpenTelemetry.

Hay dos configuraciones admitidas:

• Peticiones y respuestas basadas en texto que se adjuntan a los intervalos 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 funciones de IA generativa. Las claves de los atributos de IA generativa empiezan por gen_ai.

• Peticiones y respuestas multimodales que se almacenan en un segmento de Cloud Storage. Cloud Trace identifica estos eventos correlacionando tus datos de trazas y registros. Para obtener información sobre las configuraciones admitidas, consulta Recoger y ver peticiones y respuestas multimodales.

En la siguiente captura de pantalla se muestra cómo se representan en la página Explorador de trazas los eventos de IA generativa basados en texto que se adjuntan a los intervalos:

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

Siguientes pasos

• Crear y gestionar ámbitos de traza
• Compartir rastros e intervalos
• Solucionar problemas