Crear y guardar consultas con el lenguaje de consulta de Logging

En este documento se describe cómo obtener y analizar registros cuando se usa Explorador de registros. Para ello, se escriben consultas en el campo del editor de consultas y se seleccionan opciones de filtro predefinidas. Las consultas que crees se escriben en el lenguaje de las consultas de Logging.

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

Antes de empezar

El rol Visualizador de registros (roles/logging.viewer) permite ver los registros. Por ejemplo, si se te asigna este rol, puedes escribir y ejecutar consultas. También puedes guardar consultas como privadas y ejecutar tanto consultas privadas como compartidas. Sin embargo, este rol no te permite guardar ni modificar consultas compartidas. Si quieres guardar o modificar consultas compartidas, asegúrate de que se te ha concedido el rol Administrador de Logging (roles/logging.admin), que proporciona acceso completo a Cloud Logging.

Elige una de estas opciones:

  • Para obtener los permisos que necesitas para escribir y ejecutar consultas, ejecutar y guardar consultas privadas, y ejecutar consultas compartidas, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Lector 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 gestionar consultas compartidas, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de registro (roles/logging.admin) en tu proyecto.

Para obtener más información sobre los permisos de gestión de identidades y accesos necesarios, consulta Permisos de la consola Google Cloud .

Consultas de compilación

Para crear consultas con la consola Google Cloud , sigue estos pasos:

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

    Ve al Explorador de registros.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

  2. Selecciona el proyecto Google Cloud u otro recurso Google Cloud del que quieras ver los registros.

  3. Usa el panel Consulta para crear tu consulta.

    El panel Consulta ofrece varias formas de crear y ejecutar expresiones de consulta:

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

Buscar texto en campos de registro

