Filtros de registro avançados

Neste guia, mostraremos como gravar filtros de registro avançados. Eles são expressões que podem especificar um conjunto de entradas de registro a partir de qualquer número de registros. Os filtros de registro avançados podem ser usados no Visualizador de registros, na API Stackdriver Logging ou na interface de linha de comando.

Para mais opções básicas de filtragem, consulte Filtros básicos de registro.

Introdução

Um filtro de registros avançado é uma expressão booleana que especifica um subconjunto de todas as entradas de registro no seu projeto. Ele pode ser usado para realizar as seguintes ações:

  • Selecionar entradas de registro a partir de registros ou serviços de registro específicos.
  • Selecionar entradas de registro dentro de um intervalo de tempo.
  • Selecionar entradas de registro que satisfaçam condições em metadados ou campos definidos pelo usuário.
  • Selecionar uma porcentagem de amostra de todas as entradas de registro.

Primeiros passos com filtros avançados

Para usar filtros avançados no Visualizador de registros:

  1. Acesse a página Stackdriver Logging > Registros (Visualizador de registros) no Console do GCP:

    Acessar a página "Visualizador de registros"

  2. Selecione um projeto do GCP na parte superior da página ou crie um novo.

  3. Use os menus suspensos para selecionar o recurso com os registros que você quer ver.

  4. Clique na seta suspensa (▾) na extrema direita da caixa de filtro de pesquisa e selecione Converter para filtro avançado.

Veja a interface de filtros avançados abaixo:

Um filtro de registros avançado

Ela é caracterizada pela ausência dos menus de seleção de registro e pelo botão Enviar filtro: O Visualizador de registros exibe entradas de registro que satisfazem todas as condições especificadas no filtro.

Este é um exemplo simples de um filtro avançado:

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

Esse filtro corresponde a entradas de registro do Compute Engine que tenham valores de gravidade de pelo menos ERROR e com um campo textPayload que não contenha a string robot em nenhum lugar. As comparações de string não diferenciam maiúsculas de minúsculas. Os nomes resource, severity e textPayload são definidos no tipo LogEntry.

Sugestões e destaques à medida que você digita Ao digitar um filtro avançado no Visualizador de registros, você verá sugestões de campos específicos de entrada de registro. As sugestões provêm da linguagem do filtro e do conjunto de entradas de registro reais carregadas pelo Visualizador de registros. Para escolher uma sugestão, pressione TAB. Se não estiver vendo as sugestões, tente pressionar CTRL + SPACE. As partes distintas de uma expressão de filtro são destacadas em cores diferentes. Se o filtro digitado tiver um erro ou estiver incompleto, a expressão aparecerá em vermelho vivo.

Texto sem aspas: é possível omitir aspas em strings que não contenham espaços em branco ou certos caracteres especiais. Isso se chama texto sem aspas, e os exemplos são as palavras ERROR e robot no exemplo anterior. A string "v1.compute.instances.insert" fica entre aspas porque tem pontos. Se quiser incluir aspas dentro de uma string, digite uma barra invertida (``) antes das aspas.

Prática recomendada: adicione aspas às strings que você esteja comparando com valores de campo. Isso protege contra erros que alteram o significado de suas comparações e são difíceis de depurar. É possível omitir aspas em palavras que consistem em uma letra seguida de uma sequência de letras, dígitos ou caracteres de sublinhado (_).

Usando um teclado: se você estiver usando um teclado para digitar um filtro avançado na caixa de filtro de pesquisa, pressione ESC para sair do modo de edição e pressione TAB para navegar até as outras opções, como os menus suspensos do seletor de intervalo, a seta suspensa (▾) na extrema direita da caixa de filtro de pesquisa ou o botão Enviar filtro.

Sintaxe de filtro avançado

Esta seção discute como os filtros avançados são estruturados e como a correspondência é realizada.

Notação da sintaxe

A sintaxe de filtro avançado é descrita usando a seguinte notação:

  • a = e significa que a é um nome para a expressão e.
  • a b significa "a seguido de b".
  • a | b significa "a ou b."
  • ( e ) é usado no agrupamento.
  • [ e ] significa que e é opcional.
  • { e } significa que e pode ser repetido nenhuma ou mais vezes.
  • "abc" significa que abc precisa ser escrito exatamente como aparece.

Resumo da sintaxe

