Cómo buscar y explorar registros

La página Explorador de seguimiento te permite ver las tendencias de latencia agregadas, filtrar los datos de Cloud Trace y, además, inspeccionar seguimientos y intervalos individuales para solucionar problemas de errores y cuellos de botella de rendimiento. De forma predeterminada, la página Explorador de seguimientos consulta los datos de seguimiento almacenados en tu proyecto deGoogle Cloud . Sin embargo, puedes configurar la página para consultar datos de seguimiento almacenados en varios proyectos.

Para realizar un análisis agregado personalizado de tus intervalos con SQL, usa la página Estadísticas de observabilidad o BigQuery. Cuando usas la página Estadísticas de observabilidad, puedes ver los resultados de las consultas como una tabla o un gráfico. Para obtener información sobre cómo usar SQL para consultar tus datos de seguimiento, consulta Consulta y analiza seguimientos.

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. En el mapa de calor, se usa el color para representar la cantidad de intervalos en una celda. Una celda con muchos intervalos tiene un color más oscuro que una con pocos intervalos. La información sobre la herramienta de cada celda muestra la latencia y otros datos. También puedes ver los percentiles de latencia y la información de la tasa de intervalos.

En la siguiente captura de pantalla, se ilustra cómo se muestran los datos de seguimiento:

Ejemplo de visualización de datos de seguimiento.

Cuando investigas un problema, es posible que quieras ver un seguimiento 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 seguimiento específico, usa la opción ID de seguimiento de la de la barra de herramientas.

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 nombre de servicio y 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. Desde 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 seguimiento.

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

  • La configuración de Permiso, que determina en qué vistas el sistema busca datos de seguimiento. Cuando se abre la página, el elemento Alcance se establece en el alcance de seguimiento predeterminado y el sistema consulta las vistas que se indican en ese alcance para obtener datos de seguimiento.

    En un proyecto nuevo, el alcance de seguimiento predeterminado muestra la vista _AllSpans del proyecto. Esa vista proporciona acceso de lectura a todos los datos de seguimiento que almacena el proyecto.

    Puedes crear permisos de seguimiento que te permitan consultar datos almacenados en varios proyectos. Para obtener más información, consulta Cómo ver registros en varios proyectos.

  • Tus permisos de Identity and Access Management (IAM) en la vista buscada 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.

  • La configuración del intervalo de tiempo.

  • Los filtros que apliques

Puedes guardar tus datos de registro en un panel personalizado. Para obtener más información, consulta Cómo mostrar datos de seguimiento en un panel personalizado.

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 permiso de seguimiento, pídele a tu administrador que te otorgue el rol de IAM de usuario 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 permiso 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 permiso de seguimiento:

  • Para seleccionar un alcance de seguimiento, haz lo siguiente: cloudtrace.traceScopes.[get, list]
  • Para leer el permiso de seguimiento 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. Para obtener información sobre cómo 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é vistas busca el sistema para obtener datos de registro con el elemento Scope:

      • Para mostrar los datos de seguimiento que almacena tu proyecto, configura el primer menú del elemento Alcance en Proyecto o en _Predeterminado. Estos dos parámetros de configuración son equivalentes.

      • Para mostrar los datos de seguimiento que almacenan varios proyectos, expande el primer menú del elemento Permiso, selecciona Permiso de seguimiento y, luego, selecciona el permiso de seguimiento que enumera la vista _AllSpans para esos proyectos. Después de hacer la selección, el menú Alcance muestra un ícono de alcance de seguimiento, , y el nombre del alcance de seguimiento seleccionado.

      Los datos que muestra el sistema dependen de tus roles de IAM en las vistas buscadas. Por ejemplo, si no tienes los permisos necesarios para ver los datos en una vista, el sistema no los mostrará.

      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 alguna tendencia en los datos de latencia. Los datos de intervalos 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 intervalos tiene un color más oscuro que una con pocos intervalos.

    • Consulta los detalles de la celda con la información sobre la herramienta de la celda. En la información sobre la herramienta, se indica la cantidad de intervalos, la fecha y la hora, y el intervalo de tiempo de la celda.

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

    • Para ver las tendencias de latencia, configura el menú Vista de 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 la respuesta como una función del tiempo, establece el menú Vista de gráfico en Tasa de intervalos. En el gráfico, se muestra la tasa de tramos que se envían a tu proyecto.

  5. Usa las tablas Intervalos y Agrupados para identificar valores atípicos o ver información estadística. En la tabla Intervalos, se enumeran los intervalos individuales. En la tabla Agrupada, se agrupan los intervalos por su nombre y por el nombre del servicio o la carga de trabajo.

    • Para ver los valores atípicos o encontrar un nombre de intervalo, ordena la tabla. Puedes ordenar por cualquier encabezado de columna.

      Por ejemplo, ordenar la tabla Intervalos por duración te permite encontrar intervalos con alta latencia.

    • Para ver estadísticas como la latencia promedio, usa la tabla Agrupadas.

    • Para encontrar los servicios y las cargas de trabajo registrados en App Hub, busca en la columna Servicio/carga de trabajo las entradas que incluyan el ícono de servicio, , o el ícono de carga de trabajo, . El vínculo que se proporciona con un servicio o una carga de trabajo registrados en App Hub abre el panel de supervisión de aplicaciones correspondiente.

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

  6. Para restringir los intervalos que se muestran, agrega filtros. Para obtener información sobre cómo filtrar tus datos de seguimiento, consulta la siguiente sección.

