Consultas de registro avanzadas

Esta guía muestra cómo usar el Lector de registros (clásico) para escribir consultas de registros avanzadas, que son expresiones que pueden especificar un conjunto de entradas de registro de cualquier cantidad de registros. Las consultas de registros avanzados se pueden utilizar en el Lector de registros (clásico), la API de Logging o la gcloud herramienta de línea de comandos.

Para obtener más opciones de consultas básicas, ve a la página sobre consultas de registro básicas.

Si deseas obtener una lista de consultas recomendadas para buscar registros, visita la página sobre consultas de muestra.

Introducción

Una consulta de registro avanzada es una expresión booleana que especifica un subconjunto de todas las entradas de registro de tu proyecto. Se puede usar para realizar cualquiera de las acciones siguientes:

  • Elegir entradas de registro de registros específicos o servicios de registro
  • Elegir entradas de registro dentro de un intervalo de tiempo
  • Elegir entradas de registro que cumplan con las condiciones de los metadatos o de los campos definidos por el usuario
  • Elegir un porcentaje de muestra de todas las entradas de registro

Comienza a usar las consultas de registro avanzadas

Para usar las consultas de registro avanzadas en el visor de registros, sigue estos pasos:

  1. Ve a la página Registro del paquete de operaciones de Google Cloud Logs (Lector de registros) en Cloud Console:

    Ir a la página Visor de registros

  2. Selecciona un proyecto de Google Cloud existente en la parte superior de la página o crea un proyecto nuevo.

  3. En el menú desplegable , selecciona el recurso cuyos registros quieres ver.

  4. Haga clic en el menú desplegable en el cuadro de búsqueda y seleccione Convertir a filtro avanzado.

La interfaz de usuario muestra la conversión a filtro avanzado.

Las consultas de registro se etiquetan como “filtros” en la interfaz de usuario, ya que te permiten seleccionar un conjunto particular de entradas de registros.

Aparecerá la interfaz de consultas de registro avanzadas:

La interfaz de usuario muestra las opciones de filtros avanzados.

Puedes reconocer esta interfaz de consulta por la ausencia de los menús de selección de registros y la presencia del botón Enviar filtro (Submit filter). El visor de registros muestra entradas de registro que cumplen con todas las condiciones especificadas en la consulta.

A continuación, se muestra un ejemplo simple de una consulta de registro avanzada:

    resource.type = "gce_instance" AND
        severity >= ERROR AND
        NOT textPayload:robot
    

Esta consulta busca coincidencias en las entradas de registro de Compute Engine que tienen valores de gravedad de al menos ERROR y cuyo campo textPayload no contiene la string robot. Las comparaciones de strings no distinguen entre mayúsculas y minúsculas. Los nombres resource, severity y textPayload se definen en el tipo LogEntry.

Sugerencias y palabras destacadas a medida que escribes: Cuando escribes una consulta de registro avanzada en el visor de registros, pueden aparecer sugerencias para campos de entradas de registro específicas. Las sugerencias provienen del lenguaje de consulta y del conjunto de entradas de registro reales que cargó el visor de registros. Para elegir una sugerencia, presiona TAB. Si las sugerencias no aparecen, presiona CTRL + SPACE. Las partes diferentes de una expresión de consulta se destacan con distintos colores. Si la expresión es de color rojo brillante, es posible que la consulta que escribiste hasta el momento tenga un error o esté incompleta.

Texto sin comillas: Puedes omitir las comillas en las strings de texto que no contienen espacios en blanco o ciertos caracteres especiales. Esto se denomina texto sin comillas; ejemplos de esto son las palabras ERROR y robot del caso anterior. La string "v1.compute.instances.insert" va entrecomillada porque contiene puntos. Si deseas incluir una comilla dentro de una string, escribe una barra invertida antes de la comilla.

Práctica recomendada: Agrega comillas a las strings que comparas con los valores de campos. Esto protege contra los errores que cambian el significado de tus comparaciones y son difíciles de depurar. Puedes omitir las comillas en las palabras que consisten en una letra seguida de una secuencia de letras, dígitos o caracteres de guion bajo (_).

Usar un teclado: si usas un teclado para ingresar una consulta de registros avanzados en el cuadro de búsqueda, puedes presionar ESC para salir del modo de edición y presionar TAB para navegue a las otras opciones, como el menú desplegable o el botón Enviar filtro.

