Linguagem de consulta de registo

Este documento descreve, a um nível elevado, a linguagem de consulta do Logging que usa para consultar e filtrar dados do Cloud Logging.

Para obter informações detalhadas sobre a conceção da linguagem de consulta de registo, consulte as especificações formais da API Google para filtragem.

Para ver exemplos de consultas comuns que pode querer usar, consulte o artigo Consultas de exemplo com o Explorador de registos.

Vista geral

Pode usar a linguagem de consulta do Logging no Explorador de registos na Google Cloud consola, na API Logging> ou na interface de linha de comandos. Pode usar a linguagem de consulta de registo para consultar dados e escrever filtros para criar destinos e métricas baseadas em registos.

Uma consulta é uma expressão booleana que especifica um subconjunto de todas as entradas do registo no Google Cloud recurso selecionado, como um Google Cloud projeto ou uma pasta.

Pode criar consultas com base no LogEntry campo indexado através dos operadores lógicos AND e OR. Usando o campo resource.type nos exemplos seguintes, a gramática da linguagem de consulta de registo tem o seguinte aspeto:

• Restrição simples: resource.type = "k8s_cluster"

• Restrição conjuntiva: resource.type = "k8s_cluster" AND severity = "ERROR"

• Restrição disjuntiva: resource.type = "k8s_cluster" OR resource.type = "gce_instance"

  • Em alternativa: resource.type = ("k8s_cluster" OR "gce_instance")

• Expressão complexa conjuntiva/disjuntiva: resource.type = "k8s_cluster" AND (severity = "ERROR" OR "error")

Segue-se um exemplo de uma consulta:

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

Esta consulta corresponde a entradas de registo do Compute Engine que têm valores de gravidade de, pelo menos, ERROR e cujo campo textPayload não contém a string robot em nenhum lugar. As comparações de strings não são sensíveis a maiúsculas e minúsculas. Os nomes resource, severity e textPayload são definidos no tipo LogEntry.

Notação de sintaxe

As secções seguintes oferecem uma vista geral da sintaxe da linguagem de consulta de registo e abordam detalhadamente a forma como as consultas são estruturadas e como a correspondência é realizada. Alguns dos exemplos usam comentários para fornecer texto explicativo.

Tenha em conta o seguinte:

• O comprimento de uma consulta não pode exceder 20 000 carateres.

• O idioma de consulta de registo não é sensível a maiúsculas e minúsculas, com exceção das expressões regulares e dos operadores lógicos, como AND e OR. Os operadores lógicos têm de estar em maiúsculas.

Resumo da sintaxe

A sintaxe da linguagem de consulta de registo pode ser pensada em termos de consultas e comparações.

Uma consulta é 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 = "k8s_cluster"

A primeira linha é um exemplo de uma comparação que é um único valor. Estes tipos de comparações são restrições globais. Cada campo de uma entrada de registo é comparado com o valor através da utilização implícita do operador has. Para este exemplo, se qualquer campo num LogEntry ou se a respetiva carga útil contiver a expressão "O gato de chapéu", a comparação é bem-sucedida.

A segunda linha é um exemplo de uma comparação que é uma expressão booleana da forma [FIELD_NAME] [OP] [VALUE]. Uma comparação tem três componentes:

• [FIELD_NAME] é um campo numa entrada de registo. Por exemplo, resource.type.

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

• [VALUE] é um número, uma string, uma função ou uma expressão entre parênteses. Por exemplo, "k8s_cluster". Para valores nulos JSON, use NULL_VALUE.

Operadores booleanos

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

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

Pode omitir o operador AND entre comparações. Também pode substituir o operador NOT pelo operador - (menos). Por exemplo, as duas consultas seguintes são iguais:

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

Esta documentação usa sempre AND e NOT.

Para todos os filtros, exceto os filtros usados pelas visualizações de registos, pode usar os operadores AND, OR e NOT. As visualizações de registos só suportam operações AND e NOT.

Para combinar regras AND e OR na mesma expressão, tem de aninhar as regras com parênteses. Se não usar parênteses, a consulta pode não funcionar conforme previsto.

Os operadores booleanos têm sempre de estar em maiúsculas. As palavras and, or e not são analisadas como termos de pesquisa.

Comparações

As comparações têm o seguinte formato:

[FIELD_NAME] [OP] [VALUE]

