Cómo consultar y analizar registros

En este documento, se describe cómo consultar y analizar tus datos de seguimiento con Análisis de registros, que proporciona una interfaz de consulta basada en SQL. SQL te permite realizar análisis agregados, lo que puede ayudarte a generar estadísticas y a identificar tendencias. Para ver los resultados de tu consulta, usa tablas o gráficos. También puedes guardar estas tablas y gráficos en tus paneles personalizados.

Si quieres ver o explorar seguimientos o intervalos individuales, o ver los atributos adjuntos a los intervalos, usa la página Explorador de seguimiento. Para obtener información sobre esa página, consulta Busca y explora seguimientos.

Para el seguimiento, puedes consultar un bucket de observabilidad llamado _Trace. Una vista, _AllSpans, está disponible para la consulta. Para obtener más información sobre cómo se almacenan tus datos de seguimiento, consulta Descripción general del almacenamiento.

Acerca de los conjuntos de datos vinculados de BigQuery

No necesitas un conjunto de datos vinculado de BigQuery para consultar tus datos de seguimiento ni para consultar tus datos de seguimiento y registro. Para esas situaciones, puedes usar la página Análisis de registros. Para obtener información sobre cómo consultar datos de registro, consulta Consulta y analiza registros con Análisis de registros.

Necesitas un conjunto de datos vinculado de BigQuery cuando quieres hacer cualquiera de las siguientes acciones:

  • Unir datos de seguimiento con otros conjuntos de datos de BigQuery.
  • Consultar datos de seguimiento de otro servicio, como la página BigQuery Studio o Looker Studio.
  • Mejorar el rendimiento de las consultas que ejecutas desde el Análisis de registros ejecutándolas en tus ranuras reservadas de BigQuery.

En este documento, no se describe cómo crear un conjunto de datos vinculado ni cómo configurar el Análisis de registros para ejecutar consultas en ranuras reservadas. Para obtener información sobre estos temas, consulta Consulta un conjunto de datos vinculado de BigQuery.

Antes de comenzar

  1. Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Para obtener los permisos que necesitas para cargar la página Análisis de registros, escribir, ejecutar y guardar consultas privadas sobre tus datos de seguimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM:

    • Usuario con acceso a vistas de observabilidad (roles/observability.viewAccessor) en las vistas de observabilidad que deseas consultar. Este rol admite condiciones de IAM, que te permiten restringir el otorgamiento a una vista específica. Si no adjuntas una condición al otorgamiento del rol, la principal puede acceder a todas las vistas de observabilidad.
    • Usuario de estadísticas de observabilidad (roles/observability.analyticsUser) en tu proyecto. Este rol contiene los permisos necesarios para guardar y ejecutar consultas privadas, y para ejecutar consultas compartidas.
    • Visualizador de registros (roles/logging.viewer) en tu proyecto.

    Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Muestra el esquema

El esquema define cómo se almacenan los datos, lo que incluye los campos y sus tipos de datos. Esta información es importante para ti porque el esquema determina los campos que consultas y si necesitas convertir campos a diferentes tipos de datos. Por ejemplo, para escribir una consulta que calcule la latencia promedio de las solicitudes HTTP , debes saber cómo acceder al campo de latencia y si se almacena como un número entero, como 100, o como una cadena, como "100". Si los datos de latencia se almacenan como una cadena, la consulta debe convertir el valor a un valor numérico antes de calcular un promedio.

Para identificar el esquema, haz lo siguiente:

  1. En la Google Cloud consola de, ve a la página Análisis de registros:

    Ir a Análisis de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. En el menú Vistas, ve a la sección Seguimientos y, luego, selecciona _Trace.Spans._AllSpans.

    Se actualiza el panel Esquema. Análisis de registros infiere automáticamente los campos de una columna cuando el tipo de datos es JSON. Para ver con qué frecuencia aparecen estos campos inferidos en tus datos, haz clic en Opciones y selecciona Ver información y descripción.

    Para obtener información sobre el esquema, consulta Esquema de almacenamiento para datos de seguimiento.

    Si no ves una vista llamada _Trace.Spans._AllSpans, significa que tu Google Cloud proyecto no contiene un bucket de observabilidad llamado _Trace. Para obtener información sobre cómo resolver esta falla, consulta Error en la inicialización del almacenamiento de seguimiento.

Consulta datos de seguimiento

En esta sección, se describen los enfoques que puedes usar para consultar tus datos de seguimiento:

  • Carga una consulta definida por el sistema, edítala y, luego, ejecútala.
  • Ingresa y ejecuta una consulta personalizada. Por ejemplo, puedes pegar una consulta que tengas o escribir una. Las consultas personalizadas pueden incluir uniones, consultas anidadas y otras instrucciones de SQL complejas. Para obtener ejemplos, consulta Consultas de SQL de muestra.
  • Para crear una consulta, realiza selecciones de menú y, luego, ejecuta esa consulta. Análisis de registros convierte tus selecciones en una consulta en SQL, que puedes ver y editar.