Sintaxis de las consultas de registro avanzadas

En esta sección, se explica cómo se estructuran las consultas de registro avanzadas y cómo se realiza la búsqueda de coincidencias.

Notación de la sintaxis

Con la siguiente notación, se describe la sintaxis de consulta de registro avanzada:

  • a = e significa que a es un nombre para la expresión e.
  • a b significa “a seguida de b”.
  • a | b significa “a o b”.
  • ( e ) se usa para los grupos.
  • [ e ] significa que e es opcional.
  • { e } significa que e se puede repetir cero o más veces.
  • “abc” significa que abc se debe escribir tal como aparece.

Resumen de la sintaxis

En esta sección, se proporciona una descripción general rápida de la sintaxis de las consultas de registro avanzadas. Se omitieron algunos detalles, pero se explican en las secciones siguientes.

Una consulta de registro avanzada es una string que contiene una expresión como la que se muestra a continuación:

    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
    

Una comparación es un valor único o una expresión booleana como la que se muestra a continuación:

  "The cat in the hat"
      resource.type = "gae_app"
    

La primera línea es un ejemplo de una comparación que es un valor único. Estos tipos de comparaciones son restricciones globales. Cada campo de una entrada de registro se compara con el valor mediante el uso implícito del operador has. Para este ejemplo, si algún campo en una LogEntry o su carga útil contienen la frase “The cat in the hat”, entonces, la comparación es exitosa.

La segunda línea es un ejemplo de una comparación que es una expresión booleana de la forma [FIELD_NAME] [OP] [VALUE]. Los elementos de la comparación se describen a continuación:

  • [FIELD_NAME]: Es un campo en una entrada de registro. Por ejemplo, resource.type.

  • [OP]: Es un operador de comparación. Por ejemplo, =.

  • [VALUE]: Es un número, una expresión entre paréntesis, una string o una función. Por ejemplo, "gae_app".

En las siguientes secciones, se brindan más detalles sobre las consultas y la coincidencia.

Operadores booleanos

Los operadores booleanos AND y OR son operadores de cortocircuito. El operador NOT tiene la prioridad más alta, seguido de OR y AND en ese orden. Por ejemplo, las dos expresiones siguientes son equivalentes:

a OR NOT b AND NOT c OR d
    (a OR (NOT b)) AND ((NOT c) OR d)
    

Puedes omitir el operador AND entre las comparaciones. También puedes reemplazar el operador NOT por el operador - (menos). Por ejemplo, las siguientes dos consultas de registro avanzadas son las mismas:

a=b AND c=d AND NOT e=F
    a=b c=d -e=f
    

En esta documentación, siempre se usa AND y NOT.

Comparaciones

Las comparaciones tienen el formato siguiente:

[FIELD_NAME] [OP] [VALUE]
    

Los elementos de la comparación se describen a continuación:

  • [FIELD_NAME]: Es el nombre de la ruta de un campo en una entrada de registro. Los ejemplos del nombre de campo son los siguientes:

    resource.type
        resource.labels.zone
        resource.labels.project_id
        insertId
        jsonPayload.httpRequest.protocol
        labels."compute.googleapis.com/resource_id"
        

    Para obtener detalles, revisa la sección sobre identificadores de rutas de campo en esta página.

  • [OP]: Es un operador de comparación, uno de los siguientes:

    =           # equal
        !=          # not equal
        > < >= <=   # numeric ordering
        :           # "has" matches any substring in the log entry field
        
  • [VALUE]: Es un número, una expresión entre paréntesis, una string o una función. Las strings se usan para representar textos arbitrarios, además de valores booleanos, de enumeración y de string de bytes. El [VALUE] se convierte al tipo de campo antes de la comparación.

Si [VALUE] es una combinación booleana de comparaciones entre paréntesis, entonces el nombre del campo y el operador de comparación se aplican a cada elemento. Por ejemplo:

    jsonPayload.cat = ("siamese" OR "shorthair")
        jsonPayload.animal : ("nice" AND "pet")
    

La primera comparación verifica que el campo cat tenga el valor “siamese” o “shorthair”. La segunda comprueba que el valor del campo animal contenga las dos palabras “nice” y “pet”, en cualquier orden.

