Compila consultas de registros (vista previa)

En esta página, se describe cómo compilar consultas en el visor de registros de Google Cloud Console (vista previa) para recuperar los registros, definirlos mejor y analizarlos.

Antes de comenzar

No necesitas un lugar de trabajo para usar Logging, a menos que envíes registros de Amazon Web Services (AWS) a Logging.

El visor de registros muestra los registros de un solo proyecto de Google Cloud. Si utilizas un lugar de trabajo, Logging no combina los registros de los proyectos supervisados. Debes seleccionar un proyecto específico para ver sus registros.

Si usas AWS y un lugar de trabajo, selecciona el proyecto del conector de AWS para ver los registros de AWS.

Comienza ahora

Para navegar al Visor de registros (vista previa), haz lo siguiente:

  1. Ve al menú de navegación de Google Cloud  y selecciona Logging > Visor de registros:
    Ir al Visor de registros
  2. Selecciona un proyecto de Google Cloud.
  3. En el menú del selector de versiones, cambia la versión del Visor de registros de Classic (Clásico) a Preview the new Logs Viewer (Obtén una vista previa del Visor de registros nuevo).

En este momento, te encuentras en el Visor de registros (vista previa).

Compila consultas

En el panel del compilador de consultas, se proporcionan varias formas de recuperar registros:

  1. Menús desplegables del compilador de consultas
  2. Consultas mediante el lenguaje del compilador de consultas
  3. Pestaña de consultas guardadas

query-builder-pane

En las siguientes secciones, se describe cómo compilar y ejecutar consultas para recuperar tus registros.

Menús desplegables del compilador de consultas

Los menús desplegables te permiten agregar parámetros de búsqueda al Compilador de consultas. Puedes usar los menús desplegables para seleccionar los recursos, los nombres de registros, la gravedad del registro y los intervalos de tiempo. Estas opciones corresponden a los campos LogEntry de todos los registros de Google Cloud's operations suite.

Menús desplegables del compilador de consultas

  • Resource (Recurso): Te permite especificar resource.type. Puedes seleccionar solo un recurso a la vez para agregarlo al Compilador de consultas. En las entradas, se usa el operador lógico AND.
  • Log name (Nombre del registro): Te permite especificar logName. Puedes seleccionar varios nombres de registro a la vez para agregarlos al Compilador de consultas. Cuando seleccionas varias entradas, se usa el operador lógico OR.
  • Severity (Gravedad): Te permite especificar severity. Puedes seleccionar varios niveles de gravedad a la vez para agregarlos al Compilador de consultas. Cuando seleccionas varias entradas, se usa el operador lógico OR.

Para usar cualquiera de los menús de los parámetros de búsqueda, debes expandirlos, seleccionar uno o varios parámetros y, luego, hacer clic en Agregar.

Una vez que hayas compilado la consulta, haz clic en Ejecutar consulta para recuperar las entradas de registro que desees.

Consultas con una restricción de tiempo

Existen dos maneras de consultar registros en función del tiempo:

  1. Consulta mediante una expresión de marca de tiempo
  2. Consulta mediante el selector de intervalos de tiempo

    En la sección del visor de registros, se muestran dos maneras de filtrar en función del tiempo

Si tienes una consulta 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.

Consultas mediante el lenguaje del compilador de consultas

Puedes usar el lenguaje del compilador de consultas para compilar consultas en el panel del compilador de consultas de Cloud Logging, así como en la API de Logging o la interfaz de línea de comandos.

Para obtener más detalles, consulta el lenguaje del compilador de consultas.

A continuación, se proporcionan algunas sugerencias para optimizar tus consultas.

Optimiza tus consultas

Para encontrar entradas de registro de manera más eficiente, haz lo siguiente:

  • Busca con campos indexados.
  • Minimiza la cantidad de entradas de registro que se deben buscar.

Usa campos indexados

A fin de aprovechar el índice, especifica los valores exactos para los campos indexados mediante el operador de igualdad. No uses coincidencias de substrings.

Los campos LogEntry siguientes están indexados:

En las siguientes secciones, se explica cómo usar estos campos indexados para minimizar la cantidad de entradas de registro que se consultarán.

Encuentra entradas de registro con rapidez

Puedes hacer que tus búsquedas sean más rápidas si reduces la cantidad de registros, la cantidad de entradas de registro o el intervalo de tus búsquedas. Aún mejor, puedes reducir los tres.

Ejemplo: Usa el nombre de registro correcto

