Cómo buscar y explorar registros

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

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

Ejemplo de visualización de datos de seguimiento.

Para ejecutar consultas que realicen un análisis agregado de tus intervalos, usa la página Observability Analytics o BigQuery. Ambas interfaces admiten la consulta de tus datos de intervalo con SQL. Cuando usas la página Observability Analytics, puedes ver los resultados de las consultas como una tabla o un gráfico. Para obtener más información sobre cómo usar SQL para consultar tus datos de seguimiento, consulta Consulta y analiza seguimientos.

Esta función solo es compatible con proyectos de Google Cloud . 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 los 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 alcance.

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 Search for trace 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 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 se basan en lo siguiente:

  • El parámetro de configuración Alcance, 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 enumeran en ese alcance para obtener datos de seguimiento.

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

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

  • 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 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 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 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 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 Scope en Project o en _Default. 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 Alcance, selecciona Alcance del seguimiento y, luego, selecciona el alcance del seguimiento que muestra la vista _AllSpans para esos proyectos. Después de realizar la selección, el menú Alcance muestra un ícono de alcance de la ruta, , y el nombre del alcance de la ruta 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 período 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 tramo 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 su sugerencia. La información sobre la herramienta enumera la cantidad de tramos, 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 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 la respuesta como una función del tiempo, configura el menú Vista del gráfico en Tasa de intervalo. En el gráfico, se muestra la tasa de tramos que se envían a tu proyecto.

  5. Usa las tablas Spans y Grouped 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 los datos según 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 Agrupada.

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

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

Cómo aplicar filtros de intervalo

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

Para encontrar o ver los intervalos que generan tus servicios y cargas de trabajo registrados en App Hub, estos deben contener los siguientes atributos de recursos:

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

Los atributos de recursos anteriores se generan a partir de la instrumentación que agregas a tus aplicaciones. Puedes filtrar los datos de seguimiento por cualquier atributo de recurso. Sin embargo, los siguientes filtros de intervalo filtran por los IDs de la aplicación, el servicio y la 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 registro, haz lo siguiente:

  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 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 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 Buscar seguimiento y, luego, ingresa el ID de seguimiento.

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

      Ejemplo del menú desplegable de seguimiento.

      El menú desplegable contiene una pantalla dividida. Un lado muestra el intervalo en el contexto de su registro. En el otro lado, se muestran pestañas que te permiten ver información específica del intervalo, como atributos, metadatos y mensajes y respuestas adjuntos. Para obtener más información sobre estas pestañas, consulta Cómo ver atributos, entradas de registro y eventos.

      Los elementos de la línea de tiempo son dinámicos. Para explorar otro intervalo, selecciónalo 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:

  • En la columna Nombre, se muestran 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 alternativa, 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 Gráfico en la barra de herramientas:

Registro 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 de desplazamiento del cursor para cambiar el tamaño del gráfico.

Cómo buscar los intervalos en un seguimiento

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 tramo, nombre del servicio o 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á el texto en los paneles Nombre, Servicio/carga de trabajo y Atributos que muestre GET, sin tener en cuenta las mayúsculas y minúsculas.

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 Cómo ver eventos y atributos de la 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 Trace.

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

  • Stacktraces: Enumera los registros de seguimiento de pila disponibles.

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

    • ID del tramo: El ID del 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 Seguimiento actual, significa que 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.

Consulta los eventos y atributos de la IA generativa

Para identificar los intervalos que contienen atributos o eventos coherentes con las convenciones semánticas de OpenTelemetry GenAI, 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 configuraciones compatibles:

    • Instrucciones y respuestas basadas en texto adjuntas a los tramos 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 capacidades 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 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 sección Entradas/Salidas renderiza eventos de IA generativa basados en texto adjuntos a intervalos:

      Eventos de IA generativa basados en texto en el Explorador de registros.

      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 tramos 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 atributo 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 qué servidores MCP remotos de Google Cloud admiten la generación de registros y cómo configurar tu aplicación para indicarles a estos servidores que generen intervalos, consulta Investiga las llamadas a MCP con Trace.

¿Qué sigue?