Compila 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 escribiendo consultas en el campo del editor de consultas y seleccionando opciones de filtro predefinidas. Las consultas que crees se escribirán 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 de la API de Logging savedQueries.create.

Antes de comenzar

El rol de visualizador de registros (roles/logging.viewer) proporciona acceso para ver los registros. Por ejemplo, cuando se te otorga este rol, puedes escribir y ejecutar consultas. También puedes guardar consultas como privadas y ejecutar consultas privadas y compartidas. Sin embargo, este rol no te permite guardar ni modificar consultas compartidas. Si deseas guardar o modificar consultas compartidas, asegúrate de que se te haya otorgado el rol de administrador de Logging (roles/logging.admin), que proporciona acceso completo a Cloud Logging.

Realiza una de las siguientes acciones:

• Para obtener los permisos que necesitas para escribir y ejecutar consultas, ejecutar y guardar consultas privadas, y ejecutar consultas compartidas, pídele a tu administrador que te otorgue el rol de IAM de Visualizador de registros (roles/logging.viewer) en tu proyecto.

• Para obtener los permisos que necesitas para escribir y ejecutar consultas, ejecutar y guardar consultas privadas, y ejecutar, crear y administrar consultas compartidas, pídele a tu administrador que te otorgue el rol de IAM de Administrador de Logging (roles/logging.admin) en tu proyecto.

Para obtener más información sobre los permisos de IAM necesarios, consulta Permisos para la consola de Google Cloud .

Compilar consultas

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

1. En la consola de Google Cloud , accede a la página Explorador de registros:

   Acceder al Explorador de registros

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

2. Selecciona el Google Cloud proyecto o algún otro Google Cloudrecurso para el que deseas ver los registros.

3. Usa el panel Consulta para crear tu consulta.

   El panel Query proporciona varias formas de compilar y ejecutar expresiones de consulta:

   • Busca texto en todos los campos de registro.
   • Selecciona opciones en los menús de filtro.
   • Escribe o modifica consultas con el editor de consultas.
   • Visualiza y ejecuta consultas guardadas, recientes y sugeridas desde la biblioteca de consultas .