Uma comparação tem três componentes:

• [FIELD_NAME]: é o identificador do caminho do campo de um campo numa entrada do registo. Seguem-se exemplos destes identificadores:

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

  Se um componente de um identificador do caminho de um campo tiver carateres especiais, o componente tem de estar entre aspas duplas. Por exemplo, "http://www.example.com/foo/bar" tem de estar entre aspas duplas porque contém uma barra /.compute.googleapis.com/resource_id

  Para ver detalhes, consulte os identificadores do caminho do campo neste documento.

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

  =           -- equal
  !=          -- not equal
  > < >= <=   -- numeric ordering
  :           -- "has" matches any substring in the log entry field
  =~          -- regular expression search for a pattern
  !~          -- regular expression search not for a pattern
  

Para saber como pesquisar entradas de registo através de expressões regulares, consulte o artigo Usar expressões regulares.

• [VALOR]: é um número, uma string, uma função ou uma expressão 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 valor [VALUE] é convertido no tipo do campo antes da comparação. Para valores nulos JSON, use NULL_VALUE.

Para filtrar um valor nulo JSON, use a seguinte sintaxe:

jsonPayload.field = NULL_VALUE      -- includes "field" with null value
NOT jsonPayload.field = NULL_VALUE  -- excludes "field" with null value

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

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

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

Identificadores do caminho do campo

Todas as entradas de registo são instâncias do tipo LogEntry. O identificador que é (ou começa) o lado esquerdo de uma comparação tem de ser um campo definido no tipo LogEntry. Para ver detalhes sobre os identificadores possíveis e os respetivos valores, consulte o tipo LogEntry.

Segue-se a lista atual de campos de entradas do registo. Cada campo é seguido do próximo nível de nomes para esse 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

Seguem-se exemplos de identificadores de caminhos de campos que pode usar nas suas comparações:

• resource.type: se o primeiro identificador de caminho for resource, o identificador seguinte tem de ser um campo no tipo MonitoredResource.

• httpRequest.latency: se o primeiro identificador do caminho for httpRequest, o identificador seguinte tem de ser um campo no tipo HttpRequest.

• labels.[KEY] Se o primeiro identificador do caminho for labels, o identificador seguinte, [KEY], tem de ser uma das chaves dos pares de chave-valor apresentados no campo labels.

• logName: uma vez que o campo logName é uma string, não pode ser seguido por nomes de subcampos.

Quando consulta campos map ou struct, tem de preservar a capitalização e a formatação das chaves na sua expressão.

Por exemplo, jsonPayload é um campo de estrutura, pelo que um nome de campo aninhado em jsonPayload, como jsonPayload.end_time, difere de jsonPayload.endTime. Da mesma forma, para um campo de mapa como labels, a chave da etiqueta labels.env_name é diferente de labels.envName. Por outro lado, quando consulta o campo de buffer de protocolo normal protoPayload, não precisa de preservar a capitalização.

Para ver informações sobre os tipos de campos LogEntry, consulte a referência google.logging.v2.

Carateres especiais

Se um campo LogEntry contiver carateres especiais, o campo de registo tem de estar entre aspas. Por exemplo:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Para ver a lista de carateres especiais, consulte a secção string em Valores e conversões.

Para mais informações sobre a utilização de identificadores de caminhos de campos que fazem referência a objetos ou matrizes, consulte Tipos de objetos e matrizes neste documento.

Tipos de recursos monitorizados

Para consultas mais rápidas, especifique um tipo de recurso monitorizado. Para ver uma lista de tipos de recursos, consulte o artigo Tipos de recursos monitorizados.

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. O exemplo seguinte mostra como limitar as suas consultas a ambos os tipos de VMs:

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

Os valores do tipo de recurso monitorizado nos registos são indexados. A utilização de correspondências de subcadeias de carateres para os mesmos resulta em consultas mais lentas.

Campos em falta

Se usar um nome de campo numa consulta e esse campo não aparecer numa entrada de registo, o campo está em falta, indefinido ou predefinido:

• Se o campo fizer parte da carga útil da entrada do registo (jsonPayload ou protoPayload) ou estiver numa etiqueta na secção labels da entrada do registo, significa que o campo está em falta. A utilização de um campo em falta não apresenta um erro, mas todas as comparações que usam campos em falta falham silenciosamente.

  Exemplos: jsonPayload.nearest_store, protoPayload.name.nickname

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

  Exemplos: httpRequest.remoteIp, trace, operation.producer

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

  Exemplos: thud, operation.thud, textPayload.thud