Identificadores de rutas de campo

Todas las entradas de registro son instancias del tipo LogEntry. El identificador que es (o comienza en) el lado izquierdo de una comparación debe ser un campo definido en el tipo LogEntry. Para obtener detalles sobre los identificadores posibles y sus valores, revisa el tipo LogEntry.

A continuación, se muestra la lista actual de los campos de entrada de registro. Cada campo va seguido del nivel de nombres siguiente para ese campo, si corresponde:

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { variable }
  • labels { variable }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variable }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

Los siguientes son ejemplos de identificadores de rutas de campo que puedes usar en tus comparaciones:

  • resource.type: Si tu primer identificador de ruta es resource, el identificador siguiente debe ser un campo del tipo MonitoredResource.

  • httpRequest.latency: Si tu primer identificador de ruta es httpRequest, el siguiente identificador debe ser un campo del tipo HttpRequest.

  • labels.[KEY]: Si tu primer identificador de ruta es labels, el identificador siguiente, [KEY], debe ser una de las claves de los pares clave-valor que aparecen en el campo labels.

  • logName: Debido a que el campo logName es una string, no puede haber ningún nombre de subcampo luego de este.

Para obtener más información sobre el uso de identificadores de rutas de campo que hacen referencia a objetos o arreglos, dirígete Tipos de objetos y arreglos en esta página.

Tipos de recursos supervisados

Para realizar búsquedas más rápidas, especifica un tipo de recurso supervisado. Para obtener una lista de los tipos de recursos, ve a la página sobre tipos de recursos supervisados.

Por ejemplo, las VM de Compute Engine usan el tipo de recurso gce_instance y las instancias de Amazon EC2 usan aws_ec2_instance. En el ejemplo siguiente, se muestra cómo limitar tus búsquedas a ambos tipos de VM:

    resource.type = ("gce_instance" OR "aws_ec2_instance")
    

Los valores del tipo de recurso supervisado en los registros se indexan. El uso de coincidencias de substring para ellos hace que las consultas sean más lentas.

Campos faltantes

Si usas un nombre de campo en una consulta y ese campo no aparece en una entrada de registro, entonces el campo es un campo faltante, indefinido o predeterminado:

  • Si el campo es parte de la carga útil de la entrada de registro (jsonPayload o protoPayload) o si está en una etiqueta de la sección labels de la entrada de registro, el campo es un campo faltante. El uso de un campo faltante no mostrará un error, pero todas las comparaciones que usan campos faltantes fallarán de forma silenciosa.

    Ejemplos: jsonPayload.nearest_store, protoPayload.name.nickname

  • Si el campo está definido en el tipo LogEntry, entonces, está predeterminado. Las comparaciones se realizan como si el campo estuviera presente y tuviera su valor predeterminado.

    Ejemplos: httpRequest.remoteIp, trace, operation.producer

  • De lo contrario, el campo está indefinido, que es un error que se detecta antes de que se use la consulta.

    Ejemplos: thud, operation.thud, textPayload.thud

Para comprobar si hay un campo faltante o predeterminado sin probar un valor particular en el campo, usa la comparación :*. Por ejemplo, la siguiente comparación se realiza de forma correcta si el campo operation.id está presente de modo explícito en una entrada de registro:

operation.id:*
    

Tipos de objetos y arreglos

Cada campo de entrada de registro puede contener un escalar, un objeto o un arreglo.

  • Un campo escalar almacena un valor único, como 174.4 o -1. Una string también se considera un escalar. Los campos que se pueden convertir en (o desde) una string, como Duration y Timestamp, también son tipos escalares.

  • Un tipo de objeto almacena una recopilación de valores con nombre, como el valor JSON siguiente:

    {"age": 24, "height": 67}
        

    Puedes hacer referencia a un valor dentro de un objeto. Por ejemplo, si jsonPayload.x contiene el valor anterior, entonces jsonPayload.x.age tendría el valor 24.

  • Un campo de arreglos almacena una lista de valores, todos del mismo tipo. Por ejemplo, un campo que contiene medidas podría tener el arreglo de números siguiente:

    {8.5, 9, 6}
        

    Cuando se realizan comparaciones y [FIELD_NAME] es un campo de arreglo, cada miembro del arreglo se compara con [VALUE], y los resultados se unen mediante el operador OR. Por ejemplo, si jsonPayload.shoeSize es un campo de arreglo que almacena {8.5, 9, 6}, la comparación siguiente:

    jsonPayload.shoeSize < 7
        

    es equivalente a esto:

    8.5 < 7 OR 9 < 7 OR 6 < 7
        

    En este ejemplo, la comparación en general se evalúa como exitosa.