Carga, edita y ejecuta la consulta definida por el sistema

  1. En la Google Cloud consola de, ve a la página Análisis de registros:

    Ir a Análisis de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. En el menú Vistas, ve a la sección Seguimientos y, luego, selecciona _Trace.Spans._AllSpans.

    Si no ves una vista llamada _Trace.Spans._AllSpans, significa que tu Google Cloud proyecto no contiene un bucket de observabilidad llamado _Trace. Para obtener información sobre cómo resolver esta falla, consulta Error en la inicialización del almacenamiento de seguimiento.

  3. Realiza una de las siguientes acciones:

    • Para cargar una consulta definida por el sistema que se basa en el Compilador de consultas, que te permite definir la consulta con selecciones de menú, asegúrate de que el panel Consulta muestre Compilador de consultas. Si se muestra un editor de SQL, entonces haz clic en  Compilador.

    • Para cargar una consulta definida por el sistema que extrae valores JSON, asegúrate de que el panel Consulta muestre el editor de SQL. Si este panel muestra Compilador de consultas, haz clic en  SQL.

  4. En el panel Esquema, selecciona Consulta y, luego, haz clic en Anular.

    El panel Consulta muestra una consulta definida por el sistema. Si seleccionaste el Compilador de consultas , pero quieres ver la consulta en SQL, haz clic en  SQL.

  5. Opcional: Modifica la consulta.

  6. Para ejecutar la consulta, ve a la barra de herramientas y selecciona Ejecutar consulta.

    Análisis de registros presenta los resultados de la consulta en una tabla. Sin embargo, puedes crear un gráfico y también puedes guardar la tabla o el gráfico en un panel personalizado. Para obtener más información, consulta Resultados de consulta en SQL SQL.

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar el Análisis de registros para usar el motor de consultas predeterminado. Para realizar este cambio, en la barra de herramientas del panel Consulta, haz clic en Configuración y, luego, selecciona Analytics (predeterminado).

Ingresa y ejecuta una consulta personalizada

Para ingresar una consulta en SQL, haz lo siguiente:

  1. En la Google Cloud consola de, ve a la página Análisis de registros:

    Ir a Análisis de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. En el panel Consulta, haz clic en  SQL.

    • Para especificar un período, te recomendamos que uses el selector de período. Si agregas una cláusula WHERE que especifica el campo timestamp, ese valor anula la configuración en el selector de período y ese selector se inhabilita.

    • Para obtener ejemplos, consulta Consultas de SQL de muestra.

    • El editor de SQL muestra el nombre completamente calificado para la vista _Trace.Spans._AllSpans, que tiene el siguiente formato:

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

      Los campos de la expresión anterior tienen el siguiente significado:

      Si el panel de consultas muestra un mensaje de error que hace referencia a la instrucción FROM, no se puede encontrar la vista. Para obtener información sobre cómo resolver esta falla, consulta Mensaje de error que indica que no existe una vista.

  3. Para ejecutar la consulta, ve a la barra de herramientas y selecciona Ejecutar consulta.

    Análisis de registros presenta los resultados de la consulta en una tabla. Sin embargo, puedes crear un gráfico y también puedes guardar la tabla o el gráfico en un panel personalizado. Para obtener más información, consulta Resultados de consulta en SQL SQL.

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar el Análisis de registros para usar el motor de consultas predeterminado. Para realizar este cambio, en la barra de herramientas del panel Consulta, haz clic en Configuración y, luego, selecciona Analytics (predeterminado).

Compila, edita y ejecuta una consulta

La interfaz del Compilador de consultas te permite compilar una consulta realizando selecciones en los menús. Análisis de registros convierte tus selecciones en una consulta en SQL, que puedes ver y editar. Por ejemplo, puedes comenzar usando la interfaz del Compilador de consultas y, luego, cambiar al editor de SQL para refinar tu consulta.

Análisis de registros siempre puede convertir las selecciones de menú de la interfaz del Compilador de consultas en una consulta en SQL. Sin embargo, no todas las consultas de SQL pueden representarse con la interfaz del Compilador de consultas. Por ejemplo, las consultas con uniones no pueden representarse con esta interfaz.

