Se usó la API de Cloud Translation para traducir esta página.

Consultas en SQL de muestra

Este documento contiene consultas de muestra sobre entradas de registro que se almacenan en buckets de registros que se actualizan para usar el Análisis de registros. En estos buckets puedes ejecutar consultas en SQL desde la página Análisis de registros en la consola de Google Cloud. Para obtener más muestras, consulta los repositorios de GitHub de logging-analytics-samples y security-analytics.

En este documento, no se describe SQL ni cómo enrutar y almacenar entradas de registro. Para obtener información sobre esos temas, consulta la sección Próximos pasos.

Antes de comenzar

Para usar las consultas que se muestran en este documento en la página Análisis de registros, reemplaza TABLE por el nombre de la tabla que corresponde a la vista que deseas consultar. El nombre de la tabla tiene el formato project_ID.region.bucket_ID.view_ID. Puedes encontrar el nombre de la tabla de una vista en la página Análisis de registros; la consulta predeterminada para una vista de registro enumera el nombre de la tabla en la instrucción FROM. Para obtener información sobre cómo acceder a la consulta predeterminada, ve a Consulta una vista de registro.
Para usar las consultas que se muestran en este documento en la página BigQuery Studio, reemplaza TABLE por la ruta a la tabla en el conjunto de datos vinculado. Por ejemplo, para consultar la vista _AllLogs en el conjunto de datos vinculado mydataset que se encuentra en el proyecto myproject, configura este campo como myproject.mydataset._AllLogs:

En la consola de Google Cloud, ve a la página de BigQuery:
Ir a BigQuery

También puedes usar la barra de búsqueda para encontrar esta página.
Para abrir la página Análisis de registros, 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. Opcional: Si quieres identificar el esquema de tabla para la vista de registro, en la lista Vistas de registro, busca la vista y, luego, selecciona su nombre.
Se muestra el esquema de la tabla. Puedes usar el campo Filtro para ubicar campos específicos. No puedes modificar el esquema.

Filtrar registros

Las consultas de SQL determinan qué filas de la tabla procesar y, luego, agrupan las filas y realizan operaciones de agregación. Cuando no se muestran operaciones de agrupación y agregación, el resultado de la consulta incluye las filas seleccionadas por la operación de filtro. En los ejemplos de esta sección, se muestra el filtrado.

Filtrar por hora

Para establecer el intervalo de tiempo de tu consulta, te recomendamos que uses el selector de intervalo de tiempo. Este selector se usa automáticamente cuando una consulta no especifica un campo timestamp en la cláusula WHERE. Por ejemplo, para ver los datos de la semana pasada, selecciona Últimos 7 días en el selector de intervalo de tiempo. También puedes usar el selector de intervalo de tiempo para especificar una hora de inicio y finalización, especificar una hora para ver los alrededores y cambiar las zonas horarias.

Si incluyes un campo timestamp en la cláusula WHERE, no se usa la configuración del selector de rango de tiempo. En el siguiente ejemplo, se filtran los datos mediante la función TIMESTAMP_SUB, que te permite especificar un intervalo de retrospectiva a partir de la hora actual:

WHERE
  timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Para obtener más información sobre cómo filtrar por tiempo, consulta Funciones de tiempo y Funciones de marca de tiempo.

Filtrar por recurso

Para filtrar por recurso, agrega una restricción resource.type.

Por ejemplo, la siguiente consulta lee la hora más reciente de los datos, luego conserva las filas cuyo tipo de recurso coincide con gce_instance y ordena y muestra hasta 100 entradas:

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  resource.type = "gce_instance"
ORDER BY timestamp ASC
LIMIT 100

Filtrar por gravedad

Puedes filtrar por una gravedad específica con una restricción como severity = 'ERROR'. Otra opción es usar la declaración IN y especificar un conjunto de valores válidos.

Por ejemplo, la siguiente consulta lee la hora más reciente de los datos y, luego, retiene solo las filas que contienen un campo severity cuyo valor es 'INFO' o 'ERROR':

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  severity IS NOT NULL AND
  severity IN ('INFO', 'ERROR')
