Filtros do Cloud Trace

Use filtros de trace para selecionar um conjunto de traces do Cloud Trace. Você pode fazer isso da seguinte forma:

  • Como o parâmetro de filtro em uma consulta usando o método de API list.

  • Como o parâmetro do filtro Solicitação ao criar um relatório de análise.

  • Como o campo Filtro na página Explorador de traces. Para informações sobre como criar e modificar esses filtros, consulte Exibir traces recentes.

Os filtros permitem especificar uma ou mais condições que precisam ser atendidas para que um trace seja exibido. A sintaxe do filtro permite definir quando as correspondências são exatas ou quando são testes de prefixo. Todas as correspondências diferenciam maiúsculas de minúsculas.

Visão geral do filtro

Os filtros de traces consistem em uma sequência de comparações denominada termos. Os traces precisam corresponder a todos os termos no filtro a serem selecionados. Por exemplo, o filtro a seguir corresponde a traces com latência de um segundo ou mais e que contêm um período chamado /modules.GetNumInstances:

+span:/modules.GetNumInstances latency:1s

Todas as comparações de string diferenciam maiúsculas e minúsculas.

Atributos booleanos

Se quiser especificar valores para atributos booleanos, use 0 para falso e 1 para verdadeiro. Por exemplo:

Client:0

Caracteres especiais