Para construir una consulta, haz lo siguiente:

  1. En la Google Cloud consola de, ve a la página Análisis de registros:

    Ir a Análisis de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Si el panel Consulta muestra un editor de SQL, selecciona Compilador, que abre el panel Compilador de consultas.

  3. Usa el menú Fuente para seleccionar la vista que deseas consultar. Tus selecciones se asignan a la cláusula FROM en la consulta en SQL.

  4. Opcional: Usa los siguientes menús para restringir o dar formato a la tabla de resultados:

    • Buscar en todos los campos: Busca cadenas coincidentes. Tus selecciones se asignan a la cláusula WHERE en la consulta en SQL.

    • Columnas: Selecciona las columnas que aparecen en la tabla de resultados. Tus selecciones se asignan a las cláusulas SELECT en la consulta en SQL.

      Cuando seleccionas un nombre de campo en este menú, se abre un diálogo. En este diálogo, puedes hacer lo siguiente:

      • Usa el menú para agregar o agrupar tus datos.

        Para evitar errores de sintaxis, cualquier agregación y agrupamiento que apliques a una columna se aplica automáticamente a otras columnas. Para obtener un ejemplo de cómo agregar y agrupar entradas, consulta Agrega y agrupa datos con el Compilador de consultas.

      • Convierte un valor de cualquier tipo en otro tipo de datos especificado. Para obtener más información, consulta la CAST documentación.

      • Extrae una subcadena de valores con expresiones regulares. Para obtener más información, consulta la REGEXP_EXTRACT documentación.

    • Filtros: Agrega filtros cuando quieras restringir la consulta a intervalos que contengan un atributo o un ID de intervalo específico. En el menú, se enumeran todas las opciones de filtro disponibles. Tus selecciones se asignan a la cláusula WHERE en la consulta en SQL.

    • Ordenar por: Establece las columnas por las que se ordenará y si el orden es ascendente o descendente. Tus selecciones se asignan a la cláusula ORDER BY en la consulta en SQL.

    • Límite: Establece la cantidad máxima de filas en la tabla de resultados. Tus selecciones se asignan a la cláusula LIMIT en la consulta en SQL.

  5. Para ejecutar la consulta, ve a la barra de herramientas y selecciona Ejecutar consulta.

    Análisis de registros presenta los resultados de la consulta en una tabla. Sin embargo, puedes crear un gráfico y también puedes guardar la tabla o el gráfico en un panel personalizado. Para obtener más información, consulta Resultados de consulta en SQL SQL.

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar el Análisis de registros para usar el motor de consultas predeterminado. Para realizar este cambio, en la barra de herramientas del panel Consulta, haz clic en Configuración y, luego, selecciona Analytics (predeterminado).

Ejemplo: Agrega y agrupa datos con el Compilador de consultas

Cuando seleccionas una columna en el Compilador de consultas, cada campo incluye un menú en el que puedes agregar agrupamiento y agregación. El agrupamiento te permite organizar tus datos en grupos según el valor de una o más columnas, y la agregación te permite realizar cálculos en estos grupos para mostrar un solo valor.

Cada campo que selecciones en el elemento Columnas tiene un menú adjunto con las siguientes opciones:

  • Ninguno: No agrupes ni agregues por este campo.
  • Agregar: Agrupa los campos que aparecen en el elemento Columnas, excepto cuando el campo tiene una selección de Agregar. Para esos campos, calcula el valor realizando una operación en todas las entradas de cada agrupamiento. La operación podría ser calcular el promedio de un campo o hacer algo como contar la cantidad de entradas en cada agrupamiento.
  • Agrupar por: Agrupa las entradas por todos los campos que aparecen en el elemento Columnas.

En el siguiente ejemplo, se muestra cómo puedes construir una consulta que agrupa entradas y, luego, realiza algún tipo de agregación.

En este ejemplo, se describe cómo usar el Compilador de consultas para agrupar intervalos por hora de inicio, nombre de intervalo y tipo de intervalo. Luego, para cada grupo, la consulta calcula la duración promedio en nanosegundos.

Para construir esta consulta, haz lo siguiente:

  1. En el menú Columnas , selecciona los campos start_time, name, kind y duration_nano.
  2. Para truncar la hora de inicio a la hora, expande el menú en la columna start_time y selecciona Agrupar por. Asegúrate de que el menú de granularidad esté configurado en Hora.

  3. Haz clic en Aplicar.

    Cuando seleccionas Agrupar por para cualquier columna, el sistema agrupa las entradas por todas las columnas. En este ejemplo, las entradas se agrupan por el valor truncado de start_time, el nombre del intervalo, el tipo de intervalo y el valor de la duración.

    Sin embargo, el objetivo de este ejemplo es agrupar las entradas por la hora truncada, el nombre del intervalo y el tipo de intervalo, y, luego, para cada grupo, calcular la duración promedio. En el siguiente paso, modificarás el agrupamiento y agregarás una agregación.

  4. Expande el menú en el campo duration_nano, selecciona Agregar y, luego, establece el campo Agregación en Promedio.

    Cuando ejecutas la consulta, cada fila corresponde a un grupo, que consta de una hora truncada, un nombre de intervalo y un tipo de intervalo. La entrada final de cada fila es la duración promedio de todas las entradas de ese grupo.

    Los resultados de esta consulta son similares a los siguientes:

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
|     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
+-----+-----------------------------+-----------+---------------+-----------------------+
| 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
| 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
| 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376

  5. Tu consulta puede incluir varias agregaciones. Por ejemplo, para agregar una columna que cuente la cantidad de entradas en cada grupo, haz lo siguiente:

    1. En el elemento Columnas, haz clic en Agregar columna.
    2. Selecciona Todas (*).
    3. En el diálogo, selecciona Agregar, selecciona Contar para la Agregación y, luego, selecciona Aplicar.

    Con este cambio, el agrupamiento sigue siendo el mismo. Las entradas se agrupan por la hora de inicio truncada, el nombre del intervalo y el tipo de intervalo. Sin embargo, para cada grupo, la consulta calcula la duración promedio y la cantidad de entradas.

La consulta en SQL correspondiente para el ejemplo anterior es la siguiente:

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

¿Qué sigue?