Especifica el registro que contiene las entradas de registro que te interesan. Asegúrate de conocer el nombre de registro real mediante la inspección de una de tus entradas de registro. Por ejemplo, el visor de registros muestra que hay un registro en la sección de Compute Engine que se llama “activity_log”. En una inspección más detallada de las entradas de registro de actividad, el nombre real del registro es “compute.googleapis.com/activity_log”.

La comparación siguiente es incorrecta. No coincide con nada porque usa el nombre de registro incorrecto, como se ve a continuación:

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

La comparación siguiente es correcta. Elige entradas de registro del registro de actividades. Debes codificar como URL el nombre del registro, como se muestra a continuación:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

Ejemplo: elige el nombre de registro correcto

Si sabes que las entradas de registro que deseas provienen de una instancia de VM particular, especifícalas. Verifica los nombres de las etiquetas correctas mediante la inspección de una de las entradas de registro que deseas buscar. En el siguiente ejemplo, instance_id es una de las etiquetas indexadas:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

Debes especificar un valor para el tipo de recurso. De lo contrario, la comparación de instance_id no usa el índice.

Ejemplo: Elige el período correcto

Debes especificar un período para buscar. Una forma rápida de determinar las marcas de tiempo útiles en el formato RFC 3339 es usar el comando date de Gnu/Linux:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Usa los valores de estas marcas de tiempo en las siguientes consultas. A fin de crear una marca de tiempo que Logging acepte, reemplaza el espacio entre la fecha y la hora por la letra T.

Por ejemplo, usa esto para buscar dentro de las últimas tres horas:

    timestamp >= "2016-06-27T14:40:00-04:00"

Como otro ejemplo, para buscar entre tres y cinco horas atrás, usa esto:

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

Para obtener otro ejemplo del uso de marcas de tiempo, consulta los índices de campo temporales en esta página.

Minimiza las búsquedas globales y de substring

Evita usar combinaciones de teclas cuando escribas las consultas de registro.

Ejemplo: No uses substrings en campos indexados

Supón que estás buscando una entrada de registro del servidor web Apache2. Sabes que los registros de Apache se llaman apache-access y apache-error. ¿Qué debes hacer?

  • No debes usar una coincidencia de substring para escribir un poco menos:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • debes usar coincidencias exactas cuando busques campos indexados:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

Un campo indexado pierde toda su rapidez cuando haces una búsqueda de substring.

Ejemplo: no uses búsquedas globales

Si buscas una entrada de registro con “Hello, Kitty” en la carga útil, ten en cuenta la siguiente información:

  • No uses una búsqueda global. Una de las razones es que todas son búsquedas de substrings, como se ve a continuación:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • Sí debes limitar la búsqueda a un campo único, incluso si debes mantener la búsqueda de substring, como se ve a continuación:

        textPayload:"Hello, Kitty"
    
  • debes usar una prueba de igualdad, si puedes, como se ve a continuación:

        textPayload = "Hello, Kitty"
    
  • debes hacer referencia a los campos individuales en una carga útil, si tus entradas de registro tienen cargas útiles estructuradas, como se ve a continuación:

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • debes usar un campo indexado para restringir la búsqueda, como se ve a continuación:

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

Busca ejemplos

Las entradas de registro que se muestran son las que coinciden con la consulta del cuadro de búsqueda. Si el menú Jump to date contiene un valor, la pantalla se desplazará a ese punto en el tiempo. Estos son algunos ejemplos de consultas:

resource.type=gae_app

Busca las mismas entradas de registro que la interfaz de consulta básica mostraría si seleccionaras Aplicación de GAE (Todos los ID del módulo) del menú de registro de recursos y Todos los registros del menú de nombres de registro. Para ver una lista de los tipos de recursos, consulta la página sobre la lista de recursos supervisados.

A medida que escribes, el visor de registros ofrece sugerencias para completar campos como resource.type.

resource.type=gae_app AND logName:request_log

Busca entradas de registro para apps de App Engine a partir de los nombres de registro que contienen request_log. Ten en cuenta los aspectos siguientes:

  • El operador = es la igualdad exacta. El tipo de recurso debe ser "gae_app" con exactitud, salvo para mayúsculas y minúsculas.
  • El operador : significa “has”. El campo logName debe contener request_log, en mayúsculas o minúsculas. El nombre del registro real es mucho más largo. Usar : puede hacer que las búsquedas sean más lentas.
  • Las dos comparaciones están unidas por AND. También puedes usar OR, pero se supone AND si omites el operador.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Busca entradas de registro con alguno de los dos tipos de recursos: instancia de VM de Compute Engine o instancia de VM de AWS EC2. Las entradas de registro deben tener severity de al menos ERROR, lo que equivale a seleccionar ERROR en el menú de gravedad de la interfaz de consulta básica. No puedes ver registros de varios tipos de recursos en la interfaz de consulta básica.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Busca todas las entradas de registro de auditoría de la actividad del administrador en el proyecto [PROJECT_ID]. Todos los registros de auditoría usan el mismo nombre de registro en un proyecto, pero tienen tipos de recursos diferentes. El ID del registro, cloudaudit.googleapis.com/activity, debe estar codificado como URL en el nombre del registro. Usar la igualdad en la comparación acelera la búsqueda. Para obtener más información, consulta Información sobre los registros de auditoría.