Nesta seção, é fornecida uma visão geral rápida da sintaxe de filtro avançado. Alguns detalhes foram omitidos, mas são explicados nas próximas seções.

Um filtro avançado é uma string contendo uma expressão:

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

Uma comparação é um valor único ou uma expressão booleana:

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

A primeira linha é um exemplo de comparação que é um valor único. Esses tipos de comparações são restrições globais. Cada campo de uma entrada de registro é comparado ao valor usando o operador has. Para este exemplo, se algum campo em um LogEntry ou se o respectivo payload contiver a frase "The cat in the hat" (O gato de chapéu), a comparação será bem-sucedida.

A segunda linha é um exemplo de uma comparação que é uma expressão booleana da forma [FIELD_NAME] [OP] [VALUE]. Os elementos da comparação são descritos abaixo:

  • [FIELD_NAME]: é um campo em uma entrada de registro. Por exemplo, resource.type.

  • [OP]: é um operador de comparação. Por exemplo, =.

  • [VALUE]: é uma expressão numérica, de string, de função ou entre parênteses. Por exemplo, "gae_app".

Nas seções a seguir, são fornecidos mais detalhes sobre filtros e correspondência.

Operadores booleanos

Os operadores booleanos AND e OR são operadores de curto-circuito. O operador NOT tem a precedência mais alta, seguido por OR e AND, nessa ordem. Por exemplo, as duas expressões a seguir são equivalentes:

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

É possível omitir o operador AND entre comparações. Também é possível substituir o operador NOT pelo operador - (sinal de subtração). Por exemplo, estes dois filtros avançados são equivalentes:

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

AND e NOT sempre são usados nesta documentação.

Comparações

Comparações têm a seguinte forma:

[FIELD_NAME] [OP] [VALUE]

Os elementos da comparação são descritos abaixo:

  • [FIELD_NAME]: é o nome do caminho de um campo em uma entrada de registro. Os exemplos do nome do campo são:

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

    Para saber mais detalhes, consulte os identificadores de caminho de campo.

  • [OP]: é um destes operadores de comparação:

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    
  • [VALUE]: é uma expressão numérica, de string, de função ou entre parênteses. As strings são usadas para representar texto arbitrário, além de valores booleanos, de enumeração e de string de bytes. O [VALUE] é convertido no tipo do campo antes da comparação.

Se [VALUE] for uma combinação booleana de comparações entre parênteses, o nome do campo e o operador de comparação serão aplicados a cada elemento. Por exemplo:

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

A primeira comparação verifica se o campo cat tem o valor "siamese" ou "shorthair". O segundo verifica se o valor do campo animal contém as palavras "nice" e "pet", em qualquer ordem.

Identificadores de caminho de campo

Todas as entradas de registro são instâncias do tipo LogEntry. Isso significa que o identificador, que é o lado esquerdo da comparação (ou começa nele), será um campo definido no tipo LogEntry. Para detalhes sobre os possíveis identificadores e os valores correspondentes, consulte o tipo LogEntry.

Esta é a lista atual de campos de entrada de registro. Cada campo é seguido do próximo nível de nomes desse campo, se aplicável:

  • 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

Você verá abaixo exemplos de identificadores de caminho de campo que podem ser usados nas comparações:

  • resource.type: se o primeiro identificador de caminho for resource, o próximo identificador precisará ser um campo no tipo MonitoredResource.

  • httpRequest.latency: se o primeiro identificador de caminho for httpRequest, o próximo identificador precisará ser um campo no tipo HttpRequest.

  • labels.[KEY]: se o primeiro identificador de caminho for labels, o próximo identificador [KEY] precisará ser uma das chaves dos pares de chave-valor exibidas no campo labels.

  • logName: como o campo logName é uma string, não é possível inserir qualquer nome de subcampo depois dele.

Para saber mais informações sobre o uso de identificadores de caminho de campo que façam referência a objetos ou matrizes, consulte Tipos de matrizes e objetos.

Tipos de recursos monitorados

Para pesquisas mais rápidas, especifique um tipo de recurso monitorado. Para uma lista de tipos de recursos, consulte Tipos de recursos monitorados.

Por exemplo, as VMs do Compute Engine usam o tipo de recurso gce_instance e as instâncias do Amazon EC2 usam aws_ec2_instance. Veja no exemplo a seguir como limitar suas pesquisas nos dois tipos de VMs:

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

