Filtros de registros avanzados

En esta guía, se muestra cómo escribir filtros de registros avanzados, que son expresiones que pueden especificar un conjunto de entradas de registro a partir de cualquier cantidad de registros. Los filtros de registro avanzados se pueden usar en el visor de registros, la API de Stackdriver Logging o la interfaz de línea de comandos.

Para obtener más opciones de filtros básicos, consulta Filtros de registro básicos.

Introducción

Un filtro de registros avanzado 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 los filtros avanzados

Para usar filtros avanzados en el Visor de registros, sigue estos pasos:

Dirígete a la página Stackdriver Logging > Logs (Registros) (Logs Viewer) (Visor de registros) en GCP Console:

Ir a la página Visor de registros
Selecciona un proyecto de GCP existente en la parte superior de la página o crea un proyecto nuevo.
Con los menús desplegables, selecciona el recurso cuyos registros quieres ver.
Haz clic en la flecha desplegable (&blacktriangledown;) en el extremo derecho del cuadro de filtro de búsqueda y selecciona Convert to advanced filter (Convertir en filtro avanzado).

A continuación, verás una imagen de la interfaz de filtro avanzado:

Un filtro de registros avanzado

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

A continuación, se muestra un ejemplo simple de un filtro avanzado:

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

Este filtro coincide con las entradas de registro de Compute Engine que tienen valores de gravedad de ERROR como mínimo y cuyo campo textPayload no contiene la string robot dentro de él. 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 elementos destacados cuando escribes Cuando escribes un filtro avanzado en el visor de registros, puede que veas sugerencias para los campos de entrada de registro específicos. Las sugerencias provienen del lenguaje del filtro y el conjunto de entradas de registros reales que cargó el visor de registros. Para elegir una sugerencia, presiona TAB. Si no ves ninguna sugerencia, presiona CTRL+ SPACE. Las diferentes partes de una expresión de filtro se destacan con colores distintos. Si tu expresión es de color rojo brillante, entonces el filtro que escribiste hasta ahora puede que tenga un error o que esté incompleto.

Texto sin comillas: puedes omitir las comillas en las strings de texto que no contienen espacios en blanco o ciertos caracteres especiales. Esto se llama texto sin comillas y las palabras ERROR y robot son ejemplos que se mencionaron con anterioridad. La string "v1.compute.instances.insert" se coloca entre comillas porque contiene puntos. Si deseas incluir una comilla dentro de una string, precede la comilla con una barra invertida (``).

Recomendación: 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 (_).

Uso de teclado: si usas un teclado para escribir filtros avanzados en el cuadro de filtros de búsqueda, puedes presionar ESC si deseas salir del modo de edición y, luego, presionar TAB si deseas navegar hacia otras opciones, como el selector de rango de tiempo, los menús desplegables, la flecha desplegable (&blacktriangledown;) en el extremo derecho del cuadro de filtros de búsqueda o el botón Submit Filter (Enviar filtro).

Sintaxis de filtros avanzados

En esta sección, se explica cómo se estructuran los filtros avanzados y cómo se realiza la coincidencia.

Notación de la sintaxis

La sintaxis de filtros avanzados se describe mediante la siguiente notación:

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 filtros avanzados. Se omitieron algunos detalles, pero se explican en las secciones siguientes.