Filtra tus datos de seguimiento

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.

Filtrar por ID de seguimiento

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

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

Si ingresas un ID de seguimiento que no se encuentra, es posible que los datos de seguimiento se almacenen en una vista que no se busca en la página Explorador de Trace, o 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. En cada proyecto, verifica que tu rol de IAM te permita ver los datos de seguimiento y, luego, asegúrate de que el elemento Permiso enumere la vista predeterminada del proyecto para los datos de seguimiento. Para obtener más información, consulta Configura las vistas en las que busca el Explorador de seguimiento.

Cómo aplicar filtros de intervalo

En el panel Filtros de intervalos, 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 tus datos de seguimiento. Cuando un menú incluye una opción sin texto, esa opción se refiere a los intervalos 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 intervalo: Describe las relaciones entre los intervalos. 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 quieres filtrar por un atributo que no aparece en el panel Filtros de intervalos, usa la barra Filtro.

Usa la barra de filtro.

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, realiza una de las siguientes acciones:

  • Selecciona una clave definida, como Nombre del intervalo, y, luego, selecciona un valor en el 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 intervalo.

    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 esta situación, puedes establecer el valor en 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

Puedes filtrar tus datos de seguimiento por una aplicación, una carga de trabajo o un servicio de App Hub cuando esos datos contengan los siguientes atributos de recursos:

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

Estos atributos de recursos se generan con la instrumentación que agregas a tus aplicaciones.

En la página Explorador de seguimiento, usa los siguientes menús de Filtros de tramo para restringir los tramos por aplicación, servicio o carga de trabajo:

  • Aplicación de App Hub
  • Servicio de App Hub
  • Carga de trabajo de App Hub

Para abrir el panel de Supervisión de la aplicación de un servicio y una carga de trabajo registrados en App Hub, haz lo siguiente:

  1. Ve a la tabla Intervalos o Agrupados y busca el servicio o la carga de trabajo. Puedes buscar el ícono de servicio, , el ícono de carga de trabajo, , o filtrar la tabla.

  2. Selecciona el vínculo en la columna Servicio/carga de trabajo.

Explora un registro

Para explorar un intervalo en el contexto de su seguimiento, haz lo siguiente:

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

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

    • Ve a la página Explorador de seguimiento y selecciona una entrada de la tabla. Puedes ordenar las filas de las tablas según cualquier encabezado. 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 ID de seguimiento y, luego, ingresa el ID de seguimiento.

      Se abrirá el menú desplegable Detalles, en el que se mostrarán un seguimiento y sus intervalos en formato de cronograma, así como información sobre el intervalo seleccionado:

      Ejemplo del menú desplegable de seguimiento.

      El menú flotante contiene una pantalla dividida. En un lado, se muestra el intervalo en el contexto de su seguimiento. En el otro lado, se muestran pestañas que te permiten ver información específica del intervalo, como atributos, metadatos, instrucciones y respuestas adjuntas. Para obtener información sobre estas pestañas, consulta Visualiza atributos, entradas de registro y eventos.

      Los elementos de la línea de tiempo son dinámicos. Selecciona un intervalo para ver sus atributos, entradas de registro y eventos.

Explora la jerarquía de llamadas

De forma predeterminada, la jerarquía de llamadas aparece como una línea de tiempo. La primera entrada representa el registro, y cada entrada posterior representa un intervalo. En cada entrada, se muestra lo siguiente:

  • La columna Nombre muestra un nombre y un ID de intervalo o de seguimiento. Un ícono de GenAI, , indica que un intervalo incluye eventos o atributos de IA generativa.
  • En la columna Servicio/carga de trabajo, se muestra el nombre de un servicio o una carga de trabajo. El sistema establece este valor con el atributo service.name de OpenTelemetry. Como resguardo, para los servicios de App Engine, el sistema muestra el nombre del servicio de App Engine.
  • El color y la longitud de la barra de latencia reflejan el estado y la duración del comando.
  • 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.