unicorn

Busca entradas de registro que contengan unicorn en algún campo, en mayúscula o minúscula. Un término de búsqueda que no forma parte de una comparación de campos es una consulta de “todos los campos”.

unicorn phoenix

Busca entradas de registro que contengan unicorn y phoenix en algún campo.

textPayload:(unicorn phoenix)

Busca entradas de registro cuyo campo textPayload contenga unicorn y phoenix en cualquier orden; AND está implícito entre las dos palabras.

textPayload:"unicorn phoenix"

Busca entradas de registro cuyo campo textPayload contenga la string "unicorn phoenix". Esto es lo mismo que en la interfaz de consulta básica.

textPayload: NOT "unicorn phoenix"

Busca entradas de registro cuyo campo textPayload no contenga la string "unicorn phoenix". Este tipo de consulta reduce la cantidad de entradas de registro no deseadas.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Busca entradas de registro dentro de un período de 30 minutos.

Consultas guardadas

En el panel del compilador de consultas, se incluye una pestaña Saved (Guardadas), en la que puedes acceder a las consultas guardadas.

Lista de consultas guardadas

Las consultas guardadas te permiten almacenar expresiones de consulta para ayudarte a explorar los registros de manera más coherente y eficiente.

Para guardar una consulta que compilaste en el panel del compilador de consultas, haz lo siguiente:

  1. Haz clic en Save (Guardar) en el panel del compilador de consultas. Se abrirá el cuadro de diálogo Guardar consulta, que contendrá tu expresión de consulta en el campo Query (Consulta).

  2. Agrega un Name (Nombre) para la consulta.

    Los nombres tienen un límite de 64 caracteres.

  3. Para agregar campos de resumen a tu consulta, activa Include summary fields (opcional).

  4. Agrega una Description (Descripción) para tu consulta (opcional).

    Las descripciones tienen un límite de 1,000 caracteres. No incluyas información sensible.

  5. Haz clic en Guardar consulta en el cuadro de diálogo.

Las consultas guardadas aparecen en una lista en la pestaña Saved (Guardadas) en el panel del compilador de consultas.

Para ejecutar una consulta guardada, haz clic en Run query (Ejecutar consulta).

Soluciona problemas

Texto sin comillas

Puedes omitir las comillas en las strings de texto que no contengan espacios en blanco o ciertos caracteres especiales. Esto se denomina texto sin comillas y la palabra ERROR en el ejemplo anterior es un ejemplo de esto. La string "v1.compute.instances.insert" va entrecomillada porque contiene puntos. Si deseas incluir una comilla dentro de una string, coloca una barra inversa antes de la comilla.

Problemas de sintaxis

Si tienes problemas con el lenguaje del compilador de consultas, verifica que se cumpla lo siguiente:

  • Tu consulta obedece a las reglas de sintaxis; los paréntesis y las comillas coinciden. Tu consulta no puede incluir comentarios.

  • Los nombres de los campos de entrada de registro están escritos de forma correcta.

  • Las operaciones booleanas están en letras mayúsculas ( AND, OR, NOT ).

  • Las expresiones booleanas, como las restricciones globales o como el lado derecho de las comparaciones, están entre paréntesis para brindar mayor claridad. Por ejemplo, las dos consultas siguientes parecen ser iguales, pero no lo son:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • El texto sin comillas no debe contener ningún carácter especial. Si tienes dudas, agrega comillas dobles. Por ejemplo, la primera comparación a continuación es ilegal debido al operador de substring incorporado (:). La comparación debe escribirse entre comillas:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud logging requiere que la consulta esté entre comillas dobles. Si quieres usar comillas dobles para escapar los caracteres especiales mediante el comando gcloud logging, en su lugar, encierra toda la consulta entre comillas simples:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    
  • Si escribes una consulta que incluye una marca de tiempo, debes seleccionar Sin límite en el selector de rango de tiempo debajo del cuadro de búsqueda.