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:
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 (▾) 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:
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 (▾) 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 campolabels
.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
oprotoPayload
) o si se encuentra en una etiqueta en la secciónlabels
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
. Unastring
también se considera un escalar. Los campos que se pueden convertir en (o desde) una string, comoDuration
yTimestamp
, 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, entoncesjsonPayload.x.age
tiene el valor24
.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 operadorOR
. Por ejemplo, sijsonPayload.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"
deprotoPayload
. 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
ofalse
tienen el tipobool
. - 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 campos cuyos valores son números sin comillas tienen el tipo
Los tipos
Duration
yTimestamp
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 portrue
>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 deTimestamp
, 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ónlabels
, 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 campologName
debe contenerrequest_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 usarOR
, pero se suponeAND
si omites el operador.
- 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
deERROR
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
yphoenix
en algún campo.textPayload:(unicorn phoenix)
Busca entradas de registro cuyo campo
textPayload
contengaunicorn
yphoenix
en cualquier orden, elAND
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.