Usar expressões de filtro

Use expressões de filtro para visualizar um mapa de rastreamento ou rastreamentos para uma solicitação específica, serviço, conexão entre dois serviços (uma borda) ou solicitações que satisfaçam uma condição. O X-Ray fornece uma linguagem de expressão de filtro para filtrar solicitações, serviços e bordas com base em dados em cabeçalhos de solicitação, status de resposta e campos indexados nos segmentos originais.

Ao escolher um período de rastreamento para visualizar no console do X-Ray, você pode obter mais resultados do que o console é capaz de exibir. No canto superior direito, o console mostra o número de rastreamentos que verificou e se há mais rastreamentos disponíveis. É possível usar uma expressão de filtro para estreitar os resultados a apenas rastreamentos que você deseja localizar.

Detalhes de expressão de filtro

Quando você escolhe um nó no mapa de rastreamento, o console constrói uma expressão de filtro com base no nome do serviço do nó e nos tipos de erro presentes com base na sua seleção. Para encontrar rastreamentos que mostram problemas de desempenho ou relacionados a solicitações específicas, é possível ajustar a expressão fornecida pelo console ou criar a sua própria. Se você adicionar anotações com o X-RaySDK, também poderá filtrar com base na presença de uma chave de anotação ou no valor de uma chave.

nota

Se você escolher um intervalo de tempo relativo no mapa de rastreamento e escolher um nó, o console converterá o intervalo de tempo em um horário absoluto de início e término. Para garantir que os rastreamentos do nó apareçam nos resultados da pesquisa e evitar tempos de verificação quando o nó não estava ativo, o intervalo de tempo inclui apenas as horas em que o nó enviou rastreamentos. Para pesquisar com relação à hora atual, é possível voltar a um intervalo de tempo relativo na página de rastreamentos e verificar novamente.

Se ainda houver mais resultados disponíveis além do que o console pode mostrar, o console mostrará o número de rastreamentos correspondidos e o número de rastreamentos verificados. A porcentagem mostrada é a porcentagem do intervalo de tempo selecionado que foi verificado. Para garantir que você veja todos os rastreamentos correspondentes representados nos resultados, restrinja mais sua expressão de filtro ou escolha um limite de tempo mais curto.

Para obter os resultados mais recentes primeiro, o console inicia a verificação no final do intervalo de tempo e trabalha retroativamente. Se houver um grande número de rastreamentos, mas poucos resultados, o console dividirá o intervalo de tempo em partes e os verificará em paralelo. A barra de progresso mostra as partes do intervalo de tempo que foram verificadas.

Usar expressões de filtro com grupos

Os grupos são uma coleção de rastreamentos definidos por uma expressão de filtro. Você pode usar grupos para gerar gráficos de serviços adicionais e fornecer CloudWatch métricas da Amazon.

Os grupos são identificados por seu nome ou por um nome de recurso da Amazon (ARN) e contêm uma expressão de filtro. O serviço compara os rastreamentos de entrada com a expressão e os armazena adequadamente.

É possível criar e modificar grupos usando o menu suspenso à esquerda da barra de pesquisa da expressão de filtro.

nota

Se o serviço encontrar um erro na qualificação de um grupo, esse grupo não estará mais incluído no processamento de rastreamentos de entrada e uma métrica de erro será registrada.

Para obter mais informações sobre grupos, consulte Configurar grupos.

Sintaxe de expressão de filtro

As expressões de filtro podem conter uma palavra-chave, um operador unário ou binário e um valor para comparação.

keyword operator value

Operadores diferentes estão disponíveis para tipos diferentes de palavras-chave. Por exemplo, responsetime é uma palavra-chave de número e pode ser comparada com os operadores relacionados a números.

exemplo Exemplo: solicitações em que o tempo de resposta foi superior a 5 segundos

responsetime > 5

É possível combinar várias expressões em uma expressão composta usando os operadores AND ou OR.

exemplo Exemplo: solicitações em que a duração total foi de 5 a 8 segundos

duration >= 5 AND duration <= 8

Palavras-chave e operadores simples encontram problemas apenas no nível de rastreamento. Se ocorrer um erro de downstream, mas é controlado pelo seu aplicativo e não retornado ao usuário, uma pesquisa por error não o encontrará.

