Consulta y analiza datos de telemetría con el Análisis de registros

En este documento, se describe cómo consultar y analizar tus datos de registros y de seguimiento con el Análisis de registros, que proporciona una interfaz de consultas 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 el formato tabular o visualiza los datos con gráficos. También puedes guardar estas tablas y gráficos en tus paneles personalizados.

Acerca de los conjuntos de datos vinculados de BigQuery

No necesitas un conjunto de datos de BigQuery vinculado para consultar tus datos de registros, tus datos de seguimiento o ambos tipos de datos cuando usas la página Análisis de registros.

Necesitas un conjunto de datos de BigQuery vinculado cuando quieras realizar cualquiera de las siguientes acciones:

En este documento, no se describe cómo crear un conjunto de datos vinculado, lo que requiere un proceso específico del tipo de datos. Para obtener información sobre cómo crear un conjunto de datos vinculado, consulta Cómo consultar datos de registro con un conjunto de datos vinculado o Cómo consultar datos de seguimiento con un conjunto de datos vinculado.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . 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. Habilita la API de Observability.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la 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. Habilita la API de Observability.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

    8.

  8. Para obtener los permisos que necesitas para cargar la página de Log Analytics, escribir, ejecutar y guardar consultas privadas en 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 podrá acceder a todas las vistas de observabilidad. Las vistas de observabilidad están disponibles en versión preliminar pública.
    • Usuario de Observability Analytics (roles/observability.analyticsUser) en tu proyecto. Este rol contiene los permisos necesarios para guardar y ejecutar consultas privadas, y para ejecutar consultas compartidas.
    • Visor de registros (roles/logging.viewer) en tu proyecto
    • Descriptor de acceso de vista de registros (roles/logging.viewAccessor) en el proyecto que almacena las vistas de registros que deseas consultar.

    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.

Datos de registro y seguimiento de consultas

En esta sección, se describen los enfoques que puedes usar para consultar tus datos de registros y 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 búsqueda que tengas o escribir una. Las consultas personalizadas pueden incluir uniones, consultas anidadas y otras instrucciones de SQL complejas. Para ver ejemplos, consulta Consultas de SQL de muestra.
  • Crea una consulta seleccionando opciones del menú y, luego, ejecuta esa consulta. El 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 consola de Google Cloud , 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, selecciona una vista.

    Para encontrar la vista que deseas consultar, usa la barra de Filtro o desplázate por la lista:

    • Las vistas de registros, que se enumeran en la sección Registros, se ordenan según los IDs de bucket y de vista.

    • Las vistas de Analytics, que se enumeran en la sección Vistas de Analytics de , se ordenan por ubicación y por ID de la vista. Las vistas de observabilidad están disponibles en versión preliminar pública.

    • Hay una vista de seguimiento, que se muestra en la sección Seguimientos. Las vistas de observabilidad están disponibles en versión preliminar pública.

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

  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 el Compilador de consultas. Si se muestra un editor de SQL, 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 en este panel se muestra el Generador de consultas, haz clic en  SQL.

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

    En el panel Consulta, se muestra una consulta definida por el sistema. Si seleccionaste el modo 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.

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

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar Log Analytics para que use 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).

Cómo ingresar y ejecutar una consulta personalizada