Os valores do tipo de recurso monitorados nos registros são indexados. O uso de correspondências de substring para eles resulta em consultas mais lentas.

Campos ausentes

Se você usar um nome de campo em um filtro e esse campo não for exibido em uma entrada de registro, o campo estará ausente, indefinido ou padronizado:

  • Se ele fizer parte do payload da entrada de registro (jsonPayload ou protoPayload) ou se estiver em um rótulo na seção labels da entrada de registro, o campo estará ausente. Usar um campo ausente não exibirá um erro, mas todas as comparações que usem campos ausentes apresentarão uma falha silenciosa.

    Exemplos: jsonPayload.nearest_store, protoPayload.name.nickname

  • Se estiver definido no tipo LogEntry, o campo será padronizado. As comparações seriam realizadas como se o campo estivesse presente e tivesse o valor padrão.

    Exemplos: httpRequest.remoteIp, trace, operation.producer

  • Caso contrário, o campo será indefinido, o que é um erro detectado antes do uso do filtro.

    Exemplos: thud, operation.thud, textPayload.thud

Para testar se há um campo ausente ou padronizado sem testar um determinado valor no campo, use a comparação :*. Por exemplo, a comparação a seguir será bem-sucedida se o campo operation.id estiver explicitamente presente em uma entrada de registro:

operation.id:*

Tipos de objetos e matrizes

Cada campo de entrada de registro pode conter um escalar, um objeto ou uma matriz.

  • Um campo escalar armazena um único valor, como 174.4 ou -1. Uma string também é considerada um escalar. Os campos que podem ser convertidos em (ou a partir de) uma string, como Duration e Timestamp, também são tipos escalares.

  • Um tipo de objeto armazena uma coleção de valores nomeados, como o seguinte valor JSON:

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

    Consulte o valor dentro de um objeto. Por exemplo, se jsonPayload.x contivesse o valor anterior, jsonPayload.x.age teria o valor 24.

  • Um campo de matriz armazena uma lista de valores, todos do mesmo tipo. Por exemplo, um campo com medições pode ter uma matriz de números:

    {8.5, 9, 6}
    

    Quando as comparações são realizadas e [FIELD_NAME] é um campo de matriz, cada membro da matriz é comparado com [VALUE], e os resultados são mesclados usando o operador OR. Por exemplo, se jsonPayload.shoeSize for um campo de matriz que armazena {8.5, 9, 6}, a comparação:

    jsonPayload.shoeSize < 7
    

    é equivalente a:

    8.5 < 7 OR 9 < 7 OR 6 < 7
    

    Neste exemplo, a comparação geral é avaliada como bem-sucedida.

Valores e conversões

O primeiro passo na avaliação de uma comparação é converter o valor do lado direito para o tipo do campo de entrada de registro. Os tipos de campos escalares são permitidos em comparações, além de dois tipos adicionais cujos valores são representados como strings: Duration e Timestamp. Para ver uma lista de tipos escalares, consulte a lista de tipos escalares para buffer de protocolo. A tabela a seguir explica quais valores podem ser convertidos para os tipos de campo de registro:

Tipo de campo Valor de filtro permitido
bool "True" ou "false" em letras minúsculas ou maiúsculas. Exemplos: "True", "true".
bytes Uma string que contém qualquer sequência de bytes. Exemplo: "\377\377".
Duration Uma string que contém um número decimal assinado seguido de uma das unidades "ns", "us", "ms", "s", "m" ou "h". As durações são medidas com precisão até a casa dos nanossegundos. Exemplo: "3.2s".
enum O nome de um tipo de enumeração literal, indiferente a maiúsculas. Exemplos: "WARNING", que é um valor do tipo LogSeverity.
double Qualquer número, com ou sem sinal e uma parte expoente, ou as strings de valor especial "NaN", "-Infinity" e "Infinity" (em letras maiúsculas ou não). Exemplos: "-3.2e-8", "nan".
intNN Qualquer inteiro assinado que não exceda o tamanho do tipo. Exemplo: "-3".
string Qualquer string que contenha texto codificado em UTF-8 ou ASCII de 7 bits. Aspas incorporadas precisam ser precedidas de uma barra invertida.
Timestamp Uma string no formato RFC 3339. Exemplo: "2014-10-02T15:01:23.045Z". Nas expressões de filtro, os carimbos de data/hora podem especificar um fuso horário com "Z" ou ±hh:mm. Os carimbos de data/hora são representados com precisão de nanosegundos.
uintNN Qualquer inteiro não assinado que não exceda o tamanho do tipo. Exemplo: "1234".