Para testar se existe um campo em falta ou predefinido sem testar um valor específico no campo, use a comparação :*. Por exemplo, a seguinte comparação é bem-sucedida se o campo operation.id estiver explicitamente presente numa entrada de registo:

operation.id:*

Tenha em atenção o comportamento das seguintes consultas:

• Quando usa o operador booleano NOT num campo em falta, o resultado é TRUE:

  -- Returns TRUE
  NOT missingField=foo
  

• Quando usa o operador de comparação não igual a != num campo em falta, o resultado é FALSE:

  -- Returns FALSE
  missingField!=foo
  

Tipos de objetos e matrizes

Cada campo de entrada do registo 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 para (ou de) uma string, como Duration e Timestamp, também são tipos escalares.

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

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

  Pode referir-se ao 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 são feitas comparações e [FIELD_NAME] é um campo de matriz, cada membro da matriz é comparado com [VALUE] e os resultados são unidos através do 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 é bem-sucedida.

Valores e conversões

O primeiro passo na avaliação de uma comparação é converter o valor do lado direito no tipo do campo de entrada do registo. Os tipos de campos escalares são permitidos em comparações, juntamente com 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 de buffer do protocolo escalar. A tabela seguinte explica que valores podem ser convertidos nos tipos de campos de registo:

Se uma tentativa de conversão falhar, a comparação falha.

Quando uma conversão requer uma string, também pode usar um número ou texto sem aspas se não contiverem carateres especiais, como espaços e operadores. Da mesma forma, quando uma conversão requer um número, pode usar uma string cujo conteúdo seja um número.

Os tipos intNN e uintNN representam tipos de números inteiros de vários tamanhos, como int32 e uint64. Quando escreve um valor a ser convertido num tipo de número inteiro de 64 bits, escreve o valor como uma string, como "9223372036854775807".

Tipos de campos de registo

Veja como é determinado o tipo de um campo de entrada do registo:

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

• Os campos de registo 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 protocolo buffer é armazenado no campo "@type" de protoPayload. Para mais informações, consulte o mapeamento JSON.

  Quando está a filtrar um campo associado ao tipo de mensagem Any, o campo value é percorrido automaticamente. Por conseguinte, não o inclua na consulta. Para mais informações, consulte a secção Resolução de problemas.

• Os campos de registo no interior de jsonPayload têm tipos que são inferidos a partir do valor do campo quando a entrada de registo é recebida:

  • Os campos cujos valores são números sem aspas têm o tipo double.
  • Os campos cujos valores são true ou false têm o tipo bool.
  • Os campos cujos valores são strings têm o tipo string.

  Os números 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. Noutro local, esses valores são armazenados em campos de string.

Comentários

Os comentários começam com dois traços (--) e qualquer texto após os traços é ignorado até ao final da linha. Os comentários podem ser colocados no início de um filtro, entre termos e no final de um filtro.

Pode usar os comentários para os seguintes casos:

• Para anotar os seus filtros complexos com informações sobre o que uma cláusula faz:

   -- All of our target users are emitted by Compute Engine instances.
   resource.type = "gce_instance"
   -- Looking for logs from "alex".
   jsonPayload.targetUser = "alex"

• Para ativar ou desativar rapidamente uma cláusula, adicione ou remova o prefixo do comentário:

   resource.type = "gce_instance"
   -- jsonPayload.targetUser = "alex"
   jsonPayload.targetUser = "kiran"
   -- jsonPayload.targetUser = "sasha"

Operadores de comparação

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

• Todos os tipos numéricos: a igualdade e a desigualdade têm o seu significado normal para os números.
• bool: a igualdade significa o mesmo valor Booleano. A desigualdade é definida por true>false.
• enum: a 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. A desigualdade baseia-se na duração. Exemplo: como durações, "1s">"999ms".
• Timestamp: a igualdade significa o mesmo instante no tempo. Se a e b forem valores Timestamp, a < b significa que a ocorre antes de b.
• bytes: os operandos são comparados byte a byte, da esquerda para a direita.
• string: as comparações ignoram as maiúsculas e minúsculas. Especificamente, ambos os operandos são normalizados primeiro através da normalização Unicode NFKC_CF e, em seguida, usam comparações lexicográficas. No entanto, as pesquisas de expressões regulares não são normalizadas. Para mais informações sobre a pesquisa de entradas de registo com expressões regulares, consulte o artigo Usar expressões regulares.