ORDER BY timestamp ASC
LIMIT 100

La consulta anterior filtra por el valor del campo severity. Sin embargo, también puedes escribir consultas que filtren por el valor numérico de la gravedad del registro. Por ejemplo, si reemplazas las líneas severity por las siguientes líneas, la consulta mostrará todas las entradas de registro cuyo nivel de gravedad es al menos NOTICE:

  severity_number IS NOT NULL AND
  severity_number > 200

Para obtener información sobre los valores enumerados, consulta LogSeverity.

Filtrar por nombre de registro

Para filtrar por un nombre de registro, puedes agregar una restricción en el valor de los campos log_name o log_id. El campo log_name incluye la ruta del recurso. Es decir, este campo tiene valores como projects/myproject/logs/mylog. El campo log_id solo almacena el nombre del registro, como mylog.

Por ejemplo, la siguiente consulta lee la hora más reciente de los datos, luego conserva las filas en las que el valor del campo log_id es cloudaudit.googleapis.com/data_access y, luego, ordena y muestra los resultados:

SELECT
  timestamp, log_id, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  log_id = "cloudaudit.googleapis.com/data_access"
ORDER BY timestamp ASC
LIMIT 100

Filtrar por etiqueta de recurso

La mayoría de los descriptores de recurso supervisado definen las etiquetas que se usan para identificar el recurso específico. Por ejemplo, el descriptor de una instancia de Compute Engine incluye etiquetas para la zona, el ID del proyecto y el ID de la instancia. Cuando se escribe la entrada de registro, se asignan valores a cada campo. A continuación, se muestra un ejemplo:

{
   type: "gce_instance"
   labels: {
      instance_id: "1234512345123451"
      project_id: "my-project"
      zone: "us-central1-f"
   }
}

Debido a que el tipo de datos del campo labels es JSON, incluir una restricción como resource.labels.zone = "us-centra1-f" en una consulta generará un error de sintaxis. Para obtener el valor de un campo con un tipo de datos de JSON, usa la función JSON_VALUE.

Por ejemplo, la siguiente consulta lee los datos más recientes y, luego, retiene las filas en las que el recurso es una instancia de Compute Engine que se encuentra en la zona us-central1-f:

SELECT
  timestamp, log_name, severity, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  resource.type = "gce_instance" AND
  JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC
LIMIT 100

Para obtener información sobre todas las funciones que pueden recuperar y transformar datos JSON, consulta Funciones de JSON.

Filtrar por solicitud HTTP

Si deseas filtrar la tabla para que solo incluya filas que correspondan a una solicitud o respuesta HTTP, agrega una restricción http_request IS NOT NULL:

SELECT
  timestamp, log_name, severity, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL
ORDER BY timestamp
LIMIT 100

La siguiente consulta solo incluye filas que corresponden a solicitudes GET o POST:

SELECT
  timestamp, log_name, severity, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.request_method IN ('GET', 'POST')
ORDER BY timestamp ASC
LIMIT 100

Filtrar por estado HTTP

Si deseas filtrar por estado HTTP, modifica la cláusula WHERE para requerir que se defina el campo http_request.status:

SELECT
  timestamp, log_name, http_request.status, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.status IS NOT NULL
ORDER BY timestamp ASC
LIMIT 100

Para determinar el tipo de datos almacenados en un campo, visualiza el esquema o muestra el campo. Los resultados de la consulta anterior muestran que el campo http_request.status almacena valores de números enteros.

Filtra por un campo de tipo JSON

Para extraer un valor de una columna cuyo tipo de datos sea JSON, usa la función JSON_VALUE.

Considera las siguientes consultas:

SELECT
  json_payload
FROM
  `TABLE`
WHERE
  json_payload.status IS NOT NULL

SELECT
  json_payload
FROM
  `TABLE`
WHERE
  JSON_VALUE(json_payload.status) IS NOT NULL

Las consultas anteriores prueban el valor de la columna json_payload. El contenido de esta columna está determinado por el contenido de una entrada de registro. Ambas consultas descartan las filas que no contienen una columna etiquetada json_payload. La diferencia entre estas dos consultas es la línea final, que define lo que se prueba en NULL. Ahora, considera una tabla que tenga dos filas. En una fila, la columna json_payload tiene la siguiente forma:

