Cómo buscar y explorar seguimientos

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.

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

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, que es la visualización predeterminada, usa el color para representar la cantidad de intervalos en una celda. Una celda con muchos tramos se muestra con un color más oscuro que una celda con pocos tramos. Puedes seleccionar una celda o activar su información sobre herramientas 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 expandir el eje X. En el caso de los gráficos de líneas, puedes expandir los ejes X e Y.

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

  • Cuando conozcas el ID de un registro, en la barra de herramientas, haz clic en Buscar registro y, luego, ingresa el ID del registro en el diálogo. A continuación, puedes buscar palabras clave en los intervalos y atributos del registro .

  • Cuando veas los datos agregados, puedes buscar períodos específicos aplicando filtros. Por ejemplo, puedes filtrar los datos para mostrar solo los intervalos de un servicio específico. A continuación, puedes agregar un segundo filtro que limite la visualización a los intervalos de un servicio específico que informa un error.

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

Los datos de seguimiento que muestra la página del Explorador de seguimiento dependen de lo siguiente:

  • Son los proyectos en los que se buscan datos de seguimiento. De forma predeterminada, solo se buscan datos de seguimiento en el proyecto seleccionado con el selector de proyectos. Sin embargo, puedes configurar la página para que busque en la lista de proyectos de un permiso de seguimiento.
  • Tus permisos de Identity and Access Management (IAM) en los proyectos en los que se realizó la búsqueda Si no tienes permiso para ver los datos de seguimiento de un proyecto, la consola de Google Cloud mostrará un mensaje de advertencia y no se mostrarán 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 seguimiento.

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 para 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. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para apps.

  3. 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 Ámbito, selecciona Ámbito del seguimiento y, luego, selecciona el ámbito 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.

  4. Opcional: Actualiza el intervalo de tiempo con el selector de intervalo de tiempo o con el puntero para destacar un intervalo 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.

  5. Ve a la barra de herramientas y establece el selector de período en, al menos, dos semanas. Los datos de los tramos se almacenan durante 30 días.

  6. Explora los gráficos, que muestran patrones y tendencias en los datos de registro:

    • Para obtener información sobre los datos de latencia de los intervalos, configura el menú Vista del gráfico en Duración del intervalo (mapa de calor). La intensidad del color es proporcional a la cantidad de tramos. Para obtener información sobre una celda, usa el puntero. La información sobre herramientas muestra la cantidad de intervalos, la fecha y la hora, y el intervalo de tiempo de la celda.

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

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

    Cada fila de las tablas muestra un intervalo o una agrupación, junto con un vínculo a información detallada y algunas métricas. Por ejemplo, en la pestaña Agrupado, las métricas incluyen la tasa de error y la cantidad de intervalos en el grupo.

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

  8. Agrega filtros para restringir los intervalos que se muestran. 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.

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

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.
  • Aplicación 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.

Cómo encontrar 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, 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.

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

  3. Ve a la barra de herramientas, haz clic en Buscar seguimiento y, luego, ingresa el ID de seguimiento.

    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.

Explora un registro

Para ver un registro o un intervalo, 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. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para apps.

  3. Realiza una de las siguientes acciones:

    • Ve a la sección de la tabla de la página Trace Explorer 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 del intervalo.

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

    Se abrirá el menú desplegable Detalles y se mostrará un registro y sus intervalos:

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

  4. Opcional: Busca el nombre del intervalo, el nombre del servicio y los atributos en un registro de seguimiento con el campo Buscar en el registro de seguimiento.

    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.

    No puedes buscar con una expresión regular ni buscar en los registros, los eventos o los 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.

Cómo ver atributos y eventos

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

Ver etiquetas

Para ver las etiquetas adjuntas al intervalo, ve a la pestaña Attributes. Para obtener información sobre las etiquetas, consulta Etiquetas de seguimiento.

Ver la información de la aplicación