O operador de substring (:) é aplicável a string e bytes e é processado como igualdade, exceto que o operando direito só precisa de ser igual a alguma parte do campo esquerdo. As correspondências de subcadeias em campos indexados não tiram partido dos índices de registos.

Restrições globais

Se a comparação consistir num único valor, denomina-se restrição global. O registo usa o operador has (:) para determinar se algum campo numa entrada de registo ou se a respetiva carga útil contém a restrição global. Se for o caso, a comparação é bem-sucedida.

A consulta mais simples escrita em termos de uma restrição global é um valor único:

"The Cat in The Hat"

Pode combinar restrições globais através dos operadores AND e OR para uma consulta mais interessante. Por exemplo, se quiser apresentar todas as entradas do registo que tenham um campo que contenha cat e um campo que contenha hat ou bat, escreva a consulta da seguinte forma:

("cat" AND ("hat" OR "bat"))

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

Uma restrição global é uma forma de consultar os seus registos para um valor específico. Por exemplo, se estiver a procurar no seu registo de atividade entradas que contenham alguma menção de GCE_OPERATION_DONE, pode usar a seguinte consulta:

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

Em vez de usar restrições globais, que podem ser lentas, recomendamos que use a função SEARCH integrada e consulte campos indexados. Para mais informações, consulte o artigo Encontrar rapidamente entradas de registo neste documento.

Funções

Pode usar funções integradas como restrições globais em consultas:

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

onde argument é um valor, um nome de campo ou uma expressão entre parênteses. As funções estão descritas nas secções seguintes.

log_id

A função log_id é útil quando cria uma vista de registo personalizada num contentor de registos que contém entradas de registo de Google Cloud muitos Google Cloud projetos, pastas ou organizações.

O único argumento da função log_id é um ID do registo não codificado por URL:

log_id(non-URL-encoded log ID)

Por exemplo, a seguinte consulta devolve todos os registos de auditoria de atividade:

log_id("cloudaudit.googleapis.com/activity")

Na consulta anterior, o argumento consiste apenas em carateres alfanuméricos e carateres especiais (/, _, - e .).

transmitir

A função cast aceita dois parâmetros: o campo LogEntry a ser convertido e o tipo de dados para o qual o campo é convertido:

cast([FIELD], [TYPE][, OPTION])

Os parâmetros da expressão anterior são definidos da seguinte forma:

• [FIELD]: o nome de um campo na entrada do registo, como logName ou jsonPayload.a_field.

• [TYPE]: o tipo de dados, como STRING, INT64, FLOAT64 e BOOL.

  • TIMESTAMP ou DURATION: alguns tipos de dados oferecem opções adicionais, como especificar um fuso horário da base de dados de fusos horários da IANA para o tipo de dados TIMESTAMP.

Por exemplo, a consulta seguinte converte o campo timestamp numa STRING e especifica o fuso horário America/New_York:

cast(timestamp, STRING, TIME_ZONE("America/New_York")) =~ "^2025-04-02.*"

regexp_extract

Use a função regexp_extract para encontrar a primeira substring que corresponda a uma expressão regular:

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

Na expressão anterior, os campos são definidos da seguinte forma:

• [FIELD]: o nome de um campo na entrada do registo, como logName ou jsonPayload.a_field.
• [REGULAR_EXPRESSION]: A expressão regular RE2 que tem de conter um grupo de captura ((...)). Tem de usar um grupo sem captura (?:...) se for necessário um agrupamento adicional para a expressão regular. Vários grupos de captura ou nenhum grupo de captura resultam num erro.

Pode encadear as funções cast e regexp_extract:

CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:(\\d+)"), INT64) < 30

O exemplo anterior converte o campo timestamp numa string. A expressão regular capta o valor do campo de segundos da string timestamp e, em seguida, converte-o num número inteiro para fazer uma comparação numérica. O resultado da consulta apresenta uma entrada de registo quando o campo de segundos da respetiva data/hora é inferior a 30.