Para encontrar rastreamentos com problemas de downstream, use as palavras-chave complexas service() e edge(). Essas palavras-chave permitem que você aplique uma expressão de filtro a todos os nós de downstream, um único nó de downstream ou uma borda entre dois nós. Para obter mais granularidade, filtre os serviços e bordas por tipo com a função id().

Palavras-chave boolianas

Os valores de palavras-chave boolianas são verdadeiros ou falsos. Use essas palavras-chave para encontrar rastreamentos que resultaram em erros.

Palavras-chave boolianas

• ok: o código de status da resposta foi 2XX Êxito.

• error: o código de status da resposta foi 4XX Erro do cliente.

• throttle: o código de status da resposta foi 429 Solicitações em excesso.

• fault: o código de status da resposta foi 5XX Erro do servidor.

• partial: a solicitação tem segmentos incompletos.

• inferred: a solicitação inferiu segmentos.

• first: o elemento é o primeiro de uma lista enumerada.

• last: o elemento é o último de uma lista enumerada.

• remote: a entidade de causa raiz é remota.

• root: o serviço é o ponto de entrada ou o segmento raiz de um rastreamento.

Os operadores boolianos encontram segmentos onde a chave especificada é true ou false.

Operadores booleanos

• none: a expressão é verdadeira se a palavra-chave for verdadeira.

• !: a expressão é verdadeira se a palavra-chave for falsa.

• =,!=: compara o valor da palavra-chave com a string true ou false. Estes operadores agem da mesma forma que os outros operadores, mas são mais explícitos.

exemplo Exemplo: o status de resposta é 2XX OK

ok

exemplo Exemplo: o status de resposta não é 2XX OK

!ok

exemplo Exemplo: o status de resposta não é 2XX OK

ok = false

exemplo Exemplo: o último rastreamento de falha enumerado tem o nome de erro "deserialize"

rootcause.fault.entity { last and name = "deserialize" }

exemplo Exemplo: solicitações com segmentos remotos em que a cobertura é maior que 0,7 e o nome do serviço é "traces"

rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }

exemplo — solicitações com segmentos inferidos em que o tipo de serviço é “:DynamoDB” AWS

rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }

exemplo Exemplo: solicitações que têm um segmento com o nome "data-plane" como raiz

service("data-plane") {root = true and fault = true}

Palavras-chave de número

Use palavras-chave de número para pesquisar solicitações com um tempo de resposta, duração ou status de resposta específico.

Palavras-chave de número

• responsetime: o tempo que o servidor levou para enviar uma resposta.

• duration: duração total da solicitação, incluindo todas as chamadas subsequentes.

• http.status: código de status da resposta.

• index: posição de um elemento em uma lista enumerada.

• coverage: porcentagem decimal do tempo de resposta da entidade sobre o tempo de resposta do segmento raiz. Aplicável apenas para entidades de causa raiz de tempo de resposta.

Operadores de número

Palavras-chave de número usam operadores padrão de igualdade e comparação.

• =,!=: a palavra-chave é igual ou não a um valor numérico.

• <,<=, >,>=: a palavra-chave é menor ou maior do que um valor numérico.

exemplo Exemplo: o status de resposta não é 200 OK

http.status != 200

exemplo Exemplo: solicitação em que a duração total foi de 5 a 8 segundos

duration >= 5 AND duration <= 8

exemplo Exemplo: solicitações que foram concluídas com êxito em menos de 3 segundos, incluindo todas as chamadas subsequentes

ok !partial duration <3

exemplo Exemplo: entidade de lista enumerada que tem um índice maior que 5

rootcause.fault.service { index > 5 }

exemplo Exemplo: solicitações em que a última entidade tem cobertura superior a 0,8

rootcause.responsetime.entity { last and coverage > 0.8 }

Palavras-chave de string

Use palavras-chave de string para encontrar traços com texto específico nos cabeçalhos da solicitação ou em um usuário IDs específico.

Palavras-chave de string

• http.url— SolicitaçãoURL.

• http.method: método da solicitação.

• http.useragent: string do agente de usuário da solicitação.

• http.clientip: endereço IP do solicitante.

• user: valor do campo de usuário em qualquer segmento no rastreamento.

• name: o nome de um serviço ou exceção.

• type: tipo de serviço.

• message: mensagem de exceção.