Se ocorrer erro na tentativa de conversão, a comparação falhará.

Quando uma conversão exigir uma string, também será possível usar um número ou um texto sem aspas se eles não contiverem caracteres especiais, como espaços e operadores. Da mesma maneira, quando uma conversão exigir um número, será possível usar uma string com um conteúdo que seja número.

Os tipos intNN e uintNN representam tipos de números inteiros de vários tamanhos, como int32 e uint64. Os valores que serão convertidos em tipos de números inteiros de 64 bits precisam ser gravados como strings. Por exemplo: "9223372036854775807".

Tipos de campos de registro

Veja como o tipo de um campo de entrada de registro é determinado:

  • Os campos de registro definidos no tipo LogEntry e no tipo de componente são campos do buffer de protocolo. Os campos de buffer de protocolo têm tipos explícitos.

  • Os campos de registro que fazem parte de objetos protoPayload também são campos do buffer de protocolo e têm tipos explícitos. O nome do tipo do buffer de protocolo é armazenado no campo "@type" de protoPayload. Para saber mais informações, consulte Mapeamento JSON.

  • Os campos de registro dentro de jsonPayload têm tipos inferidos do valor do campo quando a entrada de registro é recebida:

    • Campos com valores que sejam números sem sinal têm tipo double.
    • Campos com valores que sejam true ou false têm tipo bool.
    • Campos com valores que sejam strings têm tipo string.

    Os inteiros longos (64 bits) são armazenados em campos de string, porque não podem ser representados exatamente como valores double.

  • Os tipos Duration e Timestamp só são reconhecidos em campos de buffer de protocolo. Em outros lugares, esses valores são armazenados em campos de string.

Operadores de comparação

O significado dos operadores de igualdade (=, !=) e desigualdade (<, <=, >, >=) depende do tipo subjacente do nome do campo à esquerda.

  • Todos os tipos numéricos: os símbolos de igualdade e desigualdade têm significado normal para os números.
  • bool: igualdade significa o mesmo valor booleano. A desigualdade é definida por true>false.
  • enum: igualdade significa o mesmo valor de enumeração. A desigualdade usa os valores numéricos subjacentes dos literais de enumeração.
  • Duration: igualdade significa o mesmo comprimento de duração. A desigualdade se baseia no comprimento da duração. Exemplo: como durações, "1s">"999ms".
  • Timestamp: igualdade significa o mesmo instante no tempo. Se a e b forem valores Timestamp, a < b significa que a é anterior a b.
  • bytes: os operadores são comparados byte por byte, da esquerda para a direita.
  • string: as comparações ignoram letras maiúsculas. Mais especificamente, primeiro os dois operandos passam pelo processo de normalização Unicode NFKC_CF. Depois, usam comparações lexicográficas.

O operador de substring (:) é aplicável a string e bytes e é tratado como igualdade, com a diferença de que o operando à direita só precisa se igualar a parte do campo à esquerda. As correspondências de substring em campos indexados não aproveitam os índices de registro.

Restrições globais

Se a comparação consistir em um único valor, é chamada de restrição global. O Logging usa o operador has (:) para determinar se algum campo em uma entrada de registro ou o respectivo payload contém a restrição global. Se isso acontecer, a comparação será bem-sucedida.

O filtro avançado mais simples escrito em termos de uma restrição global é um valor único:

"The Cat in The Hat"

É possível combinar restrições globais usando os operadores AND e OR para um filtro mais interessante. Por exemplo, se você quiser exibir todas as entradas de registro com um campo contendo cat e um campo contendo hat ou bat, escreva o filtro da seguinte forma:

(cat AND (hat OR bat))

Neste caso, existem três restrições globais: cat, hat e bat. Essas restrições globais são aplicadas separadamente e os resultados são combinados, como se a expressão tivesse sido escrita sem parênteses.

Uma restrição global é uma jeito fácil de pesquisar um valor específico em registros. Por exemplo, se você estiver procurando no registro de atividades por entradas contendo qualquer menção de GCE_OPERATION_DONE, use o seguinte filtro:

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