fonte

A função source corresponde a entradas de registo de um recurso específico na hierarquia de organizações, pastas e projetos Google Cloud .

A função source não corresponde aos recursos secundários. Por exemplo, usar source(folders/folder_123) corresponde aos registos do recurso folder_123, e não aos registos dos recursos do projeto em folder_123. Google Cloud

Para consultar registos a um nível de recurso específico, use a seguinte sintaxe:

source(RESOURCE_TYPE/RESOURCE_ID)

exemplo

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

sample([FIELD], [FRACTION])

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

[FRACTION] é a fração de entradas de registo que têm valores para [FIELD] a incluir. É um número superior a 0,0 e inferior ou igual a 1,0. Por exemplo, se especificar 0.01, a amostra contém aproximadamente um por cento de todas as entradas de registo que têm valores para [FIELD]. Se [FRACTION] for 1, são escolhidas todas as entradas de registo que tenham valores para [FIELD].

Exemplo: a seguinte consulta devolve 25% das entradas de registo do registo syslog:

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

Detalhes: É usado um algoritmo determinístico, baseado na aplicação de hash, para determinar se uma entrada de registo é incluída ou excluída da amostra. A precisão da amostra resultante depende da distribuição dos valores com hash. Se os valores com hash não estiverem distribuídos uniformemente, a amostra resultante pode ser enviesada. No pior caso, quando [FIELD] contém sempre o mesmo valor, a amostra resultante contém o [FRACTION] de todas as entradas do registo ou nenhuma entrada do registo.

Se [FIELD] aparecer numa entrada de registo:

• É calculado um hash do valor.
• O valor com hash, que é um número, é dividido pelo valor com hash máximo possível.
• Se a fração resultante for inferior ou igual a [FRACTION], a entrada de registo é incluída na amostra. Caso contrário, é excluída da amostra.

Se o ícone [FIELD] não aparecer numa entrada do registo, significa que:

• Se [FIELD] fizer parte das secções de payload ou labels da entrada do registo, a entrada do registo não é selecionada para a amostra, mesmo que [FRACTION] seja 1.
• Caso contrário, a entrada de registo é tratada como se [FIELD] estivesse na entrada de registo e o valor de [FIELD] é o valor predefinido. O valor predefinido é determinado pelo tipo LogEntry. Para mais informações sobre campos em falta e predefinidos, consulte a secção Campos em falta neste documento.

Para excluir entradas de registo com campos predefinidos da amostra, use o operador field-exists, :*. A consulta seguinte produz uma amostra de 1% das entradas de registo 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 numa entrada de registo está contido numa sub-rede. Pode usar isto para saber se um pedido é proveniente de uma fonte interna ou externa. Por exemplo:

ip_in_net([FIELD], [SUBNET])

[FIELD] é um campo com valor de string na entrada do registo que contém um endereço IP ou um intervalo. O campo pode ser repetido, caso em que apenas um dos campos repetidos tem de ter um endereço ou um intervalo contido na sub-rede.

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

Exemplo: a consulta seguinte testa um endereço IP no payload das entradas de registo do registo my_log:

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

Detalhes: se, numa entrada de registo, [FIELD] estiver em falta, for o valor predefinido ou não contiver um endereço IP ou um intervalo de IP legal, a função devolve o valor falso. Para mais informações sobre campos em falta e predefinidos, consulte Campos em falta neste documento.

Seguem-se exemplos dos intervalos e endereços IP suportados:

• 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 IPv6 CIDR: 1:2::/48

Função SEARCH

Pode usar a função incorporada SEARCH para encontrar strings nos seus dados de registo:

SEARCH([query])
SEARCH([field], [query])

Ambas as formas da função SEARCH contêm um argumento query, que tem de ser formatado como um literal de string. No primeiro formulário, é feita uma pesquisa em toda a entrada do registo. No segundo formulário, especifica o campo na entrada do registo a pesquisar.

Tem de especificar o campo query. Se este campo não for especificado, é devolvido um erro.

Quando a função SEARCH é processada, a string query é processada por um analisador de texto que divide a string em tokens. O Cloud Logging realiza sempre comparações sem distinção entre maiúsculas e minúsculas, mesmo para tokens envolvidos com acentos graves. Este comportamento difere do do BigQuery, que preserva a capitalização em tokens envolvidos em acentos graves. Para obter informações sobre as regras do analisador, consulte o documento do BigQuery Regras do analisador de texto.