Para ingresar una consulta en SQL, haz lo siguiente:

  1. En la consola de Google Cloud , 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íodos. Si agregas una cláusula WHERE que especifica el campo timestamp, ese valor anula el parámetro de configuración del selector de intervalo de tiempo y ese selector se inhabilita.

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

    • La vista que consultas determina el formato de la cláusula FROM:

      Datos de registros

      Puedes consultar vistas de registros o vistas de análisis. Usa el siguiente formato para la cláusula FROM:

      • Vistas de registro:

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • Vistas de Analytics:

        FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`

      Los campos de las expresiones anteriores tienen el siguiente significado:

      • PROJECT_ID: Es el identificador del proyecto.
      • LOCATION: Es la ubicación de la vista de registros o la vista de estadísticas.
      • BUCKET_ID: Es el nombre o el ID del bucket de registros.
      • LOG_VIEW_ID: Es el identificador de la vista de registros, que se limita a 100 caracteres y solo puede incluir letras, dígitos, guiones bajos y guiones.
      • ANALYTICS_VIEW_ID: Es el ID de la vista de Analytics, que se limita a 100 caracteres y solo puede incluir letras, dígitos, guiones bajos y guiones.

      Si el panel de consultas muestra un mensaje de error que hace referencia a la instrucción FROM, significa que no se puede encontrar la vista. Para obtener información sobre cómo resolver este error, consulta El error FROM debe contener exactamente una vista de registro.

      Datos de seguimiento

      El editor de SQL muestra el nombre completamente calificado de 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, significa que no se puede encontrar la vista. Para obtener información sobre cómo resolver este error, 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.

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

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar Log Analytics para que use 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).

Crea, edita y ejecuta una consulta

La interfaz del Compilador de consultas te permite compilar una consulta a través de selecciones en los menús. El 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 Generador de consultas y, luego, cambiar al editor de SQL para definir mejor tu consulta.

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

Para crear una consulta, haz lo siguiente:

  1. En la consola de Google Cloud , 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 aparecerán 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 agrupación que apliques a una columna también se aplicará automáticamente a otras columnas. Para ver 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 documentación de CAST.

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

    • Filtros: Agrega filtros cuando quieras restringir la búsqueda a los intervalos que contengan un atributo o un ID de intervalo específicos. En el menú, se enumeran todas las opciones de filtro disponibles. Tus selecciones se asignan a la cláusula WHERE de 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 de 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.

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

    Si la barra de herramientas muestra Ejecutar en BigQuery, debes cambiar Log Analytics para que use 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: Agrupa y agrega 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 agrupaciones y agregaciones. 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 devolver un solo valor.

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

  • Ninguno: No agrupar ni agregar por este campo
  • Agregado: Agrupa los campos que se enumeran en el elemento Columnas, excepto cuando el campo tiene una selección de Agregado. Para esos campos, calcula el valor realizando una operación en todas las entradas de cada agrupación. La operación podría ser calcular el promedio de un campo o contar la cantidad de entradas en cada agrupación.
  • Agrupar por: Agrupa las entradas por todos los campos que se enumeran en el elemento Columnas.

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

Datos de registros

En este ejemplo, se describe cómo usar el Creador de consultas para agrupar las entradas de registro por gravedad y marca de tiempo, y, luego, calcular el promedio del campo http_request.response_size para cada grupo.

Para crear una consulta que agrupe y agregue tus datos, realiza las siguientes selecciones en los menús del compilador de consultas:

  1. En el menú Columnas, selecciona los campos timestamp, severity y http_request.response_size.

    1. Para agrupar tus datos, haz clic en el campo timestamp para abrir el diálogo de configuración. En este diálogo, selecciona la opción Group by y establece la Truncation Granularity en HOUR. Luego, la agrupación se aplica automáticamente a todos los demás campos para evitar errores de sintaxis. Si hay campos no válidos en los que no se puede aplicar la agrupación, verás un mensaje de error. Quita los campos no válidos del menú para resolver este error.

    2. Para realizar la agregación en el campo http_request.response_size, haz clic en él para abrir el diálogo de configuración. En este diálogo, selecciona Aggregate. En el menú Agregación, haz clic en Promedio.

  2. En el menú Filters, agrega http_request.response_size y establece el comparador en IS NOT NULL. Este filtro coincide con las entradas de registro que contienen un valor de response_size.

    Los menús del Generador de consultas se ven similares a los siguientes:

    Agrega y agrupa datos con los menús del compilador de consultas.

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

    Los resultados de esta consulta son similares a los siguientes:

    +-----------------------------------+----------+---------------+
| Row | hour_timestamp              | severity | response_size |
|     | TIMESTAMP                   | STRING   | INTEGER       |
+-----+-----------------------------+----------+---------------+
| 1   | 2025-10-06 16:00:00.000 UTC | NOTICE   | 3082          |
| 2   | 2025-10-06 17:00:00.000 UTC | WARNING  | 338           |
| 3   | 2025-10-06 16:00:00.000 UTC | INFO     | 149           |

La consulta en SQL correspondiente al ejemplo anterior es la siguiente:

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
  severity,
  -- Compute average response_size.
  AVG( http_request.response_size ) AS average_http_request_response_size
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a response_size.
  http_request.response_size IS NOT NULL
GROUP BY
  -- Group log entries by timestamp and severity.
  TIMESTAMP_TRUNC( timestamp, HOUR ),
  severity
LIMIT
  1000

Datos de seguimiento

En este ejemplo, se describe cómo usar el compilador de consultas para agrupar intervalos por hora de inicio, nombre y tipo. 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 Hour.

  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 según el valor truncado de start_time, el nombre del tramo, el tipo de tramo y el valor de la duración.

    Sin embargo, el objetivo de este ejemplo es agrupar las entradas por el tiempo truncado, 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 la agrupación y agregarás una agregación.

  4. Expande el menú en el campo duration_nano, selecciona Agregación 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 Aggregate, luego Count para Aggregation y, por último, Apply.

    Con este cambio, la agrupación sigue siendo la misma. 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 al 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

Cómo mostrar 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 en un valor numérico antes de calcular un promedio.

Para identificar el esquema, haz lo siguiente:

  1. En la consola de Google Cloud , 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, selecciona una vista.

    Se actualiza el panel Esquema. Log Analytics 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.

    Datos de registros

    En el caso de las vistas de registro, el esquema es fijo y corresponde a LogEntry. En el caso de las vistas de análisis, puedes modificar la consulta en SQL para cambiar el esquema.

    Datos de seguimiento

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

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

Restricciones

Si deseas consultar varias vistas, estas deben residir en la misma ubicación. Por ejemplo, si almacenas dos vistas en la ubicación us-east1, una consulta puede consultar ambas vistas. También puedes consultar dos vistas almacenadas en la multirregión us. Sin embargo, si la ubicación de una vista es global, esa vista puede residir en cualquier ubicación física. Por lo tanto, es posible que fallen las uniones entre dos vistas que tienen la ubicación de global.

Para obtener una lista de las restricciones que se aplican a los datos de registro, consulta Log Analytics: Restricciones.

¿Qué sigue?