Crea y guarda consultas con el lenguaje de consulta de Logging

En este documento, se describe cómo recuperar y analizar registros cuando usas el Explorador de registros mediante la escritura de consultas en el campo de editor de consultas y la realización de selecciones de los menús de filtro con las opciones incluidas en las entradas de registro. Las consultas que compilas se escriben en el lenguaje de consulta de Logging.

También puedes guardar tus consultas en la página del Explorador de registros o con el método savedQueries.create de la API de Logging.

Antes de comenzar

  • Si quieres compilar consultas, debes tener los permisos para leer los datos de registro. Estos permisos se incluyen en la función de visualizador de Logging (roles/logging.viewer). Si quieres obtener detalles sobre los permisos de IAM necesarios, consulta Permisos para la consola de Google Cloud.

  • Para guardar consultas, la función de Identity and Access Management debe incluir el permiso logging.queries.{list, create, get, update, delete}.

  • Para compartir consultas, la función de Identity and Access Management debe incluir el permiso logging.queries.share. Este permiso se incluye en las funciones de propietario (roles/owner) y administrador de Logging (roles/logging.admin).

    Para obtener una lista de los permisos asociados con cada función de Logging, consulta Funciones de Logging.

Compilar consultas

Para crear consultas con la consola de Google Cloud, haz lo siguiente:

  1. En el panel de navegación de la consola de Google Cloud, elige Logging y, luego, Explorador de registros:

    Ir al Explorador de registros

  2. Selecciona el proyecto de Google Cloud o cualquier otro recurso de Google Cloud del que quieras ver los registros.

    Para ver los registros que envías desde una cuenta de Amazon Web Services (AWS) a Logging, selecciona el proyecto de conector de AWS en el selector de recursos de la consola de Google Cloud y, luego, usa el Explorador de registros. El proyecto de conector de AWS almacena el nombre del recurso de Amazon (ARN) de tu cuenta de AWS y vincula tu cuenta de AWS a los servicios de Google Cloud. Para obtener más información, consulta Recopila métricas de cuentas de AWS.
  3. Usa el panel Consulta para compilar tu consulta.

    El panel de consulta del Explorador de registros.

    En el panel Consulta, se proporcionan varias formas de compilar y ejecutar expresiones de consulta:

    • Busca texto en todos los campos de registro.
    • Selecciona las opciones de los menús de filtro.
    • Escribe o modifica consultas con el editor de consultas.
    • Visualiza, edita o ejecuta las consultas en las pestañas Recientes, Guardados, Sugerencias y Biblioteca.

Busca texto en los campos de registro

Para buscar texto en todos los campos de registro y encontrar todas las entradas de registro que coincidan, ingresa los términos de búsqueda en el campo de búsqueda:

El campo de búsqueda del Explorador de registros en el panel de consultas.

Puedes buscar palabras y frases, y tus términos de búsqueda pueden incluir operadores booleanos y expresiones regulares:

  • Para realizar una búsqueda que no distinga mayúsculas de minúsculas en los límites de los tokens, ingresa los términos de búsqueda sin comillas dobles ni acentos graves.

    Por ejemplo, para buscar entradas de registro que contengan la palabra hello y world, ingresa hello world. Este comando, que se convierte en SEARCH("hello world"), coincide con las entradas de registro que contienen los tokens hello y world, en cualquier orden. Debido a que la búsqueda no distingue mayúsculas de minúsculas, también coincide con una entrada de registro que contiene los tokens Hello y World. La búsqueda no coincide con el token worlds.

  • Para realizar una búsqueda sin distinción de mayúsculas y minúsculas para una frase junto con los límites de tokens, encierra la frase entre acentos graves.

    Por ejemplo, para buscar la frase hello world, ingresa `hello world`. Este comando, que se convierte en SEARCH("`hello world`"), hace coincidir las entradas de registro que contienen el token hello world. La búsqueda no coincide con el token hello worlds.

  • Para realizar una búsqueda que no distinga mayúsculas de minúsculas para una substring, encierra el texto entre comillas dobles. Por ejemplo, "hello world" coincide con Hello World y Hello world. La misma consulta también coincide con hello worlds, porque la búsqueda no se realiza junto con los límites de los tokens.