Ao criar uma pesquisa, considere o seguinte:

• Os tokens não são sensíveis a maiúsculas e minúsculas. As seguintes funções produzem os mesmos resultados:

  SEARCH("world")
  SEARCH("World")
  

  As funções anteriores correspondem a uma entrada de registo quando um único campo contém o token "world". Uma vez que SEARCH faz correspondências exatas e não correspondências de subcadeias de carateres, as funções anteriores não correspondem a um campo cujo valor seja "worldwide".

• Se não especificar o campo a pesquisar, a função SEARCH corresponde a uma entrada de registo quando essa entrada de registo contém todos os tokens. No entanto, a ordem dos tokens não é importante e não é necessário que os tokens sejam encontrados no mesmo campo da entrada do registo.

  As seguintes funções produzem os mesmos resultados e correspondem a uma entrada de registo que contém os tokens "hello" e "world":

  SEARCH("hello world")
  SEARCH("World hello")
  

• Se especificar o campo a pesquisar, a função SEARCH só pesquisa nesse campo. Ocorre uma correspondência quando esse campo contém todos os tokens; no entanto, a ordem dos tokens não é importante.

  As seguintes funções produzem uma correspondência apenas quando o campo textPayload contém os tokens "olá" e "mundo":

  SEARCH(textPayload, "hello world")
  

• Para impor uma correspondência exata, mas não sensível a maiúsculas e minúsculas, numa expressão, coloque a expressão entre acentos graves. Por exemplo, as seguintes funções correspondem à string "hello world":

  SEARCH("`hello world`")
  SEARCH("`Hello World`")
  SEARCH("`HELLO WORLD`")
  

  Uma vez que os acentos graves são usados nas seguintes funções, produzem resultados diferentes:

  SEARCH("`hello world`")
  SEARCH("`world hello`")
  

A linguagem de consulta do Logging suporta diferentes formas de pesquisar os seus dados de registo. Quando pesquisa uma string, é mais eficiente usar a função SEARCH do que fazer uma pesquisa global ou uma pesquisa de substring. No entanto, não pode usar a função SEARCH para fazer corresponder campos que não sejam de texto. Para orientações sobre como realizar operações de pesquisa, consulte o artigo Minimize as pesquisas globais e de subcadeias.

Pesquisar por hora

Na interface, pode definir limites específicos na data e hora das entradas do registo a apresentar. Por exemplo, se adicionar as seguintes condições à sua consulta, o painel de resultados apresenta exatamente as entradas do registo no período de 30 minutos indicado e não pode deslocar a página para fora desse intervalo de datas:

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

Ao escrever uma consulta com uma data/hora, tem de usar datas e horas no formato apresentado anteriormente.

Também pode pesquisar entradas de registo através de atalhos timestamp. Por exemplo, pode introduzir uma data com um operador de comparação para obter todas as entradas do registo após um determinado dia:

timestamp > "2023-11-29"

Usar expressões regulares

Pode usar expressões regulares para criar consultas e filtros para destinos, métricas e onde quer que sejam usados filtros de registos. Por exemplo, pode usar expressões regulares no Explorador de registos e com a CLI do Google Cloud.

Uma expressão regular é uma sequência de carateres que define uma pesquisa. A linguagem de consulta de registo usa a sintaxe RE2. Para uma explicação completa da sintaxe RE2, consulte a wiki RE2 no GitHub.

As consultas de expressões regulares têm as seguintes características:

• Só é possível fazer a correspondência de campos do tipo string com uma expressão regular.

• A normalização de strings não é realizada. Por exemplo, kubernetes não é considerado o mesmo que KUBERNETES. Para mais informações, consulte a secção Operadores de comparação.

• As consultas são sensíveis a maiúsculas e minúsculas e não são ancoradas por predefinição.

• É possível usar operadores booleanos entre várias expressões regulares no lado direito do operador de comparação de expressões regulares, =~ e !~.

Uma consulta de expressão regular tem a seguinte estrutura:

Fazer corresponder um padrão:

jsonPayload.message =~ "regular expression pattern"

Não corresponde a um padrão:

jsonPayload.message !~ "regular expression pattern"