Para buscar texto en todos los campos de registro y encontrar todas las entradas de registro coincidentes, introduce 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 hacer una búsqueda que distinga entre mayúsculas y minúsculas, debes usar una expresión regular.

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

    Por ejemplo, para buscar entradas de registro que contengan la palabra hello y la palabra world, introduce 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 en la búsqueda no se distingue entre mayúsculas y minúsculas, también se incluye 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 que no distinga entre mayúsculas y minúsculas de una frase a lo largo de los límites de los tokens, encierra la frase entre comillas inversas.

    Por ejemplo, para buscar la frase hello world, escribe `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 sin distinguir entre mayúsculas y minúsculas, escribe 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 en los límites de los tokens.

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

Después de introducir los términos de búsqueda, haz clic en Ejecutar consulta o pulsa 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 del recurso seleccionado. Google Cloud

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.
  • Los operadores booleanos deben escribirse en mayúsculas. Las minúsculas and, or y not 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 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 devuelve las entradas de registro que no contienen error. También puedes sustituir 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"

Crear consultas con menús de filtros

Puede usar los menús de filtro del panel Consulta para añadir parámetros de recurso, nombre de registro, gravedad del registro y correlación al campo del editor de consultas. Estas opciones se corresponden con los campos LogEntry de todos los registros de Logging.

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

  • Recurso: le permite especificar el resource.type y el resource.labels asociado. Puedes seleccionar un solo tipo de recurso mediante este menú de filtros y cero o más etiquetas de recursos para aplicarlas a tu consulta. Los parámetros de recursos se unen mediante el operador lógico AND.
  • Nombre del registro: le permite especificar el logName. Puedes seleccionar varios nombres de registro para aplicarlos a tu consulta. Cuando se seleccionan varios nombres de registro, se usa el operador lógico OR.
  • Gravedad: permite especificar la gravedad. Puede seleccionar varios niveles de gravedad al mismo tiempo para añadirlos a su consulta. Cuando se seleccionan 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 de "principal-secundario". Para obtener más información, consulta Correlacionar entradas de registro.

Para usar cualquiera de los menús de filtros, siga estos pasos:

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

  2. Define los parámetros del filtro.

  3. Haz clic en Aplicar. Los parámetros se muestran en el campo del editor de consultas.

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

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

En el caso de determinados tipos de recursos de Compute Engine, como gce_instance y gce_network, verás el nombre del recurso con el ID del recurso como subtítulo. Por ejemplo, en el tipo de recurso gce_instance, verás el nombre de la VM junto con su ID. Los nombres de los recursos le ayudan a identificar el ID de recurso correcto, sobre el que puede crear consultas.

Ver registros por intervalo de tiempo

Hay dos formas 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 del editor de consultas.

Usar el selector de intervalo de tiempo

El intervalo de tiempo predeterminado es de una hora, pero puedes seleccionar una de las opciones predefinidas, especificar una hora de inicio y de 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 quiere ver los datos de la semana pasada, seleccione Última semana en el selector de periodo.

También puedes definir tus preferencias de zona horaria con el selector de periodo.

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

Para añadir una expresión de marca de tiempo directamente al campo del editor de consultas, usa el lenguaje de consultas de registro.

Si el campo del editor de consultas contiene una expresión con una marca de tiempo, el selector de intervalo de tiempo se inhabilita y la consulta usa la expresión de marca de tiempo como restricción de intervalo de tiempo. Si una consulta no usa una expresión de marca de tiempo, la consulta usa el selector de periodo como restricción de periodo.

Escribir consultas avanzadas con el lenguaje de las consultas de Logging

Puedes usar el lenguaje de consultas de registro 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. Introduce tus expresiones de consulta directamente en el campo del editor de consultas.

    Si ha añadido términos de búsqueda en el campo de búsqueda o ha seleccionado parámetros en los menús de filtros, también aparecerán en el campo del editor de consultas y se evaluarán como parte de la expresión de la consulta.

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

    Los registros que coinciden con tu consulta se muestran 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 habituales que puedes usar, consulta Consultas de ejemplo con el Explorador de registros.

Usar consultas recientes

Cuando ejecutas una consulta, se añade a la biblioteca de consultas, que contiene las últimas 10.000 consultas únicas de un periodo 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 la consulta con las opciones para ejecutarla o guardarla en tu lista de consultas Guardadas. También puedes seleccionar la consulta directamente para ver estas opciones.

    Para guardar la consulta, sigue estos pasos:

    1. Haz clic en Guardar. Se abrirá el cuadro de diálogo Guardar consulta.

    2. Rellena los siguientes campos:

      • Nombre (obligatorio): indica un nombre para la consulta. Los nombres tienen un límite de 64 caracteres.
      • Descripción (opcional): proporciona una descripción para identificar el propósito de la consulta.
      • Incluir campos de resumen (opcional): habilite Incluir campos de resumen e introduzca los campos de resumen que quiera mostrar.
      • Truncar campos de resumen (opcional): habilita Truncar campos de resumen y selecciona el número de caracteres que quieres truncar y si el truncamiento se produce al principio o al final de los campos.

    3. Haz clic en Guardar consulta. La consulta ya está disponible en tu lista de consultas guardadas.

También puedes ordenar y filtrar tus consultas recientes. El filtro se aplica al texto de tu expresión de consulta.

Guardar y compartir consultas

Las consultas guardadas te permiten almacenar expresiones de consulta para explorar tus registros de forma más coherente y eficiente. Explorador de registros incluye una biblioteca de consultas, donde puedes acceder a las consultas guardadas. También puedes guardar tus consultas con el método savedQueries.create de la API Logging.

Puedes guardar tu consulta para que sea privada y solo tú puedas verla, o bien puedes compartirla con otros miembros del Google Cloud proyecto. Una vez que compartes una consulta, deja de ser de tu propiedad y cualquier miembro del proyecto con los permisos necesarios puede acceder a ella.

Consola

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

  1. En el panel Consulta, haz clic en Guardar. Se abre el cuadro de diálogo Guardar consulta, con la expresión de la consulta en el campo del editor de consultas.

  2. Rellena los siguientes campos:

    • Nombre (obligatorio): indica un nombre para la consulta. Los nombres tienen un límite de 64 caracteres.
    • Descripción (opcional): proporciona una descripción para identificar el propósito de la consulta.
    • Incluir campos de resumen personalizados (opcional): habilite Incluir campos de resumen e introduzca los campos de resumen que quiera que se muestren.
    • Truncar campos de resumen (opcional): habilita Truncar campos de resumen y selecciona el número de caracteres que quieres truncar y si el truncamiento se produce al principio o al final de los campos.
    • Compartir con el proyecto: si quieres, 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 consulta guardada, selecciona Más opciones y, a continuación, Editar. También puede seleccionar la consulta, hacer modificaciones y guardar la consulta modificada.

Para eliminar una consulta guardada, selecciona Más opciones y, a continuación, Eliminar.

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

API

Para guardar una consulta mediante la API 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 mediante el widget Explorador de APIs en la página de referencia del método. En las consultas del Explorador de registros, debe 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"
  }
}

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

Ver consultas guardadas

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

Consola

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

    Ve al Explorador de registros.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

  2. Selecciona el proyecto Google Cloud u otro recurso Google Cloud del que quieras ver los registros.

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

Puede ordenar la tabla por cualquier encabezado. La columna Visibilidad indica si las consultas son compartidas o privadas:

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

API

Puedes usar la API Logging para ver consultas privadas y compartidas mediante el método savedQueries.list.

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

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

Usar consultas sugeridas

El registro genera consultas sugeridas en función del contexto de tuGoogle Cloud proyecto Google Cloud , como los productos que estés usando. Las consultas sugeridas pueden ayudarte a identificar problemas y proporcionarte estadísticas sobre el estado general de tus sistemas. Por ejemplo, si detecta que usas Google Kubernetes Engine, Logging puede sugerirte una consulta que busque todos los registros de errores de tus contenedores.

Para ver y ejecutar las consultas sugeridas, haz clic en el botón Biblioteca de consultas y, a continuación, en Sugerencias. En la pestaña Sugerencias, tiene 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 consulta con las opciones para ejecutar la consulta o guardarla. También puedes seleccionar la consulta directamente para ver estas opciones.

    Para consultar los detalles de una consulta sugerida, haz una de las siguientes acciones:

    • Selecciona la fila de la consulta.

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

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

    • Para guardar la consulta, sigue estos pasos:

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

      La consulta editada se muestra en la lista Guardadas, donde puede ejecutarla más adelante.

    • Para ejecutar la consulta ahora, haga 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 cuadro de 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ágina sucesivas no muestren las mismas consultas en el mismo orden.
  • Es posible que no veas ninguna consulta sugerida.
  • A veces, al ejecutar una consulta sugerida, no se devuelve ningún registro.

Seleccionar consultas de la biblioteca

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

Para ver y ejecutar las consultas de la biblioteca, sigue estos pasos:

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

    Ve al Explorador de registros.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

  2. Selecciona el proyecto Google Cloud u otro recurso Google Cloud del que quieras ver los registros.

  3. Haz clic en el botón Biblioteca de consultas. Verás categorías de consultas disponibles y subconjuntos de consultas basados en Google Cloudproductos. Para acotar 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 contenido de la expresión de la consulta.

  4. Para revisar una expresión de consulta, haz 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 cuadro de diálogo Detalles de la consulta, verás la consulta y las opciones Ejecutar, Transmitir o Guardar como:

    • Para guardar la consulta, sigue estos pasos:

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

      La consulta editada se muestra en la lista Guardadas, donde puede ejecutarla más adelante.

    • Para ejecutar la consulta ahora, haga 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 cuadro de diálogo y volver a la lista de consultas sugeridas, haz clic en Cerrar.

Siguientes pasos