Cómo buscar 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 del panel Consulta.

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 distingue mayúsculas de minúsculas, debes usar una expresión regular.

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

  Por ejemplo, para buscar entradas de registro que contengan la palabra hello y la palabra 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. Como 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 de una frase que no distinga mayúsculas de minúsculas a lo largo de los límites de los 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`"), coincide con 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 de una subcadena que no distinga mayúsculas de minúsculas, encierra el texto entre comillas dobles. Por ejemplo, "hello world" coincide con Hello World y Hello world. La misma búsqueda también coincide con hello worlds, ya que no se realiza a lo largo de los límites de los tokens.

  Nota: Las búsquedas de subcadenas son más lentas que las búsquedas basadas en tokens. Por lo tanto, te recomendamos que uses búsquedas basadas en tokens siempre que sea posible.

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 Google Cloud seleccionado.

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

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

Si no incluyes ningún operador, todos los términos y frases de búsqueda se unirán 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 deAND 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 devuelve entradas de registro que no contienen error. También puedes reemplazar el operador NOT por el operador - (menos). Por ejemplo, las siguientes dos consultas 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 siguientes dos consultas son equivalentes:

-"response successful"

NOT "response successful"

Cómo crear consultas con menús de filtros

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

Las opciones de los menús Recurso y Nombre del registro se derivan de las entradas de registro que almacena Cloud Logging.

• Resource: Te permite especificar el resource.type y el resource.labels asociado. Puedes seleccionar un solo tipo de recurso con este menú de filtros y cero o más etiquetas de recursos para aplicar a tu consulta. Los parámetros del recurso se unen con el operador lógico AND.
• Nombre del registro (Log name): Te permite especificar logName. Puedes seleccionar varios nombres de registro para aplicar a tu consulta. Cuando seleccionas 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 aplicarlos a tu búsqueda. Cuando seleccionas varios niveles de gravedad, se usa el operador lógico OR.
• Correlacionar por: Te permite agrupar y ver las entradas de registro en un formato "principal-secundario". Para obtener más información, consulta Cómo correlacionar entradas de registro.

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

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

2. Define mejor los parámetros del filtro.

3. Haz clic en Aplicar. Verás los parámetros en el campo del editor de consultas.

   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 texto secundario. Por ejemplo, para el tipo de recurso gce_instance, verás el nombre de la VM junto con su ID. Los nombres de los recursos te ayudan a identificar el ID de recurso correcto, sobre el cual puedes crear consultas.

Visualiza registros por período

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

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

Usa el selector de intervalo de tiempo

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

También puedes configurar tus preferencias de zona horaria con el selector de período.

Incluye una expresión de marca de tiempo en el campo del editor de consultas

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

Si el campo del editor de consultas contiene una expresión con una marca de tiempo, el selector de intervalos de tiempo se inhabilita 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, usará el selector de intervalos de tiempo como su restricción de intervalo de tiempo.

Escribe consultas avanzadas con el lenguaje de consultas de Logging

Puedes usar el lenguaje de consultas de Logging para compilar 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 parámetros en los menús de filtros, estos también aparecerán en el campo del editor de consultas y se evaluarán como parte de tu expresión de consulta.

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

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

Para ver ejemplos de consultas comunes que te pueden interesar, consulta Ejemplos de consultas con el Explorador de registros.

Nota: La longitud de una consulta no puede superar los 20,000 caracteres.

Cómo usar las búsquedas recientes

Cuando ejecutas cualquier consulta, esta se agrega a la Biblioteca de consultas , que contiene las últimas 10,000 consultas únicas en un período de 30 días.

Para ver tus consultas recientes, selecciona el botón Biblioteca de consultas en la barra de herramientas principal. En el caso de las consultas 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.

• Más opciones: Te permite ver la expresión de consulta con las opciones para ejecutar la consulta 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. Se abrirá el diálogo Guardar consulta.

  2. Completa los siguientes campos:

     • Nombre (obligatorio): Proporciona un nombre para la 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.
     • Incluir campos de resumen (opcional): Habilita Incluir campos de resumen e ingresa los campos de resumen que deseas mostrar.
     • Truncar los campos de resumen (opcional): Habilita Truncar los campos de resumen y selecciona la cantidad de caracteres que deseas truncar y si el truncamiento debe ser 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 búsquedas recientes. El filtro coincide con el texto de la expresión de tu búsqueda.

Guarda y comparte consultas

Nota: Si tus datos se administran a través de un entorno de Assured Workloads, es posible que esta función se vea afectada o restringida. Para obtener más información, consulta Restricciones y limitaciones en Assured Workloads.

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

Puedes guardar tu consulta de forma privada para que solo tú la veas, o bien puedes compartirla con otros miembros del proyecto Google Cloud . Una vez que compartes una consulta, ya no te pertenece, y cualquier miembro del proyecto con los permisos necesarios puede acceder a ella.

Console

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

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

2. Completa los siguientes campos:

   • Nombre (obligatorio): Proporciona un nombre para la 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.
   • Incluir campos de resumen personalizados (opcional): Habilita Incluir campos de resumen y, luego, ingresa los campos de resumen que deseas mostrar.
   • Truncar los campos de resumen (opcional): Habilita Truncar los campos de resumen y selecciona la cantidad de caracteres que deseas truncar y si el truncamiento debe ser al principio o al final de los campos.
   • Compartir con el proyecto: De manera opcional, habilita Compartir con el proyecto para compartir tu consulta con otros miembros del proyecto Google Cloud .

3. Haz clic en Guardar consulta. Las consultas guardadas aparecen en una lista en la pestaña Guardadas.

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

Para modificar una búsqueda guardada, selecciona Más opciones y, luego, Editar. También puedes seleccionar la consulta, realizar modificaciones y, luego, guardar la consulta modificada.

Para borrar una búsqueda guardada, selecciona Más opciones y, luego, Borrar.

También puedes ordenar y filtrar tus búsquedas guardadas. El filtro coincide con el texto de la expresión de tu búsqueda.

API

Para guardar una consulta con la API de Logging, usa el método savedQueries.create. Para 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. En el caso de las consultas del Explorador de registros, debes especificar el campo loggingQuery. En el siguiente ejemplo, se ilustra 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"
  }
}

Para compartir la consulta con otros miembros del Google Cloud proyecto, especifica un valor de SHARED en el campo visibility.

Ver las búsquedas guardadas

Para ver las consultas privadas y las que se comparten con otros miembros del proyecto, haz clic en el botón Biblioteca de consultas: Google Cloud

Console

1. En la consola de Google Cloud , accede a la página Explorador de registros:

   Acceder al Explorador de registros

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

2. Selecciona el Google Cloud proyecto o algún otro Google Cloudrecurso para el que deseas ver los registros.

3. Haz clic en el botón Biblioteca de consultas y, luego, en Guardadas.

Puedes ordenar la tabla por cualquier encabezado. En la columna Visibilidad, se indica si las búsquedas son privadas o compartidas:

• Compartidas: Son las consultas que se comparten con otros miembros del proyectoGoogle Cloud .
• Privadas: Son las consultas que guardaste y que solo tú puedes ver.

API

Puedes usar la API de Logging para ver las búsquedas privadas y compartidas con el método savedQueries.list.

Por ejemplo, el siguiente cuerpo de la solicitud enumera todas las consultas compartidas del Explorador de registros con un ID de ubicación comodín:

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

Cómo usar las consultas sugeridas

Logging genera consultas sugeridas en función del contexto de tu proyectoGoogle Cloud , como los productos 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 busque todos los registros de errores para tus contenedores.

Para ver y ejecutar consultas sugeridas, haz clic en el botón Biblioteca de consultas y, luego, en Sugeridas. En la pestaña Sugerencias, 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.

• Más opciones: Te permite ver los detalles de la expresión de la consulta con las opciones para ejecutarla 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 para Ejecutar, Transmitir o Guardar como:

  • Para guardar la consulta, haz lo siguiente:

    1. Haz clic en Guardar consulta.
    2. Completa los campos del cuadro de diálogo Guardar consulta.

    La consulta editada aparecerá en tu lista Guardada, en la que 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 sugerencias de búsqueda, 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 veas cero consultas sugeridas.
• A veces, si ejecutas una consulta sugerida, no se devuelven registros.

Selecciona consultas de la biblioteca

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

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

1. En la consola de Google Cloud , accede a la página Explorador de registros:

   Acceder al Explorador de registros

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

2. Selecciona el Google Cloud proyecto o algún otro Google Cloudrecurso para el que deseas ver los registros.

3. Haz clic en el botón Biblioteca de consultas . Verás categorías de búsquedas disponibles y subconjuntos de búsquedas basados en productos de Google Cloud. Para reducir 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 la consulta.

4. Para revisar una expresión de búsqueda, realiza una de las siguientes acciones:

   a. Haz clic en la fila de la consulta.

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

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

   • Para guardar la consulta, haz lo siguiente:

     1. Haz clic en Guardar consulta.
     2. Completa los campos del cuadro de diálogo Guardar consulta.

     La consulta editada aparecerá en tu lista Guardada, en la que 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 sugerencias de búsqueda, haz clic en Cerrar.

¿Qué sigue?

• Ejemplos de búsquedas