Os carateres =~ e !~ alteram a consulta para uma consulta de expressão regular, e o padrão que está a tentar fazer corresponder tem de estar entre aspas. Para consultar padrões que contêm aspas duplas, use um carater de escape com uma barra invertida.

Exemplos de consultas de registos com expressões regulares

Encontrar entradas do registo rapidamente

Para encontrar entradas do registo de forma eficiente, faça o seguinte:

• Consultar através de campos indexados.
• Minimize o número de entradas de registo que têm de ser pesquisadas.

Use campos indexados

O registo indexa sempre os seguintes campos LogEntry:

• resource.type
• resource.labels.*
• logName
• gravidade
• timestamp
• insertId
• operation.id
• trace
• httpRequest.status
• labels.*
• split.uid

Também pode adicionar campos indexados personalizados a qualquer contentor de registos ou usar a função SEARCH para acelerar a sua consulta.

Otimize as suas consultas

Torne as suas pesquisas mais rápidas reduzindo o número de registos, o número de entradas de registo ou o intervalo de tempo das suas pesquisas. Melhor ainda, pode reduzir todos os três.

Exemplo: use a função SEARCH

Em vez de fazer pesquisas globais ou de subcadeias, pode usar a função SEARCH para usar índices para otimizar as suas consultas.

Exemplo: use o nome do registo correto

Especifique o registo que contém as entradas de registo nas quais tem interesse. Certifique-se de que conhece o nome do registo real inspecionando uma das suas entradas de registo. Por exemplo, o painel de resultados mostra que a secção do Compute Engine contém um registo denominado "activity". Após uma inspeção mais detalhada das entradas do registo de auditoria da atividade do administrador, o registo tem, na verdade, o nome "cloudaudit.googleapis.com/activity".

A seguinte comparação está incorreta. Não corresponde a nada porque usa o nome do registo errado:

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

A comparação seguinte está correta. Escolhe entradas de registo das entradas de registo de auditoria de atividade de administrador. Tem de codificar o nome do registo em URL, conforme mostrado:

logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

Exemplo: escolha as entradas de registo certas

Se souber que as entradas de registo que quer provêm de uma instância de VM específica, especifique-a. Verifique se os nomes das etiquetas estão corretos inspecionando uma das entradas de registo que quer pesquisar. No exemplo seguinte, instance_id é uma das etiquetas indexadas:

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

Exemplo: escolha o período certo

Especifique um período para pesquisar. Uma forma rápida de determinar as indicações de tempo úteis no formato RFC 3339 é usar o comando date do GNU/Linux:

$ date --rfc-3339=s
2023-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2023-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2023-06-27 12:40:00-04:00

Use os valores destas datas/horas nas seguintes consultas. Para criar uma data/hora aceitável para o registo, substitua o espaço entre a data e a hora pela letra T.

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

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

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

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

Minimize as restrições disjuntivas

As consultas que usam apenas restrições conjuntivas, AND, podem tirar melhor partido dos índices. Pode usar a restrição disjuntiva, OR, mas estas consultas podem ser lentas e não podem usar índices.

Por exemplo, SEARCH("foo") AND SEARCH("bar") usa índices e é mais rápido do que uma consulta como SEARCH("foo") OR SEARCH("bar").

Minimize as pesquisas globais e de subcadeias de carateres

Evite a tentação de usar atalhos ao escrever consultas.

Exemplo: não use pesquisas globais

Se estiver a pesquisar uma entrada de registo com "Hello Kitty" no conteúdo:

• Não use uma pesquisa global. Por um lado, são todas pesquisas de substrings:

     "Hello Kitty"   -- THIS CAUSES A SLOW SEARCH!
     

• Limite a pesquisa a um único campo, mesmo que tenha de manter a pesquisa de substring:

     textPayload:"Hello Kitty"
     

• Use um teste de igualdade se puder:

     textPayload = "Hello Kitty"
     

• Faça referência a campos individuais num payload se as suas entradas de registo 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"
     

• Use a função SEARCH e especifique o texto completo a corresponder. A função SEARCH faz uma correspondência que não distingue maiúsculas de minúsculas:

    SEARCH("Hello Kitty")
    

  Não use a função SEARCH e especifique texto parcial. Por exemplo, a seguinte função não corresponde a "Hello Kitty".

    SEARCH("Hello Kit")
    

Exemplos de pesquisas