Para ver tus términos de búsqueda dentro de la expresión de consulta, habilita Mostrar consulta.

Después de ingresar los términos de búsqueda, haz clic en Ejecutar consulta o presiona la tecla Intro. Los resultados de la consulta se muestran en el panel Resultados de la consulta.

Operadores booleanos

Las entradas del campo de búsqueda se convierten en expresiones booleanas que especifican un subconjunto de todas las entradas de registro en el recurso de Google Cloud seleccionado.

El campo de búsqueda admite el uso de los operadores booleanos AND, OR y NOT. Cuando uses operadores booleanos en las expresiones de búsqueda, ten en cuenta lo siguiente:

  • No puedes usar paréntesis para anidar reglas. Cualquier paréntesis en la expresión de búsqueda se analiza como términos de búsqueda.
  • Debes escribir en mayúscula los operadores booleanos. and, or y not en minúscula se analizan como términos de búsqueda, no como operadores.

Si no incluyes ningún operador, todas las frases y los términos de búsqueda se unen con AND. Puedes omitir el operador AND entre los términos de búsqueda.

Los operadores AND y OR son operadores de cortocircuito. Puedes combinar reglas AND y OR en la misma expresión. Por ejemplo, cuando se mezclan los dos operadores, la expresión a AND b OR c AND d se convierte en la siguiente expresión del lenguaje de consulta de Logging:

"a"
"b" OR "c"
"d"

El operador NOT tiene la prioridad más alta, seguido de OR y AND en ese orden.

El operador NOT realiza una negación del término posterior. Por ejemplo, NOT error muestra entradas de registro que no contienen error. También puedes reemplazar el operador NOT por el operador - (menos). Por ejemplo, las dos consultas siguientes son iguales:

"response" AND "successful" AND NOT "error"
"response successful" -"error"

Esta lógica también funciona con una frase si el operador - (menos) está fuera de las comillas. Por ejemplo, las dos consultas siguientes son iguales:

-"response successful"
NOT "response successful"

Crea consultas con menús de filtro

Puedes usar los menús de filtro en el panel Consulta (Query) para agregar los recursos, el nombre del registro y los parámetros de gravedad del registro al campo del editor de consultas. Estas opciones corresponden a los campos LogEntry para todos los registros en Logging.

Las opciones de los menús Recurso y Nombre del registro solo muestran los registros que actualmente se almacenan en Cloud Logging.

Filtrar menús del editor de consultas

  • Resource (Recurso): Te permite especificar el resource.type y el resource.labels asociado. Puedes seleccionar un solo tipo de recurso con este menú de filtro y cero o más etiquetas de recursos para aplicar a tu consulta. El operador lógico AND une los parámetros de los recursos.
  • Nombre del registro (Log name): Te permite especificar logName. Puedes seleccionar varios nombres de registro para aplicar a tu consulta. Cuando se seleccionan varios nombres de registro, se usa el operador lógico OR.
  • Gravedad (Severity): Te permite especificar la gravedad. Puedes seleccionar varios niveles de gravedad al mismo tiempo para agregarlos a tu consulta. Cuando se seleccionan varios niveles de gravedad, se usa el operador lógico OR.

Para usar cualquiera de los menús de filtro, haz lo siguiente:

  1. Expande el Menú de en cualquiera de los menús de filtro del panel Consulta.

  2. Define mejor los parámetros del filtro.

  3. Haz clic en Aplicar. Puedes ver los parámetros en el campo query-editor.

    Para ver tus términos de búsqueda dentro de la expresión de consulta, habilita Mostrar consulta.

  4. Después de revisar la consulta, haz clic en Ejecutar consulta. Los resultados de la consulta se muestran en el panel Resultados de la consulta.

Para ciertos tipos de recursos de Compute Engine, como gce_instance y gce_network, verás el nombre del recurso con el ID del recurso como subtexto. Por ejemplo, para el tipo de recurso gce_instance, verás el nombre de la VM junto con el ID. Los nombres de los recursos te ayudan a identificar el ID de recurso correcto en el que puedes crear consultas.

Visualiza registros por intervalo de tiempo

Existen dos maneras de mostrar los registros que se escribieron en un intervalo de tiempo específico:

  1. Usa el selector de intervalo de tiempo.
  2. Incluye una expresión de marca de tiempo en el campo query-editor.