Valores y conversiones

El primer paso a la hora de evaluar una comparación es convertir el valor del lado derecho al tipo del campo de entrada de registro. Los tipos de campos de escalares están permitidos en las comparaciones, junto con dos tipos adicionales cuyos valores se representan como strings: Duration y Timestamp. Para obtener una lista de tipos de escalares, consulta la lista de tipos de búfer de protocolo escalar. En la tabla siguiente, se explica qué valores se pueden convertir en los tipos de campo de registro:

Tipo de campo Valor de consulta permitido
bool “Verdadero” o “falso” en mayúsculas o minúsculas. Ejemplos: “Verdadero”, “verdadero”.
bytes Una string que contiene cualquier secuencia de bytes. Ejemplo: “\377\377”.
Duration Una string que contiene un número decimal con firma seguido de una de las unidades “ns”, “us”, “m”, “s”, “m” o “h”. Las duraciones son precisas, se miden en nanosegundos. Ejemplo: “3.2s”.
enum El nombre de un tipo de enumeración literal, sin distinción entre mayúsculas y minúsculas. Ejemplos: “WARNING”, que es un valor del tipo LogSeverity.
double Cualquier número, sin un signo o con y una parte del exponente o las strings de valores especiales “-Infinity”, “Infinity” y “Nan” (en mayúscula o no). Ejemplos: “-3.2e-8”, “nan”.
intNN Cualquier número entero con firma que no exceda el tamaño del tipo. Ejemplo: “-3”.
string Cualquier string que contenga texto codificado en UTF-8 o ASCII de 7 bits. Las comillas incorporadas se deben escapar con una barra invertida.
Timestamp Una string en formato RFC 3339 o ISO 8601. Ejemplos: “2014-10-02T15:01:23.045Z” (RFC 3339), “2014-10-02” (ISO 8601). En las expresiones de consulta, las marcas de tiempo en formato RFC 3339 pueden especificar una zona horaria con “Z” o ±hh:mm. Las marcas de tiempo se representan con una exactitud de nanosegundos.
uintNN Cualquier número entero sin firma que no exceda el tamaño del tipo. Ejemplo: “1234”.

Si falla un intento de conversión, también falla la comparación.

Cuando una conversión necesita una string, también puedes usar un número o un texto sin comillas si no contienen caracteres especiales como espacios y operadores. De manera similar, cuando una conversión necesita un número, puedes usar una string cuyo contenido sea un número.

Los tipos intNN y uintNN representan tipos de números enteros de varios tamaños, como int32 y uint64. Cuando escribes un valor para convertirlo en un tipo de número entero de 64 bits, debes escribir el valor como una string, como "9223372036854775807”.

Tipos de campos de registro

A continuación, se muestra cómo se determina el tipo de un campo de entrada de registro:

  • Los campos de registro que se definen en un tipo LogEntry y en el tipo de componente son campos de búfer de protocolo. Los campos de búfer de protocolo tienen tipos explícitos.

  • Los campos de registro que forman parte de los objetos protoPayload también son campos de búfer de protocolo y tienen tipos explícitos. El nombre del tipo de búfer de protocolo se almacena en el campo "@type" de protoPayload. Para obtener más información, revisa la sección sobre la asignación de JSON.

  • Los campos de registro dentro de jsonPayload tienen tipos que se infieren del valor del campo cuando se recibe la entrada de registro:

    • Los campos cuyos valores son números sin comillas tienen el tipo double.
    • Los campos cuyos valores son true o false tienen el tipo bool.
    • Los campos cuyos valores son strings tienen el tipo string.

    Los números enteros largos (de 64 bits) se almacenan en campos de strings, porque no se pueden representar como valores double de manera exacta.

  • Los tipos Duration y Timestamp solo se reconocen en campos de búfer de protocolo {:class="external"}. En otros lugares, esos valores se almacenan en campos de strings.

Operadores de comparación