{
    status: {
        measureTime: "1661517845"
    }
}

En la otra fila, la columna json_payload tiene una estructura diferente:

{
    @type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
    jobName: "projects/my-project/locations/us-central1/jobs/test1"
    relativeUrl: "/food=cake"
    status: "NOT_FOUND"
    targetType: "APP_ENGINE_HTTP"
}

Las dos filas anteriores satisfacen la restricción json_payload.status IS NOT NULL. Es decir, el resultado de la consulta incluye ambas filas. Sin embargo, cuando la restricción es JSON_VALUE(json_payload.status) IS NOT NULL, solo la segunda fila se incluye en el resultado.

Filtrar por expresión regular

Para mostrar la subcadena que coincide con una expresión regular, usa la función REGEXP_EXTRACT. El tipo de datos que se muestra para esta función es STRING o BYTES.

La siguiente consulta muestra las entradas de registro más recientes recibidas, retiene esas entradas con un campo json_payload.jobName y, luego, muestra la parte del nombre que comienza con test:

SELECT
  timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
  `TABLE`
WHERE
  json_payload.jobName IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20

Para ver ejemplos adicionales, consulta la documentación de REGEXP_EXTRACT. Para ver ejemplos de otras expresiones regulares que puedes usar, consulta Funciones, operadores y condicionales.

La consulta que se muestra en este ejemplo no es eficiente. Para una coincidencia de subcadena, como la que se muestra en la ilustración, usa la función CONTAINS_SUBSTR.

Agrupa y agrega entradas de registro

En esta sección, se basa en los ejemplos anteriores y se ilustra cómo puedes agrupar y agregar filas de tablas. Si no especificas una agrupación, pero especificas una agregación, se muestra un solo resultado porque SQL trata todas las filas que satisfacen la cláusula WHERE como un solo grupo.

Cada expresión SELECT debe incluirse en los campos del grupo o agregarse.

Agrupar por tiempo

Para agrupar datos por tiempo, usa la función TIMESTAMP_TRUNC, que trunca una marca de tiempo a un nivel de detalle específico, como MINUTE. Por ejemplo, una marca de tiempo de 15:30:11, que tiene el formato de hours:minutes:seconds, se convierte en 15:30:00 cuando el nivel de detalle se establece en MINUTE.

La siguiente consulta lee los datos recibidos en el intervalo que especifica el selector de intervalo de tiempo y, luego, retiene las filas en las que el valor del campo json_payload.status no es NULO. La consulta trunca la marca de tiempo en cada fila por hora y, luego, las agrupa según la marca de tiempo y el estado truncados:

SELECT
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  COUNT(*) AS count
FROM
  `TABLE`
WHERE
  json_payload IS NOT NULL AND
  JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY hour,status
ORDER BY hour ASC

Para obtener muestras adicionales, consulta la documentación de TIMESTAMP_TRUNC. Para obtener información sobre otras funciones basadas en el tiempo, consulta Funciones de fecha y hora.

Agrupar por recurso

La siguiente consulta lee la hora más reciente de los datos y, luego, agrupa las filas por tipo de recurso. Luego, cuenta el número de filas de cada tipo y muestra una tabla con dos columnas. La primera columna indica el tipo de recurso, mientras que la segunda columna es el número de filas para ese tipo de recurso:

SELECT
   resource.type, COUNT(*) AS count
FROM
  `TABLE`
GROUP BY resource.type
LIMIT 100

Agrupar por gravedad

La siguiente consulta lee la hora más reciente de los datos y, luego, retiene las filas que tienen un campo de gravedad. Luego, la consulta agrupa las filas por gravedad y cuenta el número de filas para cada grupo:

SELECT
  severity, COUNT(*) AS count
FROM
  `TABLE`
WHERE
  severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100

Agrupar por `log_id`

El resultado de la siguiente consulta es una tabla con dos columnas. En la primera columna, se enumeran los nombres de los registros y, en la segunda, se indica la cantidad de entradas de registro que se escribieron en el registro. La consulta ordena los resultados según el recuento de entradas:

SELECT
  log_id, COUNT(*) AS count
FROM
  `TABLE`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100

Calcula la latencia promedio para las solicitudes HTTP

En la siguiente consulta, se ilustra la agrupación por varias columnas y se calcula un valor promedio. La consulta agrupa las filas según la URL que se incluye en la solicitud HTTP y el valor del campo labels.checker_location. Después de agrupar las filas, la consulta calcula la latencia promedio de cada grupo:

SELECT
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.request_method IN ('GET')
GROUP BY http_request.request_url, location
ORDER BY location
LIMIT 100

En la expresión anterior, se requiere JSON_VALUE para extraer el valor del campo labels.checker_location porque el tipo de datos de labels es JSON. Sin embargo, no debes usar esta función para extraer el valor del campo http_request.latency.seconds. El último campo tiene un tipo de datos de número entero.

Calcula el promedio de bytes enviados para una prueba de subred

En la siguiente consulta, se ilustra cómo mostrar la cantidad promedio de bytes enviados por ubicación.

La consulta lee la hora más reciente de los datos y, luego, retiene solo las filas cuya columna de tipo de recurso es gce_subnetwork y cuya columna json_payload no es NULL. A continuación, la consulta agrupa las filas por la ubicación del recurso. A diferencia del ejemplo anterior, en el que los datos se almacenan como un valor numérico, el valor del campo bytes_sent es una string y, por lo tanto, debes convertir el valor en FLOAT64 antes de calcular el promedio:

SELECT JSON_VALUE(resource.labels.location) AS location,
   AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
  `TABLE`
WHERE
  resource.type = "gce_subnetwork" AND
  json_payload IS NOT NULL
GROUP BY location
LIMIT 100

El resultado de la consulta anterior es una tabla en la que, en cada fila, se indica una ubicación y el promedio de bytes enviados a esa ubicación.

Para obtener información sobre todas las funciones que pueden recuperar y transformar datos JSON, consulta Funciones de JSON.

Para obtener información sobre CAST y otras funciones de conversión, consulta Funciones de conversión.

Cuenta las entradas de registro con un campo que coincida con un patrón

Para mostrar la subcadena que coincide con una expresión regular, usa la función REGEXP_EXTRACT. El tipo de datos que se muestra para esta función es STRING o BYTES.

La siguiente consulta conserva las entradas de registro para las cuales el valor del campo json_payload.jobName no es NULL. Luego, agrupa las entradas según el sufijo del nombre que comienza con test. Por último, la consulta cuenta el número de entradas en cada grupo:

SELECT
  REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
  COUNT(*) AS count
FROM
  `TABLE`
WHERE
  json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20

Para ver ejemplos adicionales, consulta la documentación de REGEXP_EXTRACT. Para ver ejemplos de otras expresiones regulares que puedes usar, consulta Funciones, operadores y condicionales.

Búsqueda en varias columnas

En esta sección, se describen dos enfoques diferentes que puedes usar para buscar varias columnas de una tabla.

Búsqueda basada en tokens

Para buscar entradas en una tabla que coincidan con un conjunto de términos de búsqueda, usa la función SEARCH. Esta función requiere dos parámetros: dónde buscar y la consulta de búsqueda. Debido a que la función SEARCH tiene reglas específicas sobre cómo se buscan los datos, te recomendamos que leas la documentación de SEARCH.

La siguiente consulta retiene solo las filas que tienen un campo que coincide de forma exacta con “35.193.12.15”:

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `TABLE` AS t
WHERE
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20

En la consulta anterior, las comillas simples encapsulan el valor que se va a buscar. Esto garantiza que la función SEARCH busque una coincidencia exacta entre el valor de un campo y el valor entre las comillas simples.

Cuando se omiten las comillas simples en la cadena de consulta, esta se divide según las reglas definidas en la documentación de SEARCH. Por ejemplo, cuando se ejecuta la siguiente instrucción, la cadena de consulta se divide en cuatro tokens: “35”, “193”, “12” y “15”:

  SEARCH(t,"35.193.12.15")