Usa el selector de intervalo de tiempo

El intervalo de tiempo predeterminado es de una hora, pero puedes seleccionar entre las opciones de tiempo predeterminadas, especificar una hora personalizada de inicio y finalización, o centrar el intervalo de tiempo alrededor de una marca de tiempo específica con el selector de intervalo de tiempo. Por ejemplo, si deseas ver los datos de la última semana, selecciona Última semana en el selector de rango de tiempo.

También puedes configurar tus preferencias de zona horaria con el selector de intervalo de tiempo.

Incluye una expresión de marca de tiempo en el campo query-editor

Para agregar una expresión de marca de tiempo directamente al campo del editor de consultas, usa el lenguaje de consulta de Logging.

Si el campo del editor de consultas contiene una expresión con una marca de tiempo, el selector de intervalo de tiempo está inhabilitado y la consulta usa la expresión de marca de tiempo como su restricción de intervalo de tiempo. Si una consulta no usa una expresión de marca de tiempo, usa el selector de intervalo de tiempo como su restricción.

Escribe consultas avanzadas con el lenguaje de consulta de Logging

Puedes usar el lenguaje de consulta de Logging para crear consultas más avanzadas en el campo del editor de consultas del Explorador de registros:

  1. Si no ves el campo del editor de consultas en el panel Consulta, habilita Mostrar consulta.

  2. Ingresa tus expresiones de consulta directamente en el campo del editor de consultas.

    Si agregaste términos de búsqueda en el campo de búsqueda o seleccionaste algún parámetro en los menús de filtro, esos también aparecerán en el campo del editor de consultas y se evaluarán como parte de la expresión de consulta.

  3. Después de revisar tu consulta, haz clic en Ejecutar consulta.

    Los registros que coinciden con la consulta se enumeran en el panel Resultados de la consulta. Los paneles Histograma y Campos de registro también se ajustan según la expresión de consulta.

Para ver ejemplos de consultas comunes que puedes usar, lee Muestras de consultas con el Explorador de registros.

Usar consultas recientes

Cuando ejecutas una consulta, esta se agrega a tu lista de consultas Recientes, que contiene las últimas 10,000 consultas únicas en un período de 30 días.

Para ver tus consultas recientes, selecciona la pestaña Recientes en el panel Consulta. En la pestaña Recientes, tienes las siguientes opciones:

  • Transmitir: Elige esta opción para ejecutar la consulta y transmitir los resultados.
  • Ejecutar: Elige esta opción para ejecutar la consulta.
  • More options: Te permite ver la expresión de la consulta con las opciones para ejecutarla o guardarla en tu lista de consultas guardadas. También puedes seleccionar la consulta directamente para obtener estas opciones.

    Para guardar la consulta, haz lo siguiente:

    1. Haz clic en Guardar como. Se abrirá el diálogo Guardar consulta.
    2. Completa los siguientes campos:

      • Nombre (obligatorio): Proporciona un nombre para tu consulta. Los nombres tienen un límite de 64 caracteres.
      • Descripción (opcional): Proporciona una descripción para ayudar a identificar el propósito de la consulta.
      • Incluye campos de resumen (opcional): Habilita la opción Incluir campos de resumen y, luego, ingresa los campos de resumen que deseas mostrar.
      • Truncar campos de resumen (opcional): Habilita la opción Truncar campos de resumen y selecciona el número de caracteres para truncarlos y si el truncamiento se produce al principio o al final de los campos.
    3. Haz clic en Guardar consulta. La consulta ahora está disponible en tu lista de consultas guardadas.

También puedes ordenar y filtrar tus consultas recientes; el filtro coincide con el texto de la expresión de consulta.

Guardar consultas

Las consultas guardadas te permiten almacenar expresiones de consulta para ayudarte a explorar los registros de manera más coherente y eficiente. El panel Consulta del Explorador de registros incluye una pestaña Guardados, en la que puedes acceder a tus consultas guardadas. También puedes guardar tus consultas con el método savedQueries.create de la API de Logging.

Console