Embora as restrições globais sejam fáceis, elas podem ser lentas. Consulte Como localizar entradas de registro rapidamente.

Funções

É possível usar funções incorporadas como restrições globais em filtros avançados:

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

em que argument é um valor, um nome de campo ou uma expressão entre parênteses. As funções são descritas nas seções a seguir.

sample

A função sample seleciona uma fração do número total de entradas de registro:

sample([FIELD], [FRACTION])

[FIELD] é o nome de um campo na entrada de registro, como logName ou jsonPayload.a_field. O valor do campo determina se a entrada do registro estará na amostra. O tipo de campo precisa ser uma string ou um valor numérico. Definir [FIELD] como insertId é uma boa escolha, cada entrada de registro tem um valor diferente para esse campo.

[FRACTION] é a fração de entradas de registro que têm valores para [FIELD] a serem incluídos. É um número maior do que 0,0 e não superior a 1,0. Por exemplo, se você especificar 0.01, a amostra conterá aproximadamente 1% de todas as entradas de registro com valores para [FIELD]. Se [FRACTION] for 1, todas as entradas de registro que tenham valores para [FIELD] serão escolhidas.

Exemplo: o seguinte filtro retorna 25% das entradas do registro syslog:

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

Detalhes: um algoritmo determinístico, baseado em hash, é usado para determinar se uma entrada de registro está incluída na amostra ou excluída dela. A precisão da amostra resultante depende da distribuição dos valores em hash. Se os valores em hash não forem distribuídos uniformemente, a amostra resultante poderá estar distorcida. No pior dos casos, quando [FIELD] sempre contém o mesmo valor, a amostra resultante contém a [FRACTION] de todas as entradas de registro ou nenhuma entrada de registro.

Se [FIELD] aparecer em uma entrada de registro:

  • será calculado um hash do valor;
  • o valor em hash, que é um número, será dividido pelo valor máximo possível de hash;
  • se a fração resultante for menor que ou igual a [FRACTION], a entrada de registro será incluída na amostra. Caso contrário, ela será excluída da amostra.

Se [FIELD] não aparecer em uma entrada de registro:

  • se [FIELD] for parte das seções de payload ou labels da entrada de registro, ela não será selecionada para a amostra, mesmo se [FRACTION] for 1;
  • caso contrário, a entrada de registro seria tratada como se [FIELD] estivesse na entrada de registro e o valor de [FIELD] fosse o valor padrão. O valor padrão é determinado pelo tipo LogEntry. Para ver mais informações sobre campos ausentes e padronizados, consulte Campos ausentes.

Para excluir entradas de registro com campos padronizados da amostra, use o operador de verificação de campo, :*. O filtro a seguir produz uma amostra de 1% das entradas de registro que forneceram explicitamente um valor para field:

field:* AND sample(field, 0.01)

ip_in_net

A função ip_in_net determina se um endereço IP em uma entrada de registro está contido em uma sub-rede. Você pode usá-la para saber se uma solicitação vem de uma fonte interna ou externa. Por exemplo:

ip_in_net([FIELD], [SUBNET])

[FIELD] é um campo com valor de string na entrada de registro em que há um intervalo ou endereço IP. O campo pode ser repetido e, nesse caso, apenas um deles terá um endereço ou intervalo contido na sub-rede.

[SUBNET] é uma constante de string para um intervalo ou endereço IP. Será um erro se [SUBNET] não for um intervalo ou endereço IP válido, conforme descrito mais adiante nesta seção.

Exemplo: o seguinte filtro testa um endereço IP no payload das entradas do registro my_log:

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

Detalhes: se [FIELD] estiver ausente, padronizado ou não contiver um intervalo ou endereço IP válido em uma entrada de registro, a função retornará "false". Para mais informações sobre campos ausentes e padronizados, consulte Campos ausentes.

Exemplos de endereços e intervalos de IP compatíveis estão listados abaixo:

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

Como pesquisar por tempo

Na interface de filtros avançados, é possível definir limites específicos nas datas e horas das entradas de registro para exibi-las. Por exemplo, se você adicionar as seguintes condições ao filtro, o Visualizador de registros exibirá exatamente as entradas de registro no período de 30 minutos indicado e não poderá sair desse período:

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

Durante a gravação de filtros de datas e horas, elas precisam estar no formato mostrado acima.

Você também pode usar os menus do seletor de intervalo de tempo para definir a data e a hora das entradas de registro para exibi-las. Para mais informações, consulte Rolar para uma hora.