Un filtro avanzado 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 que usa el operador has. Para este ejemplo, si algún campo en un 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 con el formato [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, =.
[VALOR]: es un número, una expresión entre paréntesis, una string o una función. Por ejemplo, "gae_app".

En las secciones siguientes, se proporcionan más detalles sobre los filtros 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 con el operador - (menos). Por ejemplo, los dos filtros avanzados siguientes son los mismos:

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 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"
```
Consulta identificadores de rutas de campos para obtener más detalles.

[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

[VALOR]: 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 comprueba que el campo cat tenga el valor “siamese” o “shorthair”. La segunda verifica que el valor del campo animal contenga las palabras “nice” y “pet”, en cualquier orden.

Identificadores de las rutas de campo

Todas las entradas de registro son instancias de 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, consulta 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, entonces, el identificador siguiente debe ser un campo del tipo MonitoredResource.
httpRequest.latency: si tu primer identificador de ruta es httpRequest, entonces, el identificador siguiente debe ser un campo del tipo HttpRequest.
labels.[KEY]: si tu primer identificador de ruta es labels, entonces, el identificador siguiente, [KEY], debe ser una de las claves del par clave-valor que aparece 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, consulta Tipos de objetos y arreglos.

Tipos de recursos supervisados

Para realizar búsquedas más rápidas, especifica un tipo de recurso supervisado. Para obtener una lista de tipos de recursos, consulta Tipos de recursos supervisados.

Por ejemplo, las VM de Compute Engine usan el tipo de recurso gce_instance, mientras que 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 un filtro y ese campo no aparece en una entrada de registro, entonces, el campo falta, no está definido o está predeterminado:

Si el campo es parte de la carga útil de la entrada de registro (jsonPayload o protoPayload) o si se encuentra en una etiqueta en la sección labels de la entrada de registro, entonces, el campo falta. 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 no está definido, que es un error que se detecta antes de usar el filtro.

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 comparación siguiente tiene éxito si el campo operation.id está presente de forma explícita 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 de 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 de 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 tiene 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 arreglos, cada elemento del arreglo se compara con [VALUE] y los resultados se unen mediante el operador OR. Por ejemplo, si jsonPayload.shoeSize es un campo de arreglos que almacena {8.5, 9, 6}, la comparación que aparece a continuación:
```
jsonPayload.shoeSize < 7
```
es equivalente a lo siguiente:
```
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 de escalares. En la tabla siguiente, se explica qué valores se pueden convertir en los tipos de campo de registro:

Tipo de campo	Valor de filtro 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, con distinción de 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 incorporar con una barra invertida.
`Timestamp`	Una string en formato RFC 3339. Ejemplo: “2014-10-02T15:01:23.045Z”. En las expresiones de filtros, las marcas de tiempo 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 registros 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. Consulta la asignación de JSON para obtener más información.
Los campos de registro dentro de jsonPayload tienen tipos que se deducen 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 se reconocen solo en campos de búfer de protocolo. 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 de nombre del campo izquierdo subyacente.

Todos los tipos numéricos: la igualdad y la desigualdad tienen su significado normal para los números.
bool: igualdad significa el mismo valor booleano. La desigualdad se define por true > false.
enum: igualdad significa el mismo valor de enumeración. La desigualdad usa los valores numéricos subyacentes de los literales de enumeración.
Duration: igualdad significa la misma duración. La desigualdad se basa en la duración. Ejemplo: como las duraciones "1s">"999ms".
Timestamp: igualdad significa el mismo instante en el tiempo. Si a y b son valores de 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 ignoran si la letra está en mayúscula o minúscula. En especial, primero se normalizan ambos operandos con la normalización de NFKC_CF Unicode y, luego, usan comparaciones lexicográficas.

El operador de la substring (:) es aplicable a string y bytes y se controla como igualdad, excepto que el operando derecho solo debe igualar alguna parte del campo izquierdo. 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 si su carga útil contienen la restricción global. Si es así, entonces, la comparación tiene éxito.

El filtro avanzado más simple escrito en términos de una restricción global es un valor único:

"The Cat in The Hat"

Puedes combinar las restricciones globales mediante los operadores AND y OR para obtener un filtro 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 el filtro de la manera siguiente:

(cat AND (hat OR bat))

En este caso, hay 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 entradas que contengan alguna mención de GCE_OPERATION_DONE en tu registro de actividades, puedes usar el filtro siguiente:

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

Aunque las restricciones globales son simples, pueden ser lentas. Consulta Busca entradas de registro con rapidez.

Funciones

Puedes usar funciones integradas como restricciones globales en filtros avanzados, como se ve a continuación:

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

donde 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 del 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. Establecer [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, el ejemplo 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: en el filtro siguiente, se muestra el 25 por ciento de las entradas de registro 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 hash, 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 de la sección labels, la entrada de registro no se selecciona para el ejemplo, 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, consulta Campos faltantes.

Para excluir las entradas de registro con campos predeterminados de la muestra, usa el operador de campo existente :*. Con el filtro siguiente, se produce una muestra del 1 por ciento de las entradas de registro que proporcionaron un valor para el 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 se encuentra dentro de 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 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: con el filtro siguiente, se prueba una dirección IP en la carga útil de las entradas de registro desde el 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 un rango o una dirección IP, la función muestra falso. Para obtener más información sobre los campos faltantes y predeterminados, consulta Campos faltantes.

A continuación, se enumeran ejemplos de rangos y direcciones IP compatibles:

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

Busca por tiempo

En la interfaz de filtros avanzados, 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 condiciones siguientes a tu filtro, el visor de registros muestra las entradas de registro de forma exacta en el período de 30 minutos indicado y no podrás desplazarte por fuera de ese período:

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

Cuando escribes filtros de marcas de tiempo, debes usar las fechas y horas en el formato que se muestra arriba.

También puedes usar los menús del selector del rango de tiempo para configurar la fecha y la hora de las entradas del registro que se mostrarán. Para obtener más información, consulta Desplázate hacia un horario.

Busca las entradas de registro con rapidez

Cuando filtras o consultas las entradas de registro, realiza estas acciones:

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

Usa campos indexados

Especifica valores exactos para los campos indexados. No uses coincidencias de substrings. Los campos de entradas de registro siguientes están indexados:

logName
resource.type
etiquetas de recursos indexadas en resource.labels
timestamp

Índices de campos temporales

Tres campos de entradas de registro adicionales se indexan durante tiempo limitado después de que Stackdriver Logging recibe las entradas de registro. La búsqueda en estos campos puede ser útil, si tratas de responder con rapidez a los problemas en tu sistema. Stackdriver Logging puede cambiar la forma en que indexa estos tres campos en el futuro sin previo aviso:

severity: se indexan los valores severity desde NOTICE (100) hasta EMERGENCY (900). Para aprovechar el índice, busca solo valores en el rango indexado.
httpRequest.status: se indexan los valores de estado desde 201 hasta 511. Para aprovechar el índice, busca solo valores en el rango indexado.
operation.id: se indexan todos los valores de estos campos. Para aprovechar el índice, busca este campo mediante el operador de igualdad; no uses búsquedas de substring.

Si sueles buscar estos campos en entradas de registro recientes, también debes considerar limitar el período de búsqueda con el campo marca de tiempo.

Minimiza los registros, las entradas de registro y el tiempo

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 llamado “activity_log”. Si se observan con atención las entradas de registro de actividad, se puede ver que 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 ejemplo siguiente, 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 usará 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 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 los filtros siguientes . Si deseas crear una marca de tiempo aceptable para Stackdriver Logging, reemplaza el espacio entre la fecha y la hora con la letra T.

Por ejemplo, para buscar dentro de las últimas tres horas, como se muestra a continuación:

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

Como otro ejemplo, para buscar entre tres y cinco horas atrás, como se muestra a continuación:

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

Consulta Índices de campos temporales para obtener otro ejemplo del uso de las marcas de tiempo.

Minimiza las búsquedas de substring y globales

Evita usar combinaciones de teclas cuando escribas los filtros de registro.

Ejemplo: no uses substrings en campos indexados

Supón que estás buscando una entrada de registro del servidor web de Apache2. Sabes que los registros de Apache se denominan 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!
```

Sí 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"
```
Sí debes usar una prueba de igualdad, si puedes, como se ve a continuación:
```
    textPayload = "Hello, Kitty"
```
Sí 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"
```

Sí 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 el filtro de registros avanzados en el cuadro de filtros de búsqueda. Si el menú Jump to date (Saltar a la fecha) contiene un valor, la pantalla se desplaza a ese punto en el tiempo. A continuación, hay algunos ejemplos de filtros:

resource.type=gae_app

Busca las mismas entradas de registro que la interfaz de filtros básicos mostraría si seleccionas GAE Application (All module IDs) (Aplicación de GAE) (Todos los ID del módulo) en el menú de registro de recursos y All logs (Todos los registros) en el menú de nombres de registro. Para obtener una lista de todos los tipos de recursos, consulta la Lista de recursos supervisados.

A medida que escribes, el visor de registros sugiere elementos completados para campos como resource.type.

resource.type=gae_app AND logName:request_log

Busca entradas de registro para las aplicaciones 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 exactamente "gae_app", excepto para la distinción entre mayúscula y minúscula.
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 puede 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 ERROR como mínimo, lo que equivale a seleccionar ERROR en el menú de gravedad de la interfaz de filtros básicos. No puedes ver los registros de varios tipos de recursos en la interfaz de filtros básicos.

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, se debe codificar 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 Recupera 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, el AND está implícito entre las dos palabras.

textPayload:"unicorn phoenix"

Busca entradas de registro cuyo campo textPayload contenga la string "unicorn phoenix". Este es lo mismo que en la interfaz de filtros básicos.

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

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

Solución de problemas

Si usas un teclado para escribir un filtro avanzado en el cuadro de filtros de búsqueda y necesitas navegar hacia los otros menús de la página, presiona ESC si quieres salir del modo de edición y, luego, presiona TAB para navegar hacia las otras opciones.

Si tienes problemas con los filtros avanzados, comprueba si se cumplen los casos siguientes:

Tu filtro obedece las reglas de sintaxis, con paréntesis y comillas coincidentes.
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 mayor claridad. Por ejemplo, los dos filtros 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 que se muestra a continuación es ilegal debido al operador de substring incorporado (:). La comparación se debe escribir entre comillas, como se ve a continuación:
```
insertId = abc:def  # ILLEGAL!
insertId = "abc:def"
```
gcloud logging requiere que el filtro esté entre comillas dobles. Si quieres usar comillas dobles para incorporar los caracteres especiales con el comando gcloud logging, encierra todo el filtro con comillas simples en su lugar, como se muestra a continuación:
```
gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
```
Las expresiones de búsqueda de los filtros básicos del visor de registros son diferentes de las expresiones de búsqueda de los filtros avanzados. Para obtener más información, consulta las Diferencias entre los filtros básicos y los filtros avanzados.