Para guardar una expresión de consulta que compilaste en el campo de editor de consultas, haz lo siguiente:

  1. Haz clic en Guardar en el panel Consulta. Se abrirá el diálogo Guardar consulta con tu expresión de consulta en el campo del editor de consultas.

  2. Completa los siguientes campos:

    • Nombre (obligatorio): Proporciona un nombre para tu consulta. Los nombres tienen un límite de 64 caracteres.
    • Descripción (opcional): Proporciona una descripción para ayudar a identificar el propósito de la consulta.
    • Incluye campos de resumen personalizados (opcional): Habilita Incluir campos de resumen y, luego, ingresa los campos de resumen que deseas mostrar.
    • Truncar campos de resumen (opcional): Habilita la opción Truncar campos de resumen y selecciona el número de caracteres para truncarlos y si el truncamiento se produce al principio o al final de los campos.
  3. Haz clic en Guardar consulta. Tus consultas guardadas aparecen en una lista en la pestaña Saved.

Para ejecutar una consulta guardada, haz clic en Ejecutar. Para ejecutar la consulta y transmitir los resultados, haz clic en Transmitir.

También puedes ordenar y filtrar tus consultas guardadas; el filtro coincide con el texto en la expresión de consulta.

API

Para guardar una consulta mediante la API de Logging, usa el método savedQueries.create. Si deseas obtener más información sobre este método, sus parámetros y los datos de respuesta, consulta la página de referencia de savedQueries.create.

Puedes ejecutar el método savedQueries.create con el widget del Explorador de APIs en la página de referencia del método. Para las consultas del explorador de registros, debes especificar el campo loggingQuery. En el siguiente ejemplo, se muestra un cuerpo de solicitud de muestra, que contiene una instancia de SavedQuery:

{
"parent": "projects/my-project/locations/global"
"savedQueryId": "compute-query"
{
  "displayName": "compute-admin-activity-query",
  "description": "Queries for Compute Engine Admin Activity logs.",

  "loggingQuery":
    {
      "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
    },
  "visibility": "PRIVATE"
}
}

Compartir consultas

Las consultas compartidas permiten a los usuarios de un proyecto de Google Cloud compartir sus consultas guardadas entre sí. Puedes ver las consultas compartidas en la pestaña Guardados.

Si deseas conocer los roles y permisos necesarios para ver y editar consultas compartidas, consulta Permisos de la consola de Google Cloud. Ten en cuenta que los usuarios que tienen el rol de IAM roles/logging.admin o roles/editor pueden editar las consultas compartidas de otros usuarios.

Crear una consulta compartida

Console

Puedes compartir consultas que ya guardaste o puedes compartir una nueva.

Para crear y compartir una consulta, haz lo siguiente:

  1. Ingresa una consulta en el campo del editor de consultas.

  2. Haz clic en Guardar.

  3. Completa los campos en el diálogo Guardar consulta.

  4. Habilita Compartir con el proyecto.

  5. Haz clic en Guardar consulta.

Tu consulta ahora se comparte con otros usuarios del proyecto de Google Cloud.

Para compartir una consulta ya guardada, sigue estos pasos:

  1. Selecciona la pestaña Guardadas (Saved).

  2. Selecciona Más opciones y, luego, Editar, o selecciona la consulta directamente.

  3. En el diálogo Editar consulta, habilita Compartir con el proyecto y, luego, haz clic en Actualizar consulta.

Tu consulta ahora se comparte con otros usuarios del proyecto de Google Cloud.

API

Puedes usar la API de Logging para crear una consulta compartida a través del método savedQueries.Create y especificando un valor de SHARED en el campo visibility.

Ver consultas compartidas

Console

Para ver todas las consultas compartidas con rapidez, ordena la columna Visibilidad para mostrar primero las consultas compartidas:

  1. Selecciona la pestaña Guardadas (Saved).

  2. Haga clic en Todos.

  3. Ordena la columna Visibilidad (Visibility).

La columna Visibilidad indica si se comparten las consultas y de qué manera:

  • Compartidos por mí: Consultas que guardaste y compartiste con otros usuarios del proyecto de Google Cloud.
  • Compartidos: Consultas que compartieron otros usuarios del proyecto de Google Cloud.
  • Privadas: Consultas que guardaste y no compartiste con otros usuarios del proyecto de Google Cloud.

Ver solo tus consultas