Como encontrar entradas de registro rapidamente

Ao filtrar ou consultar entradas de registro:

  • pesquise usando campos indexados;
  • minimize o número de entradas de registro a serem pesquisadas.

Usar campos indexados

Especifique valores exatos para campos indexados. Não use correspondências de substring. Os seguintes campos de entrada de registro são indexados:

Índices de campo temporários

Três campos de entrada de registro adicionais são parcialmente indexados por um tempo limitado depois que o Stackdriver Logging recebe as entradas de registro. Se você estiver tentando responder rapidamente a problemas com o sistema, a pesquisa nesses campos poderá ser útil. O Stackdriver Logging pode alterar a forma como indexa esses três campos no futuro, sem aviso prévio:

  • severity: os valores de gravidade de NOTICE (100) por meio da EMERGENCY (900) são indexados. Para aproveitar o índice, pesquise apenas valores no intervalo indexado.

  • httpRequest.status: os valores de status de 201 a 511 são indexados. Para aproveitar o índice, pesquise apenas valores no intervalo indexado.

  • operation.id: todos os valores desses campos são indexados. Para aproveitar o índice, pesquise esse campo usando o operador de igualdade. Não use pesquisas de substring.

Se procurar sempre esses campos em entradas de registro recentes, pense também em limitar o período de tempo de pesquisa usando o campo de carimbo de data/hora.

Minimizar os registros, as entradas de registro e o período

Para tornar as pesquisas mais rápidas, reduza o número de registros, o número de entradas de registros ou o tempo das pesquisas. Melhor ainda: reduza os três.

Exemplo: use o nome de registro correto

Especifique o registro que contenha as entradas do seu interesse. Verifique uma das entradas de registro para confirmar o nome do registro real. Por exemplo, o Visualizador de registros mostra que há um registro na seção do Compute Engine chamada "activity_log". Observando atentamente as entradas do registro de atividades, é possível ver que o nome real do registro é "compute.googleapis.com/activity_log".

A comparação a seguir está incorreta. Ela não gera correspondências porque usa o nome de registro errado:

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

A comparação a seguir está correta. Ela seleciona entradas de registro do registro de atividades. É preciso codificar o nome do registro por URL, como mostrado:

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

Exemplo: escolha as entradas de registro corretas

Se souber que as entradas de registro que você quer pertencem a uma determinada instância de VM, especifique-a. Inspecione uma das entradas de registro que quer pesquisar para verificar os nomes corretos dos rótulos. No exemplo a seguir, instance_id é um dos rótulos indexados:

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

Você especificará um valor para o tipo de recurso. Do contrário, a comparação de instance_id não usa o índice.

Exemplo: escolha o período correto

Especifique um período para a pesquisa. Uma maneira rápida de determinar carimbos de data/hora úteis no formato RFC 3339 é usar o comando date do 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

Use os valores desses carimbos de data/hora nos filtros a seguir. Para criar um carimbo aceitável para o Stackdriver Logging, substitua o espaço entre a data e a hora pela letra T:

Por exemplo, para pesquisar nas últimas três horas:

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

Como outro exemplo, para procurar entre três e cinco horas atrás:

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

Consulte Índices de campo temporários para ver outro exemplo de como usar carimbos de data/hora.

Minimizar as pesquisas globais e de substring

Evite a tentação de usar atalhos ao digitar filtros de registro.

Exemplo: não use substrings em campos indexados

Você está procurando uma entrada de registro do servidor da Web Apache2. Você sabe que os registros do Apache se chamam apache-access e apache-error. O que fazer?

  • Não use uma correspondência de substring para digitar menos:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • Use correspondências exatas ao pesquisar campos indexados:

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

Um campo indexado perde toda a rapidez quando você faz uma pesquisa de substring.

Exemplo: não use pesquisas globais

Você está pesquisando uma entrada de registro que contém "Hello, Kitty" no payload:

  • Não use uma pesquisa global. Uma das razões é que todas elas são pesquisas de substring:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • Limite a pesquisa a um único campo, mesmo se tiver que manter a pesquisa de substring:

        textPayload:"Hello, Kitty"
    
  • Use um teste de igualdade, se possível:

        textPayload = "Hello, Kitty"
    
  • Faça referência a campos individuais em um payload se as entradas de registro tiverem payloads estruturados:

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • Use um campo indexado para restringir a pesquisa:

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

