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.

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.

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.

responsetime > 5

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

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.

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

ok

!ok

ok = false

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

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

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

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.

http.status != 200

duration >= 5 AND duration <= 8

ok !partial duration <3

rootcause.fault.service { index > 5 }

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.

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.

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.

user CONTAINS ""

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

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

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.

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.

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

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.

service() { fault }

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

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.

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

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.

annotation[gameid] = "817DL6VO"

annotation[age]

!annotation[age]

annotation[age] > 29

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

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

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

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

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.

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.

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

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

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

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

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