El significado de los operadores de igualdad (=, !=) y de desigualdad (<, <=, >, >=) depende del tipo del nombre del campo izquierdo subyacente.

  • Todos los tipos numéricos: La igualdad y la desigualdad tienen su significado normal para los números.
  • bool: La igualdad representa el mismo valor booleano. La desigualdad se define por true>false.
  • enum: La igualdad representa el mismo valor de enumeración. La desigualdad usa los valores numéricos subyacentes de los literales de enumeración.
  • Duration: La igualdad representa la misma duración. La desigualdad se basa en la duración. Ejemplo: como duraciones, "1s">"999ms".
  • Timestamp: La igualdad representa el mismo instante. Si a y b son valores Timestamp, a < b significa que a está antes que b.
  • bytes: Los operandos se comparan byte por byte, de izquierda a derecha.
  • string: Las comparaciones no distinguen entre mayúsculas o minúsculas. En especial, primero se normalizan ambos operandos con la normalización de NFKC_CF Unicode y, luego, usan comparaciones lexicográficas.

El operador de substring (:) es aplicable a string y bytes, y se maneja como igualdad excepto que el operando de la derecha solo necesita ser parte del campo de la izquierda. Las coincidencias de substrings en los campos indexados no aprovechan los índices de registro.

Restricciones globales

Si la comparación consiste de un valor único, se denomina restricción global. Logging usa el operador has (:) para determinar si algún campo en una entrada de registro o su carga útil contiene la restricción global. Si es así, entonces, la comparación tiene éxito.

La consulta de registro avanzada más simple escrita en términos de una restricción global es un valor único:

"The Cat in The Hat"
    

Puedes combinar restricciones globales mediante los operadores AND y OR para obtener una consulta más interesante. Por ejemplo, si deseas mostrar todas las entradas de registro que tienen un campo que contiene cat y un campo que contiene hat o bat, escribe la consulta del siguiente modo:

(cat AND (hat OR bat))
    

En este caso, existen tres restricciones globales: cat, hat y bat. Estas restricciones globales se aplican por separado y los resultados se combinan, como si la expresión se hubiera escrito sin paréntesis.

Una forma fácil de buscar un valor particular en tus registros es mediante una restricción global. Por ejemplo, si buscas en tu registro de actividad entradas que contienen alguna mención de GCE_OPERATION_DONE, puedes usar la siguiente consulta:

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

Si bien las restricciones globales son fáciles, pueden ser lentas. Para obtener más información, consulta Busca entradas de registro con rapidez en esta página.

Funciones

Puedes usar las funciones integradas como restricciones globales en las consultas avanzadas:

function = identifier ( [ argument { , argument } ] )
    

En el ejemplo anterior, argument es un valor, un nombre de campo o una expresión entre paréntesis. Las funciones se describen en las secciones siguientes.

sample

La función sample selecciona una fracción de la cantidad total de entradas de registro:

sample([FIELD], [FRACTION])
    

[FIELD] es el nombre de un campo en la entrada de registro, como logName o jsonPayload.a_field. El valor del campo determina si la entrada de registro está en la muestra. El tipo de campo debe ser una string o un valor numérico. Configurar [FIELD] como insertId es una buena opción, ya que cada entrada de registro tiene un valor diferente para ese campo.

[FRACTION] es la fracción de entradas de registro que tienen valores que [FIELD] debe incluir. Es un número mayor que 0.0 y menor o igual que 1.0. Por ejemplo, si especificas 0.01, entonces la muestra contiene un valor aproximado del uno por ciento de todas las entradas de registro que tienen valores para [FIELD]. Si [FRACTION] es 1, se eligen todas las entradas de registro que tienen valores para [FIELD].

Ejemplo: La siguiente consulta muestra el 25% de las entradas del registro syslog:

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)
    

Detalles: Se usa un algoritmo determinista, en función de los hashes, para determinar si una entrada de registro se incluye o no en la muestra. La precisión del ejemplo resultante depende de la distribución de los valores de hash. Si los valores de hash no están distribuidos de manera uniforme, la muestra resultante se puede sesgar. En el peor de los casos, cuando [FIELD] siempre contiene el mismo valor, la muestra resultante contiene la [FRACTION] de todas las entradas de registro o ninguna de ellas.