As entradas de registo apresentadas são as que correspondem a uma consulta. Se o menu Avançar para tempo contiver um valor, o ecrã desloca-se para esse ponto no tempo. Seguem-se alguns exemplos de consultas:

resource.type=k8s_cluster

Encontra todas as entradas de registo do Google Kubernetes Engine. Para ver uma lista de tipos de recursos, consulte o artigo Lista de recursos monitorizados.

À medida que escreve, o painel de consultas sugere conclusões para campos como resource.type.

resource.type=k8s_cluster AND logName:request_log

Encontra entradas de registo para clusters do Google Kubernetes Engine a partir de nomes de registos que contenham request_log. Tenha em atenção o seguinte:

• O operador = é igualdade exata. O tipo de recurso tem de ser exatamente "k8s_cluster", exceto no que diz respeito a letras maiúsculas e minúsculas.
• O operador : significa "tem". O campo logName tem de conter request_log, em qualquer combinação de letras maiúsculas e minúsculas. O nome do registo real é muito mais longo. A utilização de : pode resultar em pesquisas mais lentas.
• As duas comparações estão unidas por AND. Também pode usar OR, mas AND é assumido se omitir o operador.

resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Encontra entradas de registo com um de dois tipos de recursos: instância de VM do Compute Engine ou instância de VM do AWS EC2. As entradas do registo têm de ter uma gravidade de, pelo menos, ERROR, o que equivale a selecionar ERROR no menu de gravidade da interface de consulta.severity

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

Encontra todas as entradas do registo de auditoria da atividade do administrador no projeto [PROJECT_ID]. Todos os registos de auditoria usam o mesmo nome de registo num projeto, mas têm diferentes tipos de recursos. O ID do registo, cloudaudit.googleapis.com/activity, tem de ser codificado por URL no nome do registo. A utilização da igualdade na comparação acelera a pesquisa. Para mais informações, consulte o artigo Compreender os registos de auditoria.

unicorn

Encontra entradas do registo que contenham unicorn em qualquer campo, com qualquer combinação de letras maiúsculas e minúsculas. Um termo de pesquisa que não faz parte de uma comparação de campos é uma consulta de "todos os campos".

unicorn phoenix

Encontra entradas de registo que contêm unicorn num determinado campo e phoenix num determinado campo.

textPayload:(unicorn phoenix)

Encontra entradas de registo cujo campo textPayload contém unicorn e phoenix por qualquer ordem. O AND é implícito entre as duas palavras.

textPayload:"unicorn phoenix"

Encontra entradas de registo cujo campo textPayload contém a string "unicorn phoenix".

NOT textPayload: "unicorn phoenix"

Encontra entradas de registo cujo campo textPayload não contém a string "unicorn phoenix". Este tipo de consulta reduz as entradas de registo indesejadas.

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

Encontra entradas de registo num período de 30 minutos.

Resolução de problemas

Problemas de sintaxe

Se tiver problemas com as expressões das suas consultas, verifique o seguinte:

• A sua consulta obedece às regras de sintaxe, com parênteses e aspas correspondentes.

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

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

• Certifique-se de que está a usar NULL_VALUE para representar valores nulos JSON.

• As expressões booleanas como restrições globais ou como o lado direito das comparações devem ser colocadas entre parênteses para maior clareza. Por exemplo, as duas consultas seguintes 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 carateres especiais. Em caso de dúvida, adicione aspas. Por exemplo, na comparação seguinte, a primeira comparação é ilegal devido ao operador de subcadeia incorporado (:). A comparação tem de ser escrita com aspas:

  insertId = abc:def  -- ILLEGAL!
  insertId = "abc:def"
  

• A CLI do Google Cloud requer que a consulta esteja entre aspas duplas. Para usar as aspas duplas para ignorar carateres especiais com o comando gcloud logging, envolva toda a consulta com aspas simples:

  gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
  gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
  

• Quando está a filtrar um campo associado ao tipo de mensagem Any, o campo value é percorrido automaticamente. Por conseguinte, não inclua value na consulta.

  Por exemplo, o campo Status numa mensagem AuditLog tem um campo details do tipo google.protobuf.Any. Para consultar o campo details, omita o campo value quando especificar o filtro:

  • O que fazer

    protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"
    

  • O que não deve fazer

    protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"