Los siguientes atributos de recursos específicos de la aplicación se pueden adjuntar a los datos de seguimiento. 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 seguimiento de tu aplicación, 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.

  2. Ve al panel Span filters y agrega filtros para tu aplicación de App Hub:

    • Para filtrar por el ID de la 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 App Hub.
    • 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 seguimiento cuando se cumplen las siguientes condiciones:

  • Tus aplicaciones de App Hub usan recursos Google Cloud compatibles.
  • Instrumentas una aplicación con OpenTelemetry y envías los datos de seguimiento recopilados de tu aplicación a tu proyecto con el Google Cloud extremo de OTLP.
  • Los datos que se envían a tu proyecto incluyen atributos de recursos de OpenTelemetry que identifican los recursos Google Cloud compatibles que usa tu aplicación. Los atributos deben incluir lo siguiente:
    • cloud.account.id
    • Uno de cloud.{availability_zone,region}

    • Son atributos específicos del recurso. Por ejemplo, para una carga de trabajo de Kubernetes, los intervalos deben tener establecidos los campos k8s.cluster.name, k8s.namespace y el tipo de implementación de Kubernetes.

      Puedes usar procesadores para que el recopilador de OpenTelemetry adjunte atributos específicos del recurso 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 agregan a los datos de seguimiento cuando se identifica una aplicación.

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

Cómo 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 Mostrar más.

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

Cómo 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 genera mensajes cuyos nombres comienzan con gen_ai.

En la siguiente captura de pantalla, se ilustra cómo la página del Explorador de registros renderiza los eventos de IA generativa:

Visualización de intervalos de seguimiento.

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.

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 capacidades de IA generativa.
  • gen_ai.request.model: Identifica el modelo al que se envía la solicitud.

Los eventos cuyo nombre comienza con "gen_ai" suelen describir entradas o salidas individuales de un sistema de IA generativa. Estas entradas y salidas incluyen instrucciones del sistema y del usuario, 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: Es un evento que registra la instrucción del sistema enviada a un modelo de IA generativa. La instrucción del sistema proporciona instrucciones al modelo que, por lo general, no ve el usuario final y que guían la interpretación del modelo sobre la instrucción del usuario.
  • gen_ai.user.message: Es un evento que registra la instrucción proporcionada por el usuario y que se envió al modelo.
  • gen_ai.assistant.message: Es un 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 no utiliza la aplicación.
  • gen_ai.choice: Es un evento que se usa para informar qué resultados candidatos utiliza la aplicación.

Cómo ver seguimientos de pila

Para ver los seguimientos de pila, usa la pestaña Stacktraces.

Consulta información general y otros metadatos

Para encontrar información general sobre el tramo y una tabla de vínculos a otros tramos, consulta la pestaña Metadata & Links. Esta información incluye lo siguiente:

  • 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 principal de intervalo
  • ID del proyecto
  • Hora de inicio y finalización
  • Tabla que enumera vínculos a otros períodos

Cada fila de la tabla llamada Links enumera un vínculo entre el intervalo actual y otro intervalo. El campo Attributes enumera los pares clave-valor del intervalo vinculado. El campo Trace vincula al registro del intervalo vinculado. Cuando este campo contiene Current trace, el intervalo vinculado se encuentra en el mismo registro que el intervalo actual. De lo contrario, el campo contiene un ID de seguimiento. Para obtener información sobre los vínculos, consulta la página de referencia de la API de Links.

Después de implementar una actualización en una aplicación, es posible que desees determinar si la actualización afectó la latencia de respuesta. Puedes ver las tendencias en los datos de latencia configurando el selector de período de modo que los datos de latencia se muestren antes y después de la actualización.

Para ver las tendencias en 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.

  2. En la barra de herramientas de la consola de Google Cloud , selecciona tu proyecto Google Cloud . Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para apps.
  3. Opcional: Agrega filtros para configurar los intervalos que se muestran.
  4. Ve a la barra de herramientas y establece el selector de período en, al menos, dos semanas. Los datos de los tramos se almacenan durante 30 días.
  5. Opcional: Cambia la selección del menú Vista del gráfico.

¿Qué sigue?