Si [FIELD] aparece en una entrada de registro, sucede lo siguiente:

  • Se calcula un hash del valor.
  • El valor de hash, que es un número, se divide por el valor de hash máximo posible.
  • Si la fracción resultante es menor o igual que [FRACTION], la entrada de registro se incluye en la muestra; de lo contrario, se excluye de esta.

Si [FIELD] no aparece en una entrada de registro, sucede lo siguiente:

  • Si [FIELD] es parte de la carga útil de la entrada de registro o secciones labels, la entrada de registro no está seleccionada para la muestra, incluso si [FRACTION] es 1.
  • De lo contrario, a la entrada de registro se la trata como si [FIELD] estuviera en la entrada de registro y el valor de [FIELD] fuera el valor predeterminado. El tipo LogEntry determina el valor predeterminado. Para obtener más información sobre los campos faltantes y predeterminados, revisa Campos faltantes en esta página.

Para excluir las entradas de registro con campos predeterminados de la muestra, usa el operador de campo existente :*. La consulta siguiente genera una muestra del 1% de entradas de registro que proporcionaron un valor para field de forma explícita:

field:* AND sample(field, 0.01)
    

ip_in_net

La función ip_in_net determina si una dirección IP en una entrada de registro está contenida dentro una subred. Puedes usarlo para saber si una solicitud proviene de una fuente interna o externa. Por ejemplo:

ip_in_net([FIELD], [SUBNET])
    

[FIELD] es un campo con un valor de string en la entrada de registro que contiene un rango o una dirección IP. El campo puede repetirse; en ese caso, solo uno de los campos repetidos debe tener una dirección o un rango contenido en la subred.

[SUBNET] es una constante de string para un rango o dirección IP. Es un error si [SUBNET] no es un rango o una dirección IP legal, como se describe más adelante en esta sección.

Ejemplo: La siguiente consulta prueba una dirección IP en la carga útil de entradas del registro my_log:

    logName = "projects/my_project/logs/my_log" AND
        ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")
    

Detalles: En caso de que en una entrada de registro faltara [FIELD], estuviera predeterminado o no contuviera una dirección IP o un rango legal, la función mostrará falso. Para obtener más información sobre los campos faltantes y predeterminados, revisa Campos faltantes en esta página.

A continuación, se incluyen algunos ejemplos de las direcciones IP y rangos admitidos:

  • IPv4: 10.1.2.3
  • Subred IPv4: 10.1.2.0/24
  • CIDR IPv6: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • Subred CIDR IPv6: 1:2::/48

Busca por tiempo

En la interfaz de consulta de registro avanzada, puedes establecer límites específicos para la fecha y hora de las entradas de registro que se mostrarán. Por ejemplo, si agregas las siguientes condiciones a tu consulta, el visor de registros mostrará con exactitud las entradas de registro en el período indicado de 30 minutos y no podrás desplazarte fuera de ese período:

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

Cuando escribes una consulta con una marca de tiempo, debes usar fechas y horas en el formato que se muestra arriba. También debes seleccionar Sin límite en el selector de rango de tiempo debajo del cuadro de búsqueda.

Busca entradas de registro con rapidez

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.

Optimiza tus consultas

Puedes hacer que tus búsquedas sean más rápidas si reduces la cantidad de registros, 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!
        
  • 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 de registro avanzada en el cuadro de búsqueda. Si el menú Saltar a la fecha 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.

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

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

Soluciona problemas

Navegación con el teclado

Si usas un teclado para escribir una consulta avanzada en el cuadro de búsqueda y necesitas navegar a los demás menús de la página, presiona ESC a fin de salir del modo de edición y presiona TAB con el fin de navegar a las otras opciones.

Problemas de sintaxis

Si tienes problemas con las expresiones de tus consultas avanzadas, verifica que se cumplan las siguientes cuestiones:

  • 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"
        
  • La herramienta de línea de comandos de gcloud requiere que la consulta esté entre comillas dobles. Si quieres usar comillas dobles para escapar los caracteres especiales con el comando gcloud logging, encierra toda la consulta con comillas simples en su lugar:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
        
  • Las expresiones de búsqueda de las consultas básicas del visor de registros son diferentes de las expresiones de búsqueda de las consultas de registro avanzadas. Para obtener más información, consulta la sección Diferencias entre consultas básicas y avanzadas.

  • 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.