Para procurar um valor que contenha um espaço ou o caractere de dois pontos (:), coloque-o entre aspas duplas ("). Por exemplo:

    label:"Notice: This value contains spaces and a colon"

Para procurar o caractere de aspas duplas ou de barra invertida (\) dentro de uma string entre aspas, faça o escape do caractere com uma barra invertida. Por exemplo:

    label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

Sintaxe do filtro

Na tabela a seguir e em outros locais desta página, NAME refere-se ao nome de um campo, enquanto VALUE refere-se ao valor de um par de chave-valor. As strings _PREFIX e _EXACT são indicações visuais de que o teste é de prefixo ou uma correspondência exata. Por exemplo, root:[NAME_PREFIX] significa que o nome do período raiz precisa começar com [NAME_PREFIX].

A tabela a seguir lista a sintaxe usada nos filtros do Cloud Trace:

API Trace
Filtro de solicitações no Relatórios de análise página		 Filtrar na página Explorador de traces
root:[NAME_PREFIX] RootSpan:[NAME_PREFIX]
+root:[NAME_EXACT] RootSpan:+[NAME_EXACT]
span:[NAME_PREFIX] SpanName:[NAME_PREFIX]
+span:[NAME_EXACT] SpanName:+[NAME_EXACT]
[NAME_PREFIX] RootSpan:[NAME_PREFIX]
label:[LABEL_KEY] HasLabel:[LABEL_KEY]
[LABEL_KEY]: [VALUE_PREFIX] [LABEL_KEY]:[VALUE_PREFIX]*
+[LABEL_KEY]: [VALUE_EXACT] [LABEL_KEY]:+[VALUE]*
^[LABEL_KEY]: [VALUE_PREFIX] [LABEL_KEY]:^[VALUE_PREFIX]*
+^[LABEL_KEY]: [VALUE_EXACT] [LABEL_KEY]:^+[VALUE_EXACT]*, †
method:[VALUE_PREFIX] Method:[VALUE_PREFIX]
latency:10ms MinLatency:10ms
url:[VALUE_PREFIX] URL:[VALUE_PREFIX]

* Não use estas palavras-chave do Trace como chaves de rótulo: root, span, label, method, latency e url. Os traces com essas chaves de rótulos não podem ser consultados.
† Na página Explorador de traces, a anotação +^ é convertida em ^+ quando você pressiona Enter.

O restante desta página contém uma descrição para filtros ao usar a API Trace e o Filtro de solicitação na página Relatórios de análise. Se você estiver usando o campo Filtro na página Explorador de traces, poderá usar o mapeamento na tabela anterior para criar uma expressão equivalente.

Exemplos de filtro de solicitação

Confira a seguir a descrição dos termos do filtro:

root:[NAME_PREFIX]

O nome do período raiz do trace precisa começar com [NAME_PREFIX]. Por exemplo, o filtro a seguir corresponde a um trace chamado "/_ah/background", mas não a um "/_ahx/background":

root:/_ah/
+root:[NAME]

O nome do período raiz do trace precisa ser exatamente [NAME]. Exemplo:

+root:/_ah/background
[NAME_PREFIX]

Essa sintaxe é um atalho para root:[NAME_PREFIX].

+[NAME]

Essa sintaxe é um atalho para +root:[NAME].

span:[NAME_PREFIX]

O trace precisa ter pelo menos um intervalo cujo nome comece com [NAME_PREFIX]. Exemplo:

span:/modules.
+span:[NAME]

O trace precisa ter pelo menos um espaço cujo nome seja exatamente [NAME]. Por exemplo,

span:/modules.GetNumInstances
latency:[DURATION]

O trace precisa ter uma latência geral maior ou igual a [DURATION]. A duração é expressa como um número inteiro seguido por um especificador de unidades: s para segundos, ms para milissegundos ou ns para nanossegundos. Se não houver um especificador de unidade, as unidades serão milissegundos. Por exemplo, as quatro durações a seguir são iguais:

 12s 12000ms 12000000ns 12000
label:[LABEL_KEY]

O trace precisa conter exatamente a chave de rótulo especificada. O valor do rótulo (se houver) não importa. Por exemplo:

label:/http/url
[LABEL_KEY]:[VALUE_PREFIX]

O trace precisa conter exatamente a chave de rótulo especificada, e o valor do marcador precisa começar com [VALUE_PREFIX]. Por exemplo, o termo a seguir corresponde a traces cuja versão do App Engine começa com "2017".

g.co/gae/app/module_version:2017
+[LABEL_KEY]:[VALUE_EXACT]

O trace precisa conter exatamente a chave de rótulo e o valor especificados. Por exemplo:

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[VALUE_PREFIX]

Essa sintaxe é um atalho para o teste de rótulo, /http/method:[VALUE_PREFIX].

+method:[VALUE_EXACT]

Essa sintaxe é um atalho para o teste de rótulo, +/http/method:[VALUE_EXACT].

url:[VALUE_PREFIX]

Essa sintaxe é um atalho para o teste de rótulo, /http/url:[VALUE_PREFIX].

+url:[VALUE_EXACT]

Essa sintaxe é um atalho para o teste de rótulo, +/http/url:[VALUE_EXACT].

Exemplos de pesquisa de período raiz

Para restringir o termo de pesquisa apenas ao período raiz, adicione um (^) antes de um termo de pesquisa e depois do opcional (+). Para o campo Filtro na página Trace Explorer, se você adicionar a anotação +^, ela será convertida em ^+ quando você pressionar Enter.

Veja a seguir alguns termos de pesquisa que usam apenas o período raiz e as equivalências deles:

^label:[LABEL_KEY]
Essa é uma pesquisa de período raiz para label:[LABEL_KEY].
^[LABEL_KEY]:[VALUE_PREFIX]
Essa é uma pesquisa de período raiz para [LABEL_KEY]:[VALUE_PREFIX].
+^[LABEL_KEY]:[VALUE]
Essa é uma pesquisa de período raiz para +[LABEL_KEY]:[VALUE].
^method:[VALUE_PREFIX]
Essa é uma pesquisa de período raiz para method:[VALUE_PREFIX].
+^method:[VALUE]
Essa é uma pesquisa de período raiz para +method:[VALUE].
^url:[VALUE_PREFIX]
Essa é uma pesquisa de período raiz para url:[VALUE_PREFIX].
+^url:[VALUE]
Essa é uma pesquisa de período raiz para +url:[VALUE].
^span:[NAME_PREFIX]
Isso é equivalente a root:[NAME_PREFIX].
+^span:[NAME]
Isso é equivalente a +root:[NAME].

Ao criar uma consulta com termos mistos, a pesquisa pode ser ainda mais personalizada. Por exemplo:

    +^url:/main /images method:200

corresponde a traces quando o rótulo de período raiz /http/url é exatamente "/main", o nome do período raiz é prefixado por /images e qualquer período tem o rótulo /http/method com um valor de 200.

Solução de problemas

Esta seção tem conteúdo sobre solução de problemas.

Baixo desempenho

Se o filtro de trace for complicado, ele levará mais tempo para ser executado e poderá expirar. Para melhorar o desempenho, simplifique o filtro.

Nenhum resultado

Se o filtro não retornar nenhum trace, verifique o seguinte:

  • Verifique se não existem espaços no filtro, exceto os que separam as comparações.

  • Verifique se as letras maiúsculas e minúsculas e a ortografia de todas as palavras no filtro estão corretas. Por exemplo, se você digitar incorretamente uma palavra-chave como method:GET, o filtro será interpretado como label:method:GET, que não corresponde a nenhum trace.

  • Para testar os termos do filtro, um de cada vez, use o filtro da lista de traces ou o APIs Explorer. Se um dos termos não retornar resultados, o problema poderá estar nele.