Para ver la jerarquía de llamadas como un grafo acíclico dirigido (DAG), selecciona Graph en la barra de herramientas:

Seguimiento que muestra un grafo acíclico dirigido.

En la vista de DAG, el nombre y la latencia aparecen con cada elemento. El color refleja el estado del intervalo. Puedes usar la rueda del mouse en el puntero para cambiar el tamaño del gráfico.

Busca los intervalos en un seguimiento

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

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

Por ejemplo, si ingresas GET, se destacará cualquier coincidencia que no distinga mayúsculas de minúsculas para GET en los campos Nombre, Servicio/carga de trabajo y Atributos.

Visualiza atributos, entradas de registro y eventos

El panel desplegable Detalles de un tramo contiene una pestaña para cada uno de los siguientes elementos:

  • Entradas/Salidas: Muestra eventos que siguen las convenciones semánticas de OpenTelemetry GenAI. Esta pestaña solo se muestra cuando el intervalo contiene estos eventos. Para ayudarte a identificar estos intervalos, la vista de línea de tiempo muestra un ícono de GenAI, , con el nombre del intervalo, cuando este contiene eventos o atributos que siguen esas convenciones. Para obtener más información, consulta Visualiza eventos y atributos de IA generativa.

  • Atributos: Enumera los atributos adjuntos a los tramos. El Explorador de seguimiento indica qué tramos contienen atributos de IA generativa mostrando un ícono de GenAI, . Para obtener información sobre las etiquetas, consulta Etiquetas de seguimiento.

  • Registros y eventos: En esta pestaña, se enumeran 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 Explorador de registros para ver los datos de registro, haz clic en Ver registros. La consulta se configura para filtrar por un seguimiento, un intervalo y un período específicos.

  • Seguimientos de pila: Muestra los seguimientos de pila disponibles.

  • Metadatos y vínculos: Se muestra información general, información sobre el alcance de la instrumentación y vínculos al esquema.

    En la sección Metadatos, se muestra información como la siguiente:

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

    • Es una tabla en la que se enumeran los 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 en este campo se indica Seguimiento actual, el intervalo se vincula a otro intervalo en el mismo seguimiento.

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

    En las secciones Alcance de la instrumentación y Información del esquema, se muestran el nombre y la versión del alcance, y se proporcionan vínculos al esquema. Estas secciones se omiten cuando un intervalo no contiene esta información.

El menú lateral Detalles también puede incluir una pestaña etiquetada como Entradas/Salidas. En esta pestaña, se muestran los eventos de IA generativa.

Ver eventos sobre IA generativa

Para identificar los intervalos que contienen atributos o eventos coherentes con las convenciones semánticas de IA generativa de OpenTelemetry, busca el ícono de GenAI, :

  • En la pestaña Attributes, se muestran los atributos adjuntos al intervalo. Para enumerar solo los atributos de IA generativa, habilita Solo atributos de IA generativa.

  • En la pestaña Entradas/Salidas, se muestran los eventos que siguen esas convenciones y los atributos asociados, que también se muestran en la pestaña Atributos. Existen dos opciones de configuración compatibles:

    • Instrucciones y respuestas basadas en texto adjuntas a intervalos como atributos, que son pares clave-valor que describen una 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 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 seguimiento y de registro. Para obtener información sobre los parámetros de configuración compatibles, consulta Cómo recopilar y ver mensajes y respuestas multimodales.

      En la siguiente captura de pantalla, se muestra cómo Entradas/Salidas renderiza eventos de IA generativa basados en texto adjuntos a intervalos:

      Eventos de IA generativa basados en texto en el explorador de seguimientos.

      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.

Cómo ver las llamadas a servidores de MCP remotos

Para ver los intervalos generados por los servidores de MCP, realiza una de las siguientes acciones:

  • Filtra tus datos de seguimiento por el nombre del intervalo.

  • Agrega un filtro de atributos cuya clave sea mcp.method.name y cuyo valor sea tools/call.

    Este filtro es específico para encontrar intervalos cuyo nombre sigue las Convenciones semánticas de OpenTelemetry para MCP. El nombre es similar al siguiente:

    tools/call NAME

    En la expresión anterior, NAME hace referencia al extremo invocado. Por ejemplo, podría ser algo similar a roll_dice.

Para obtener información sobre los servidores de MCP de Google Cloud que generan seguimientos y cómo configurar tu aplicación para que indique a los servidores de MCP que generen intervalos, consulta Investiga las llamadas de MCP con Trace.

¿Qué sigue?