La declaración SEARCH anterior coincide con una fila cuando un solo campo coincide con los cuatro tokens. El orden de los tokens no importa.

Puedes incluir varias sentencias SEARCH en una consulta. Por ejemplo, en la consulta anterior, podrías reemplazar el filtro en el ID de registro con una declaración como la siguiente:

  SEARCH(t,"`cloudaudit.googleapis.com/data_access`")

La declaración anterior busca en toda la tabla, mientras que la declaración original solo busca la columna log_id.

Para realizar varias búsquedas en una columna, separa las cadenas individuales con un espacio. Por ejemplo, la siguiente declaración coincide con las filas en las que un campo contiene “Hello World”, “happy” y “days”:

  SEARCH(t,"`Hello World` happy days")

Por último, puedes buscar columnas específicas de una tabla en lugar de buscar en toda la tabla. Por ejemplo, la siguiente declaración solo busca en las columnas llamadas text_payload y json_payload:

   SEARCH((text_payload, json_payload) ,"`35.222.132.245`")

Para obtener información sobre cómo se procesan los parámetros de la función SEARCH, consulta la página de referencia de BigQuery Funciones de búsqueda.

Búsqueda de subcadenas

Si quieres realizar una prueba que no distingue mayúsculas de minúsculas para determinar si existe un valor en una expresión, usa la función CONTAINS_SUBSTR. Esta función muestra TRUE cuando el valor existe y FALSE en caso contrario. El valor de búsqueda debe ser un literal de STRING, pero no el NULL literal.

Por ejemplo, la siguiente consulta recupera todas las entradas del registro de auditoría de acceso a los datos con una dirección IP específica cuyas marcas de tiempo se encuentran en un intervalo de tiempo específico. Por último, la consulta ordena los resultados y muestra los 20 más antiguos:

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `TABLE` AS t
WHERE
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20

La consulta anterior realiza una prueba de subcadena. Por lo tanto, una fila que contiene “35.193.12.152” coincide con la declaración CONTAINS_SUBSTR.

Combinar datos de varias fuentes

Las instrucciones de consulta analizan una o más tablas o expresiones y muestran las filas de resultados procesados. Por ejemplo, puedes usar instrucciones de consulta para combinar los resultados de las declaraciones SELECT en diferentes tablas o conjuntos de datos de varias maneras y, luego, seleccionar las columnas de los datos combinados.

Combinar datos de dos tablas con uniones

Para combinar información de dos tablas, usa el de los operadores join. El tipo de unión y la cláusula condicional que usas determinan cómo se combinan y descartan las filas.

La siguiente consulta te proporciona los campos json_payload de las filas en dos tablas diferentes escritas por el mismo intervalo de seguimiento. La consulta realiza un JOIN interno sobre dos tablas para las filas en las que coinciden los valores de las columnas span_id y trace en ambas tablas. A partir de este resultado, la consulta selecciona los campos timestamp, severity y json_payload que provienen de TABLE_1, el campo json_payload de TABLE_2 y los valores de los campos span_id y trace en los que se unieron las dos tablas, y muestra hasta 100 filas:

SELECT
  a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM `TABLE_1` a
JOIN `TABLE_2` b
ON
  a.span_id = b.span_id AND
  a.trace = b.trace
LIMIT 100

Cómo combinar varias selecciones con uniones

Para combinar los resultados de dos o más declaraciones SELECT y descartar las filas duplicadas, usa el operador UNION. Para retener las filas duplicadas, usa el operador UNION ALL.

La siguiente consulta lee la hora más reciente de los datos de TABLE_1, combina el resultado con la hora más reciente de los datos de TABLE_2, ordena los datos combinados aumentando la marca de tiempo y, luego, muestra las 100 entradas más antiguas:

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM(
  SELECT * FROM `TABLE_1`
  UNION ALL
  SELECT * FROM `TABLE_2`
)
ORDER BY timestamp ASC
LIMIT 100

¿Qué sigue?

Para obtener información sobre cómo enrutar y almacenar entradas de registro, consulta los siguientes documentos:

Para obtener documentación de referencia de SQL, consulta los siguientes documentos: