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.

Esta función solo se admite en proyectos de Google Cloud . En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

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, que es la visualización predeterminada, usa el color para representar el número de intervalos de una celda. Se muestra una celda con muchos intervalos con un color más oscuro que una celda con pocos intervalos. Puedes seleccionar una celda o activar la descripción emergente de una celda para obtener más información. Las otras visualizaciones te permiten ver la latencia como un percentil y la información de la tasa de intervalo. En todas las visualizaciones, puedes usar el puntero para ampliar el eje X. En los gráficos de líneas, puedes ampliar los ejes X e Y.

Cuando investigas un problema, puede que quieras ver un rastreo específico o solo los intervalos con determinadas propiedades:

• Cuando sepas el ID de un rastreo, en la barra de herramientas, haz clic en vista de página Buscar rastreo y, a continuación, introduce el ID de rastreo en el cuadro de diálogo. A continuación, puedes buscar palabras clave en los intervalos y atributos del rastreo .

• Cuando ve los datos agregados, puede buscar intervalos específicos aplicando filtros. Por ejemplo, puede filtrar los datos para que solo se muestren los intervalos de un servicio específico. A continuación, puede añadir un segundo filtro que limite la visualización a los intervalos de un servicio específico que informe de un error.

Los datos tabulares le permiten ver los detalles de los intervalos individuales y le ayudan a identificar valores atípicos. Por ejemplo, para encontrar el intervalo con el valor de latencia más alto, selecciona la pestaña Intervalos y, a continuación, ordena los datos por latencia. Para encontrar los servicios que generan errores, filtre los datos por estado del intervalo y, a continuación, seleccione la pestaña Agrupado, que muestra los datos agregados por intervalo y nombre de servicio. Cada fila de la tabla contiene un enlace a información detallada.

Los datos de traza que se muestran en la página Explorador de trazas dependen de lo siguiente:

• Los proyectos en los que se han buscado datos de traza. De forma predeterminada, solo se buscan 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 de un ámbito de rastreo.
• 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 conceda 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 el 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

Para ver los datos de traza mediante la consola Google Cloud y seleccionar un ámbito de traza, se necesitan los siguientes permisos:

• Para seleccionar un ámbito de traza, sigue estos pasos: cloudtrace.traceScopes.[get, list]
• Para leer el ámbito de la traza predeterminado, sigue estos pasos: 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, siga estos pasos:

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

   Ir a Explorador de trazas

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

   Pueden pasar 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 se muestra 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 seguimiento.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

3. 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 almacenados 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.

4. Opcional: Actualiza el periodo con el selector de periodo 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.

5. Ve a la barra de herramientas y selecciona un periodo de al menos dos semanas. Datos de intervalo almacenados durante 30 días.

6. Consulta los gráficos, que muestran patrones y tendencias en los datos de la traza:

   • Para obtener información sobre los datos de latencia de los tramos, en el menú Vista de gráfico, selecciona Duración del tramo (mapa de calor). La intensidad del color es proporcional al número de intervalos. Para obtener información sobre una celda, usa el puntero. En la descripción emergente se muestra el número de intervalos, la fecha y la hora, así como el intervalo de tiempo de la celda.

   • Para ver las tendencias de latencia, selecciona Duración del intervalo (percentil) en el menú Vista del gráfico. 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 los intervalos que se envían a tu proyecto.

7. Consulta los datos tabulares que muestran los intervalos individuales en la pestaña Intervalos y los intervalos agrupados por servicio y nombre en la pestaña Agrupados.

   Cada fila de las tablas muestra un intervalo o una agrupación, junto con un enlace a información detallada y algunas métricas. Por ejemplo, en la pestaña Agrupado, las métricas incluyen la tasa de errores y el número de intervalos del grupo.

   Para encontrar valores atípicos, selecciona el encabezado de una columna para ordenar la tabla.

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

Filtrar los datos de 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.

