Consultas de registros avançados

Este guia mostra como usar o Visualizador de registros (Clássico) para gravar consultas de registros avançadas, que são expressões que podem especificar um conjunto de entradas de registro a partir de qualquer número de registros. As consultas de registros avançadas podem ser usadas no Visualizador de registros (Clássico), na API do Logging ou na ferramenta de linha de comando gcloud.

Para opções de consulta mais básicas, vá para Consultas de registros básicas.

Para uma lista de consultas recomendadas para encontrar registros, acesse Amostra de consultas.

Introdução

Uma consulta de registros avançada é uma expressão booleana que especifica um subconjunto de todas as entradas de registro no seu projeto. Ele pode ser usado para fazer 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 consultas de registros avançados

Para usar consultas de registros avançados no Visualizador de registros:

  1. Vá para o conjunto de operações do Google Cloud em Registros > Visualizador de registros no Console do Cloud:

    Acesse a página "Visualizador de registros"

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

  3. Usando o menu suspenso , selecione o recurso cujos registros você quer visualizar.

  4. Clique no menu suspenso na caixa de consulta de pesquisa e selecione Converter para filtro avançado.

A interface do usuário mostrando a conversão para o filtro avançado.

As consultas de registro são rotuladas como "filtros" na interface do usuário, porque permitem que você selecione um conjunto específico de entradas de registros.

A interface de consulta de registros avançados é exibida:

A interface do usuário mostrando opções avançadas de filtros.

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 na consulta.

Veja a seguir um exemplo simples de uma consulta de registros avançada:

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

Essa consulta corresponde a entradas de registro do Compute Engine com valores de gravidade de pelo menos ERROR e o campo textPayload sem a string robot em qualquer lugar dentro dela. 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: quando você digita uma consulta de registros avançada no Visualizador de registros, sugestões para campos de entrada de registro específicos podem ser exibidas. As sugestões vêm da linguagem de consulta e do conjunto de entradas de registro reais que o Visualizador de registros carregou. Para escolher uma sugestão, pressione TAB. Se as sugestões não aparecerem, tente pressionar CTRL + SPACE. As diferentes partes de uma expressão de consulta são destacadas em cores diferentes. Se sua expressão é vermelho claro, a consulta que você digitou pode ter um erro ou estar incompleta.

Texto sem aspas: é possível omitir aspas em strings que não contenham espaços em branco ou certos caracteres especiais. Isso é chamado de texto sem aspas e exemplos são as palavras ERROR e robot no exemplo anterior. A string "v1.compute.instances.insert" está entre aspas porque contém 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 evita erros que alteram o significado de suas comparações e são difíceis de depurar. É possível omitir as aspas em palavras que consistem em uma letra seguida por uma sequência de letras, dígitos ou caracteres sublinhados (_).

Usando um teclado: se você estiver usando um teclado para digitar uma consulta de registros avançada na caixa de consulta de pesquisa, pressione ESC para sair do modo de edição e pressione TAB para navegar até as outras opções, como o menu suspenso ou o botão Enviar filtro.

Sintaxe de consulta de registros avançados

Esta seção discute como as consultas de registros avançadas são estruturadas e como a correspondência é realizada.

Notação de sintaxe

A sintaxe de consulta de registros avançados é 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

Esta seção fornece uma visão geral rápida da sintaxe de consulta de registros avançados. Alguns detalhes foram omitidos, mas são explicados nas próximas seções.

Uma consulta de registros avançados é uma string que contém 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 implicitamente 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".

As seções a seguir fornecem mais detalhes sobre consultas e correspondências.

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, as duas consultas de registros avançadas a seguir são as mesmas:

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. 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 detalhes, consulte identificadores de caminho de campo nesta página.

  • [OP]: é um operador de comparação, um dos seguintes:

    =           # 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 que estiver entre parênteses, o nome do campo e o operador de comparação serão aplicados a cada elemento. 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". A segunda 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. O identificador que é (ou começa) do lado esquerdo de uma comparação precisa ter um campo definido no tipo LogEntry. Para detalhes sobre os possíveis identificadores e seus valores, revise 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 {variável}
  • labels {variável}
  • logName
  • metadata {systemLabels, userLabels}
  • operation{id, producer, first, last}
  • protoPayload {@type, variável}
  • 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 seu primeiro identificador de caminho for resource, o próximo identificador precisa ter um campo no tipo MonitoredResource.

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

  • labels.[KEY]: Se seu primeiro identificador de caminho for labels, o próximo identificador, [KEY], precisará ter uma das chaves dos pares de valor-chave que aparecem no campo labels.

  • logName: como o campo logName é uma string, não é possível usar nomes de subcampos depois dele.