Para ver las consultas guardadas que creaste o compartiste, haz clic en Minas. Ahora verás una lista de consultas que creaste y guardaste. En la columna Visibilidad, puedes ver tus consultas Privadas no compartidas. Las consultas que compartiste se identifican con Compartidas por mí (Shared by me).

Usa las consultas sugeridas

Logging genera consultas sugeridas según el contexto de tu proyecto de Google Cloud, como los productos de Google Cloud que usas. Las consultas sugeridas pueden ayudarte a identificar problemas y brindarte estadísticas sobre el estado general de tus sistemas. Por ejemplo, si detectas que usas Google Kubernetes Engine, Logging podría sugerir una consulta que encuentra todos los registros de errores de tus contenedores.

Para ver y ejecutar consultas sugeridas, selecciona la pestaña Suggested en el panel Query (Consulta). En la pestaña Suggested, se muestra una lista de consultas, cada una con descripciones y las siguientes opciones:

  • Transmitir: Elige esta opción para ejecutar la consulta y transmitir los resultados.
  • Ejecutar: Elige esta opción para ejecutar la consulta.
  • More options: Te permite ver los detalles de la expresión de consulta con las opciones para ejecutar la consulta o guardarla. También puedes seleccionar la consulta directamente para obtener estas opciones.

    Para revisar los detalles de una consulta sugerida, realiza una de las siguientes acciones:

    • Selecciona la fila de la consulta.

    • Haz clic en Más y selecciona Ver. Se abrirá el diálogo Detalles de la consulta.

    En el diálogo Detalles de la consulta, verás la consulta y las opciones Ejecutar, Transmitir o Guardar como:

    • Para guardar la consulta, haz lo siguiente:

      1. Haz clic en Guardar como.
      2. Completa los campos en el diálogo Guardar consulta.

      La consulta editada aparecerá en tu lista Guardados, en donde puedes elegir ejecutar la consulta más tarde.

    • Para ejecutar la consulta ahora, haz clic en Ejecutar. La consulta se ejecuta y aparece en el campo del editor de consultas.

    • Para ejecutar la consulta ahora y transmitir los resultados, haz clic en Transmitir.

    • Para cerrar el diálogo y volver a la lista de consultas sugeridas, haz clic en Cerrar.

Ten en cuenta los siguientes comportamientos esperados:

  • Es posible que las cargas de páginas sucesivas no muestren las mismas consultas en el mismo orden.
  • Es posible que no veas ninguna consulta sugerida.
  • En ocasiones, cuando se ejecuta una consulta sugerida, se muestra cero registros.

Selecciona consultas de la biblioteca

Logging proporciona una biblioteca de consultas basadas en casos prácticos comunes y productos de Google Cloud. Estas consultas pueden ayudarte a encontrar registros de manera eficiente durante las sesiones de solución de problemas de momentos críticos y explorar tus registros para comprender mejor qué datos de registro están disponibles.

Para ver y ejecutar las consultas de la biblioteca, haz lo siguiente:

  1. Selecciona la pestaña Biblioteca en el panel Consulta.

  2. En la columna Todas las consultas, verás amplias categorías de consultas disponibles y subconjuntos de consultas basados en los productos de Google Cloud. Para limitar la selección de consultas que ves, haz clic en cualquiera de los productos.

    También puedes usar el campo de búsqueda para buscar las consultas disponibles por categoría, descripción o el contenido de la expresión de consulta.

  3. Para revisar una expresión de consulta, realiza una de las siguientes acciones:

    a. Haz clic en la fila de la consulta.

    b. Haz clic en Más y selecciona Ver.

  4. En el cuadro de diálogo Detalles de la consulta (Query details), verás la consulta y las opciones Ejecutar, Transmitir o Guardar como:

    • Para guardar la consulta, haz lo siguiente:

      1. Haz clic en Guardar como.
      2. Completa los campos en el diálogo Guardar consulta.

      La consulta editada aparecerá en tu lista Guardados, en donde puedes elegir ejecutar la consulta más tarde.

    • Para ejecutar la consulta ahora, haz clic en Ejecutar. La consulta se ejecuta y aparece en el campo del editor de consultas.

    • Para ejecutar la consulta ahora y transmitir los resultados, haz clic en Transmitir.

    • Para cerrar el diálogo y volver a la lista de consultas sugeridas, haz clic en Cerrar.

¿Qué sigue?