Como pesquisar exemplos

As entradas de registro mostradas são aquelas que correspondem ao filtro avançado de registros na caixa de filtro de pesquisa. Se o menu Pular para data contiver um valor, a tela rolará para esse ponto no tempo. Veja alguns exemplos de filtro:

resource.type=gae_app

Encontra as mesmas entradas de registro que a interface de filtros básicos mostraria se você tivesse selecionado Aplicativo do GAE (todos os códigos de módulo) no menu de recursos e Todos os registros no menu do nome. Para ver uma lista de tipos de recursos, consulte Lista de recursos monitorados.

À medida que você digitar, o Visualizador de registros sugerirá preenchimentos para campos como resource.type.

resource.type=gae_app AND logName:request_log

Localiza entradas de registro para aplicativos do App Engine pelos nomes de registros que contêm request_log. Leve isto em conta:

  • O operador = se refere à igualdade exata. O tipo de recurso precisa ser exatamente "gae_app", exceto pelas letras minúsculas e maiúsculas.
  • O operador : significa "tem". O campo logName precisa conter request_log em letras minúsculas ou maiúsculas. O nome real do registro é muito mais longo. Usar : pode resultar em pesquisas mais lentas.
  • As duas comparações são mescladas por AND. Também é possível usar OR, mas AND será usado se você não incluir o operador.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Localiza entradas de registro com dois tipos de recursos: instância de VM do Compute Engine ou instância de VM do AWS EC2. As entradas de registro precisam ter severity de pelo menos ERROR, o que equivale a selecionar ERRO no menu de gravidade da interface de filtros básicos. Não é possível visualizar registros de vários tipos de recurso na interface de filtros básicos.

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

Encontra todas as entradas de registro de auditoria da Atividade do administrador no projeto [PROJECT_ID]. Os registros de auditoria usam o mesmo nome em um projeto, mas têm tipos de recurso diferentes. O código do registro, cloudaudit.googleapis.com/activity, precisa ser codificado em URL no nome. Usar a igualdade na comparação acelera a pesquisa. Para saber mais, consulte Como recuperar registros de auditoria.

unicorn

Encontra entradas de registro que contêm unicorn em qualquer campo e em letras minúsculas e maiúsculas. Um termo de pesquisa que não faz parte de uma comparação de campo é uma consulta de "todos os campos".

unicorn phoenix

Encontra entradas de registro que contêm unicorn em algum campo e phoenix em outro.

textPayload:(unicorn phoenix)

Encontra entradas de registro com campo textPayload que contém unicorn e phoenix em qualquer ordem. AND está implícito entre as duas palavras.

textPayload:"unicorn phoenix"

Encontra entradas de registro com campo textPayload que contém a string "unicorn phoenix". É o mesmo da interface de filtros básicos.

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

Encontra entradas de registro dentro de um período de 30 minutos.

Solução de problemas

Se você estiver usando um teclado para digitar um filtro avançado na caixa de filtro de pesquisa e precisar navegar para os outros menus na página, pressione ESC para sair do modo de edição, e pressione TAB para navegar até as outras opções.

Se você tiver problemas com filtros avançados, verifique se ele atende a estes requisitos:

  • O filtro obedece às regras de sintaxe, com parênteses e aspas correspondentes.

  • Os nomes dos campos de entrada de registro estão escritos corretamente.

  • As operações booleanas estão em maiúsculas (AND, OR, NOT).

  • As expressões booleanas como restrições globais ou como o lado direito das comparações precisam estar entre parênteses para maior clareza. Por exemplo, os dois filtros abaixo parecem iguais, mas não são:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • O texto sem aspas não pode conter nenhum caractere especial. Em caso de dúvida, adicione aspas duplas. Por exemplo, a primeira comparação abaixo é ilegal por causa do operador de substring incorporado (:). A comparação precisa ser escrita entre aspas:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • A geração de registros do gcloud exige que o filtro esteja entre aspas duplas. Para usar aspas duplas para escapar caracteres especiais usando o comando gcloud logging, envolva o filtro inteiro com aspas simples:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    
  • As expressões de pesquisa nos filtros básicos do Visualizador de registros são diferentes daquelas em filtros avançados. Para saber mais informações, consulte Diferenças entre filtros básicos e avançados.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.