Para mais informações sobre como usar identificadores de caminho de campo que fazem referência a objetos ou matrizes, vá para Tipos de matriz e objeto nesta página.

Tipos de recursos monitorados

Para pesquisas mais rápidas, especifique um tipo de recurso monitorado. Para ver uma lista de tipos de recursos, acesse 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 uma consulta e esse campo não aparecer em uma entrada, o campo será ausente, indefinido ou padrão:

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

    Por exemplo: jsonPayload.nearest_store, protoPayload.name.nickname

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

    Por exemplo: httpRequest.remoteIp, trace, operation.producer

  • Caso contrário, o campo é indefinido, que é um erro detectado antes de a consulta ser usada.

    Por exemplo: thud, operation.thud, textPayload.thud

Para testar se há um campo ausente ou padrão sem testar um determinado valor no campo, use a comparação :*. Por exemplo, a seguinte comparação 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. Um string também é considerado um escalar. Os campos que podem ser convertidos em (ou 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 com os 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 a [VALUE] e os resultados são unidos usando o operador OR. Por exemplo, se jsonPayload.shoeSize é 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. Tipos de campo escalares são permitidos em comparações, junto com dois tipos adicionais que têm os valores representados como strings: Duration e Timestamp. Para uma lista de tipos escalares, vá para a lista de tipos de buffer do protocolo escalar. A tabela a seguir explica quais valores podem ser convertidos para os tipos de campo de registro:

Tipo de campo Valor de consulta 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 ou ISO 8601. Por exemplo: "2014-10-02T15:01:23.045Z" (RFC 3339), "2014-10-02" (ISO 8601). Em expressões de consulta, os carimbos de data/hora no formato RFC 3339 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 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 de buffer de protocolo e têm tipos explícitos. O nome do tipo de buffer de protocolo é armazenado no campo "@type" de protoPayload. Para mais informações, analise o mapeamento JSON.

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

    • Os campos com valores são números sem aspas e têm tipo double.
    • Os campos com valores são true ou false e têm tipo bool.
    • Os campos com valores que são strings com 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ão reconhecidos somente em campos de buffer de protocolo {:class="external"}. 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 lado esquerdo nome do campo.

  • 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 booliano. 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 a mesma duração de duração. A desigualdade é baseada no comprimento da duração. Por 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 operandos são comparados de byte a byte, da esquerda para a direita.
  • string: as comparações ignoram letras maiúsculas e minúsculas. Mais especificamente, primeiro os dois operandos passam pelo processo de normalização Unicode NFKC_CF. Depois, eles 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, será 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.

A mais simples consulta de registros avançada gravada 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 uma consulta mais interessante. Por exemplo, se você desejar exibir todas as entradas de registro que tenham um campo que contenha cat e um campo que contenha hat ou bat, escreva a consulta como:

(cat AND (hat OR bat))
    

Nesse caso, há 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 em seu registro de atividades entradas contendo qualquer menção de GCE_OPERATION_DONE, será possível usar a seguinte consulta:

    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; para mais informações, analise Como encontrar entradas de registro rapidamente nesta página.

Funções

É possível usar funções integradas como restrições globais em consultas avançadas:

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

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

amostra

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 está na amostra. O tipo de campo precisa ser uma string ou um valor numérico. Definir [FIELD] como insertId é uma boa escolha, porque 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.

Por exemplo: a consulta a seguir 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 o [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, será excluída da amostra.

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

  • Se [FIELD] fizer parte das seções labels ou payload da entrada de registro, essa entrada não será selecionada para a amostra, mesmo que [FRACTION] seja 1.
  • Caso contrário, a entrada de registro será 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 mais informações sobre campos ausentes e padrão, veja os campos ausentes nesta página.

Para excluir entradas de registro com campos padrão da amostra, use o operador de verificação de campo, :*. A consulta a seguir produz uma amostra de 1% de 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. É possível usá-la para saber se uma solicitação vem de uma fonte interna ou externa. 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.

Por exemplo: a consulta a seguir 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, em uma entrada de registro, [FIELD] for ausente/padrão ou não contiver um intervalo ou endereço IP válido, a função retornará "false". Para mais informações sobre campos ausentes e padrão, veja os campos ausentes nesta página.

Veja a seguir alguns exemplos de endereços IP e intervalos compatíveis:

  • 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 consulta de registros avançada, é possível definir limites específicos na data e na hora das entradas de registro para exibi-las. Por exemplo, se você adicionar as seguintes condições à sua consulta, o Visualizador de registros exibirá exatamente as entradas de registro no período de 30 minutos indicado e você não poderá rolar a página fora desse período:

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

Ao escrever uma consulta com carimbo de data/hora, você precisa usar datas e horas no formato mostrado acima. Também é necessário selecionar Sem limite no seletor de intervalo de tempo abaixo da caixa de consulta de pesquisa.

Como encontrar entradas de registro rapidamente

Para encontrar entradas de registro de forma mais eficiente, faça o seguinte:

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

Usar campos indexados

Para aproveitar o índice, especifique valores exatos para campos indexados usando o operador de igualdade. Não use correspondências de substring.

Os seguintes campos LogEntry são indexados:

As próximas seções explicam como usar esses campos indexados para minimizar o número de entradas de registro a serem consultadas.

Otimize suas consultas

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 de registro real. Por exemplo, o Visualizador de registros mostra que há um registro na seção do Compute Engine chamada "activity_log". Em uma inspeção mais detalhada das entradas do registro de atividades, o registro é, na verdade, chamado "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. Caso 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 os carimbos de data/hora úteis no formato RFC 3339 é usar o comando Gnu/Linux date:

$ 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 nas consultas a seguir. Para criar um carimbo de data/hora aceitável para o 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"
    

Para outro exemplo de uso de carimbo de data/hora, acesse Índices de campos temporários nesta página.

Minimizar as pesquisas globais e de substring

Evite a tentação de usar atalhos ao digitar consultas 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 são denominados 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 à consulta de registros avançada na caixa de consulta de pesquisa. Se o menu Pular para data contiver um valor, a tela rolará para esse momento. Veja alguns exemplos de consulta:

resource.type=gae_app

Encontra as mesmas entradas de registro que a interface de consulta básica mostraria se você tivesse selecionado Aplicativo do GAE (todos os IDs de módulo) no menu de recursos e Todos os registros no menu de nomes. Para uma lista de tipos de recursos, acesse Lista de recursos monitorados.

Conforme você digita, o Visualizador de registros sugere conclusões para campos como resource.type.

resource.type=gae_app AND logName:request_log

Encontra entradas de registro para apps do App Engine a partir de nomes de registros que contenham request_log. Leve isto em conta:

  • O operador = se refere à igualdade exata. O tipo de recurso precisa ter exatamente "gae_app", exceto para diferenciação entre letras maiúsculas e minúsculas.
  • O operador :: significa "has". O campo logName precisa conter request_log, sem diferenciação entre letras maiúsculas e minú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 ERROR no menu de gravidade da interface de consulta básica. Não é possível visualizar registros de vários tipos de recursos na interface de consulta básica.

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 ID do registro, cloudaudit.googleapis.com/activity, precisa ser codificado pelo URL no nome do registro. Usar a igualdade na comparação acelera a pesquisa. Para mais informações, consulte Entendendo os registros de auditoria.

unicorn

Encontra entradas de registro contendo unicorn em qualquer campo, em qualquer letra maiúscula. 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 campo.

textPayload:(unicorn phoenix)

Encontra entradas de registro com o 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 o campo textPayload que contém a string "unicorn phoenix". É o mesmo da interface de consulta básica.

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

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

Resolver problemas

Navegação pelo teclado

Se você estiver usando um teclado para digitar uma consulta avançada na caixa 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.

Problemas de sintaxe

Se você tiver problemas com as expressões de suas consultas avançadas, verifique o seguinte:

  • Sua consulta obedece às regras de sintaxe, com aspas e parênteses correspondentes. Sua consulta não pode incluir comentários.

  • 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, as duas consultas abaixo têm a mesma aparência, mas não são iguais:

    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 é inválida por causa do operador de substring incorporado (:). A comparação precisa ser escrita com aspas:

    insertId = abc:def  # ILLEGAL!
        insertId = "abc:def"
        
  • A ferramenta de linha de comando gcloud exige que a consulta esteja entre aspas duplas. Para usar aspas duplas com o fim de escapar caracteres especiais usando o comando gcloud logging, agrupe a consulta inteira com aspas simples:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
        
  • Expressões de pesquisa nas consultas básicas do Visualizador de registros são diferentes das expressões de pesquisa em consultas de registros avançadas. Para mais informações, acesse Diferenças nas consultas básica e avançada.

  • Se você estiver gravando uma consulta que inclua um carimbo de data/hora, selecione Sem limite no seletor de intervalo de tempo abaixo da caixa de consulta de pesquisa.