Para cambiar la configuración de los filtros, puedes usar el panel Filtros de intervalo o la barra Filtro.

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 obtienen 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 quiere filtrar por un atributo que no aparece en el panel Filtros de intervalo, use 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 la clave y 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 en el menú secundario.

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

  Por ejemplo, para filtrar por el identificador de host, asigna el valor host.id a la clave. 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, seleccione Cualquier valor.

Buscar una traza por ID

Cuando solucionas un problema o un fallo, es posible que conozcas el ID de la traza. Para explorar ese rastro, haz lo siguiente:

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

   Ir a Explorador de trazas

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

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

3. Ve a la barra de herramientas, haz clic en vista de página Buscar seguimiento y escribe el ID de seguimiento.

   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.

Consultar una traza

Para ver un rastreo o un intervalo, haz lo siguiente:

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

   Ir a Explorador de trazas

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

   Pueden pasar 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 se muestra 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 seguimiento.

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

3. Elige una de estas opciones:

   • Ve a la sección de la tabla de la página Explorador de trazas y selecciona una entrada de la tabla que enumera los intervalos o la información de resumen después de agrupar los datos por servicio y nombre de intervalo.

   • 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:

   • En la columna Nombre se muestra la jerarquía de llamadas y la primera entrada incluye el ID de la traza.
   • 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 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.

4. Opcional: Busca el nombre del intervalo, el nombre del servicio y los atributos de una traza mediante el campo Buscar en traza.

   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.

   No puedes buscar usando una expresión regular ni buscar registros, eventos o metadatos.

5. Para ver los detalles de un intervalo específico, selecciónalo y consulta sus atributos y eventos. Consulta la siguiente sección para obtener más información.

Ver atributos y eventos

En esta sección se describe cómo ver etiquetas, registros y eventos.

Ver etiquetas

Para ver las etiquetas asociadas al intervalo, ve a la pestaña Atributos. Para obtener información sobre las etiquetas, consulta Etiquetas de traza.

Ver información de la aplicación

Los siguientes atributos de recursos específicos de la aplicación se pueden adjuntar a los datos de la traza. En esta sección, interpreta a.b.{x,y} como a.b.x y a.b.y:

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

Para encontrar los datos de la traza de tu aplicación, haz lo siguiente:

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

   Ir a Explorador de trazas

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

2. Ve al panel Filtros de intervalo y añade filtros para tu aplicación App Hub:

   • Para filtrar por el ID de aplicación (gcp.apphub.application.id), usa el menú Aplicación de App Hub.
   • Para filtrar por el servicio de una aplicación (gcp.apphub.service.id), usa el menú Servicio de Centro de aplicaciones.
   • Para filtrar por la carga de trabajo de una aplicación (gcp.apphub.workload.id), usa el menú Carga de trabajo de App Hub.

Los atributos de recursos específicos de la aplicación se adjuntan a los datos de la traza cuando se cumplen las siguientes condiciones:

• Las aplicaciones de tu centro de aplicaciones usan recursos admitidos Google Cloud .
• Instrumenta una aplicación con OpenTelemetry y envía los datos de traza recogidos de tu aplicación a tu proyecto mediante el Google Cloud endpoint OTLP.
• Los datos enviados a tu proyecto incluyen atributos de recursos de OpenTelemetry que identifican los recursos admitidos Google Cloud que usa tu aplicación. Los atributos deben incluir lo siguiente:
  • cloud.account.id
  • Uno de cloud.{availability_zone,region}

  • Atributos específicos de los recursos. Por ejemplo, en el caso de una carga de trabajo de Kubernetes, los intervalos deben tener los campos k8s.cluster.name, k8s.namespace y el tipo de despliegue de Kubernetes definidos.

    Puedes usar procesadores para que el OpenTelemetry Collector adjunte atributos específicos de recursos a tus intervalos. Para obtener más información, consulta resourcedetectionprocessor y k8sattributesprocessor.

  Cuando instrumentas una aplicación, Google Cloud Observability usa los atributos de recursos anteriores y la API de App Hub para identificar tu aplicación de App Hub. Las etiquetas específicas de la aplicación se añaden a los datos de la traza cuando se identifica una aplicación.

Para obtener más información sobre estos atributos, consulta las Google Cloud convenciones semánticas de App Hub.

Ver registros y eventos

Para ver los registros y eventos relacionados con el intervalo, ve a la pestaña Registros y eventos.

Para ver una entrada de registro, haz clic en keyboard_arrow_down Mostrar más.

También puedes seleccionar el botón Ver registros, que abre la página Explorador de registros con la consulta configurada para filtrar por un seguimiento, un intervalo y un periodo específicos. Es posible que esta consulta no devuelva ninguna entrada de registro.

Ver eventos de IA generativa

Para ver los eventos relacionados con los agentes de IA generativa, usa la pestaña GenAI. Esta pestaña está disponible cuando los intervalos enviados a Trace siguen las convenciones semánticas de OpenTelemetry para sistemas de IA generativa, lo que da como resultado mensajes cuyos nombres empiezan por gen_ai.

En la siguiente captura de pantalla se muestra cómo se representan los eventos de IA generativa en la página Explorador de trazas:

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.

Los atributos son pares clave-valor que describen alguna característica. A continuación, se muestran ejemplos de atributos de un sistema de IA generativa:

• gen_ai.system: identifica el sistema que proporciona las funciones de IA generativa.
• gen_ai.request.model: identifica el modelo al que se envía la solicitud.

Los eventos cuyo nombre empieza por "gen_ai" suelen describir entradas o salidas individuales de un sistema de IA generativa. Estas entradas y salidas incluyen peticiones del sistema y de los usuarios, entradas y salidas de herramientas, y respuestas del modelo. A continuación, se muestran ejemplos de eventos de un sistema de IA generativa:

• gen_ai.system.message: evento que registra la petición del sistema enviada a un modelo de IA generativa. La petición del sistema proporciona instrucciones al modelo que normalmente no ve el usuario final y que guían la interpretación del modelo de la petición del usuario.
• gen_ai.user.message: evento que registra la petición proporcionada por el usuario que se ha enviado al modelo.
• gen_ai.assistant.message: evento que registra la salida del modelo, que puede incluir el registro de una invocación de herramienta o que puede contener una salida de respuesta textual. Un mensaje puede incluir respuestas candidatas que la aplicación no utilice.
• gen_ai.choice: evento que se usa para informar de qué resultados candidatos usa la aplicación.

Ver rastreos de pila

Para ver los rastreos de pila, usa la pestaña Rastreo de pila.

Ver información general y otros metadatos

Para consultar información general sobre el intervalo y una tabla de enlaces a otros intervalos, ve a la pestaña Metadatos y enlaces. Esta información incluye lo siguiente:

• 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 de finalización
• Tabla que muestra enlaces a otros intervalos

Cada fila de la tabla Enlaces muestra un enlace entre el intervalo actual y otro intervalo. El campo Attributes muestra los pares clave-valor del intervalo vinculado. El campo Traza enlaza con la traza del intervalo vinculado. Si este campo contiene Traza actual, el intervalo vinculado está en la misma traza que el intervalo actual. De lo contrario, el campo contiene un ID de traza. Para obtener información sobre los enlaces, consulta la página de referencia de la API Links.

Consultar tendencias

Después de implementar una actualización en una aplicación, puede que quieras determinar si la actualización ha afectado a la latencia de respuesta. Para ver las tendencias de los datos de latencia, puede configurar el selector de periodo de forma que se muestren los datos de latencia antes y después de la actualización.

Para ver las tendencias de los datos de la traza, haz lo siguiente:

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

   Ir a Explorador de trazas

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

2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
3. Opcional: Añade filtros para configurar los intervalos que se muestran.
4. Ve a la barra de herramientas y selecciona un periodo de al menos dos semanas. Los datos de intervalo se almacenan durante 30 días.
5. Opcional: Cambia la selección del menú Vista de gráfico.

Siguientes pasos

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