• availabilityzone: valor do campo da zona de disponibilidade em qualquer segmento no rastreamento.

• instance.id: valor do campo de ID da instância em qualquer segmento no rastreamento.

• resource.arn— Valor do ARN campo de recurso em qualquer segmento no rastreamento.

Os operadores de string encontram valores que são iguais a ou contêm um texto específico. Os valores devem sempre ser especificados entre aspas.

Operadores de string

• =,!=: a palavra-chave é igual ou não a um valor numérico.

• CONTAINS: a palavra-chave contém uma string específica.

• BEGINSWITH,ENDSWITH: a palavra-chave começa ou termina com uma string específica.

exemplo Exemplo: filtro http.url

http.url CONTAINS "/api/game/"

Para testar se um campo existe em um rastreamento, independentemente do seu valor, verifique se ele contém a string vazia.

exemplo Exemplo: filtro do usuário

Encontre todos os rastros com o usuárioIDs.

user CONTAINS ""

exemplo Exemplo: selecionar rastreamentos com uma causa raiz de falha que inclua um serviço chamado "Auth"

rootcause.fault.service { name = "Auth" }

exemplo Exemplo: selecionar rastreamentos com uma causa raiz de tempo de resposta cujo último serviço tenha um tipo do DynamoDB

rootcause.responsetime.service { last and type = "AWS::DynamoDB" }

exemplo Exemplo: selecionar rastreamentos com uma causa raiz de falha cuja última exceção tenha a mensagem "Access Denied for account_id: 1234567890"

rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890" 

Palavras-chave complexas

Use palavras-chave complexas para encontrar solicitações com base no nome do serviço, no nome de borda ou no valor de anotação. Para serviços e bordas, você pode especificar uma expressão de filtro adicional que se aplica ao serviço ou borda. Para anotações, é possível filtrar pelo valor de uma anotação com uma chave específica usando operadores boolianos, de número ou de string.

Palavras-chave complexas

• annotation[key]— Valor de uma anotação com campo key. O valor de uma anotação pode ser booleano, número ou string, portanto, você pode usar qualquer um dos operadores de comparação desses tipos. É possível usar essa palavra-chave em combinação com as palavras-chave service ou edge. Uma chave de anotação que contém pontos (pontos) deve ser colocada entre colchetes ([]).

• edge(source, destination) {filter}— Conexão entre serviços source e destination. As chaves curvas opcionais podem conter uma expressão de filtro que se aplica aos segmentos nessa conexão.

• group.name / group.arn— O valor da expressão de filtro de um grupo, referenciado pelo nome do grupo ou grupoARN.

• json— objeto de causa JSON raiz. Consulte Obter dados do AWS X-Ray para ver as etapas para criar JSON entidades programaticamente.

• service(name) {filter}— Serviço com nome name. As chaves curvas opcionais podem conter uma expressão de filtro que se aplica aos segmentos criados pelo serviço.

Use a palavra-chave service para encontrar rastreamentos para solicitações que atingiram um determinado nó em seu mapa de rastreamento.

Os operadores complexos de palavras-chave encontram segmentos nos quais a chave especificada foi definida ou não.

Operadores de palavras-chave complexos

• none: a expressão é verdadeira se a palavra-chave for definida. Se a palavra-chave for do tipo booliano, ela será avaliada como o valor booliano.

• !: a expressão é verdadeira se a palavra-chave não for definida. Se a palavra-chave for do tipo booliano, ela será avaliada como o valor booliano.

• =,!=: compara o valor da palavra-chave.

• edge(source, destination) {filter}— Conexão entre serviços source e destination. As chaves curvas opcionais podem conter uma expressão de filtro que se aplica aos segmentos nessa conexão.

• annotation[key]— Valor de uma anotação com campo key. O valor de uma anotação pode ser booleano, número ou string, portanto, você pode usar qualquer um dos operadores de comparação desses tipos. É possível usar essa palavra-chave em combinação com as palavras-chave service ou edge.

• json— objeto de causa JSON raiz. Consulte Obter dados do AWS X-Ray para ver as etapas para criar JSON entidades programaticamente.

Use a palavra-chave service para encontrar rastreamentos para solicitações que atingiram um determinado nó em seu mapa de rastreamento.

exemplo Exemplo: filtro de serviço

Solicitações que incluem uma chamada para api.example.com com uma falha (erro da série 500).

service("api.example.com") { fault }

É possível excluir o nome do serviço para aplicar uma expressão de filtro para todos os nós no seu mapeamento de serviço.

exemplo Exemplo: filtro de serviço

Solicitações que causaram uma falha em qualquer lugar do seu mapa de rastreamento.

service() { fault }

A palavra-chave de borda aplica uma expressão de filtro a uma conexão entre dois nós.

exemplo Exemplo: filtro de borda

Solicitação em que o serviço api.example.com fez uma chamada para o backend.example.com que gerou um erro.

edge("api.example.com", "backend.example.com") { error }

Use também o operador ! com palavras-chave de serviço e borda para excluir um serviço ou borda dos resultados de outra expressão de filtro.

exemplo Exemplo: filtro de serviço e solicitação

Solicitação em que o URL começa com http://api.example.com/ e contém/v2/, mas não alcança um serviço chamadoapi.example.com.

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")

exemplo Exemplo: filtro de serviço e tempo de resposta

Encontre rastreamento em que http url está definido e o tempo de resposta é maior que 2 segundos.

http.url AND responseTime > 2

Para anotações, você pode chamar todos os rastreamentos em que annotation[key] está definido ou usar os operadores de comparação que correspondem ao tipo de valor.

exemplo Exemplo: anotação com valor de string

Solicitações com uma anotação chamada gameid com o valor de string "817DL6VO".

annotation[gameid] = "817DL6VO"

exemplo Exemplo: a anotação está definida

Solicitações com uma anotação definida como age.

annotation[age]

exemplo Exemplo: a anotação não está definida

Solicitações sem uma anotação definida como age.

!annotation[age]

exemplo Exemplo: anotação com valor numérico

Solicitações cuja idade de anotação tem um valor numérico maior do que 29.

annotation[age] > 29

exemplo Exemplo: anotação em combinação com serviço ou borda

service { annotation[request.id] = "917DL6VO" }

edge { source.annotation[request.id] = "916DL6VO" }

edge { destination.annotation[request.id] = "918DL6VO" }

exemplo Exemplo: grupo com usuário

Solicitações em que os rastreamentos atendem ao filtro de grupo high_response_time (por exemplo, responseTime > 3) e o usuário se chama Alice.

group.name = "high_response_time" AND user = "alice"

exemplo — JSON com entidade de causa raiz

Solicitações com entidades de causa raiz correspondentes.

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

Função id

Ao fornecer um nome de serviço para as palavras-chave service ou edge, você obtém resultados para todos os nós que têm esse nome. Para filtragem mais precisa, use a função id para especificar um tipo de serviço, além de um nome para distinguir os nós com o mesmo nome.

Use a função account.id para especificar uma conta específica para o serviço ao visualizar rastreamentos de várias contas em uma conta de monitoramento.

id(name: "service-name", type:"service::type", account.id:"account-ID")

Use a função id no lugar de um nome de serviço nos filtros de serviço e de borda.

service(id(name: "service-name", type:"service::type")) { filter }

edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

Por exemplo, AWS Lambda as funções resultam em dois nós no mapa de rastreamento; um para a invocação da função e outro para o serviço Lambda. Os dois nós têm o mesmo nome, mas tipos diferentes. Um filtro de serviço padrão encontrará rastreamentos para ambos.

exemplo Exemplo: filtro de serviço

As solicitações que incluem um erro em qualquer serviço chamado random-name.

service("function-name") { error }

Use a função id para restringir a pesquisa para erros na função em si, excluindo os erros do serviço.

exemplo Exemplo: filtro de serviço com a função id

Solicitações que incluem um erro em um serviço chamado random-name com tipo AWS::Lambda::Function.

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

Para procurar nós por tipo, também é possível excluir o nome inteiramente.

exemplo Exemplo: filtro de serviço com função id e tipo de serviço

Solicitações que incluem um erro em um serviço com o tipo AWS::Lambda::Function.

service(id(type: "AWS::Lambda::Function")) { error }

Para pesquisar nós para um determinado Conta da AWS, especifique um ID de conta.

exemplo Exemplo: filtro de serviço com a função id e o ID da conta

Solicitações que incluem um serviço dentro de um ID de conta AWS::Lambda::Function específico.

service(id(account.id: "account-id"))