AWS X-Ray conceitos

AWS X-Ray recebe dados de serviços como segmentos. Em seguida, o X-Ray agrupa segmentos que tenham uma solicitação em comum em rastreamentos. O X-Ray processa os rastreamentos para gerar um gráfico de serviço que apresenta uma representação visual da aplicação.

Segmentos

Os recursos de computação que executam a lógica do aplicativo enviam dados sobre o trabalho como segmentos. Um segmento fornece o nome do recurso, os detalhes sobre a solicitação e os detalhes sobre o trabalho realizado. Por exemplo, quando alcança o aplicativo, uma solicitação HTTP pode registrar os seguintes dados sobre:

O X-Ray SDK reúne informações dos cabeçalhos de solicitação e resposta, do código do seu aplicativo e dos metadados sobre os AWS recursos nos quais ele é executado. Você escolhe os dados a serem coletados modificando a configuração ou o código do aplicativo para instrumentar solicitações recebidas, solicitações downstream e AWS clientes SDK.

Você pode usar o X-Ray SDK para registrar informações adicionais, como anotações e metadados. Para obter mais detalhes sobre a estrutura e informações registradas em segmentos e subsegmentos, consulte AWS X-Ray documentos do segmento. Os documentos de segmentos podem ter até 64 kB de tamanho.

Subsegmentos

Um segmento pode dividir os dados sobre o trabalho feito em subsegmentos. Os subsegmentos fornecem informações de tempo mais granulares e detalhes sobre chamadas de downstream feitas pelo aplicativo para atender à solicitação original. Um subsegmento pode conter detalhes adicionais sobre uma chamada para um AWS service (Serviço da AWS), uma API HTTP externa ou um banco de dados SQL. Você pode até mesmo definir subsegmentos arbitrários para instrumentar funções ou linhas de código específicas em seu aplicativo.

Para serviços que não enviam seus próprios segmentos, como o Amazon DynamoDB, o X-Ray usa subsegmentos para gerar segmentos inferidos e nós downstream no mapa de rastreamento. Isso permite que você veja todas as suas dependências downstream, mesmo que elas não ofereçam suporte a rastreamento ou sejam externas.

Os subsegmentos representam a visualização de seu aplicativo de uma chamada downstream como um cliente. Se o serviço downstream também for instrumentado, o segmento que ele envia substitui o segmento deduzido gerado no subsegmento do cliente upstream. O nó no gráfico do serviço sempre usa informações do segmento do serviço, se disponíveis, enquanto a borda entre os dois nós usa o subsegmento do serviço upstream.

Por exemplo, quando você chama o DynamoDB com um cliente SDK AWS instrumentado, o X-Ray SDK registra um subsegmento dessa chamada. O DynamoDB não envia um segmento, de modo que o segmento inferido no rastreamento, o nó do DynamoDB no gráfico de serviço e a borda entre o serviço e o DynamoDB contêm informações do subsegmento.

Quando você chama outro serviço instrumentado com um aplicativo instrumentado, o serviço downstream envia seu próprio segmento para gravar sua visualizado da mesma chamada que o serviço upstream gravou em um segmento. No gráfico do serviço, os dois nós de serviço contêm o tempo e as informações de erro dos segmentos desses serviços, enquanto a borda entre eles contém informações do subsegmento do serviço upstream.

Os dois pontos de vista são úteis, uma vez que o serviço downstream grava precisamente quando iniciou e terminou o trabalho na solicitação, e o serviço upstream grava a latência da viagem de ida e volta, incluindo o tempo que a solicitação gastou viajando entre os dois serviços.

Gráfico de serviço

O X-Ray usa os dados que a aplicação envia para gerar um gráfico de serviço. Cada AWS recurso que envia dados para o X-Ray aparece como um serviço no gráfico. Margens conectam os serviços que funcionam juntos para atender a solicitações. Margens conectam clientes ao aplicativo e o aplicativo a serviços e recursos de downstream usados por ele.

Gráfico de serviço é um documento JSON que contém informações sobre os serviços e os recursos que compõem o aplicativo. O console do X-Ray usa o gráfico de serviço para gerar uma visualização ou um mapa de serviço.

Para um aplicação distribuído, o X-Ray combina nós de todos os serviços que processam solicitações com a mesma ID de rastreamento em um único gráfico de serviço. O primeiro serviço adicionado pela solicitação inclui um cabeçalho de rastreamento propagado entre o front-end e os serviços chamados.

Por exemplo, o Scorekeep executa uma API da web que chama um microsserviço (uma função do AWS Lambda ) para gerar um nome aleatório usando uma biblioteca Node.js. O X-Ray SDK para Java gera um ID de rastreamento e o inclui em chamadas para o Lambda. O Lambda envia dados de rastreamento e passa o ID de rastreamento para a função. O X-Ray SDK para Node.js também usa o ID de rastreamento para enviar dados. Como resultado, todos os nós da API, do serviço Lambda e da função Lambda aparecem como nós separados, mas conectados, no mapa de rastreamento.

O gráfico de serviço é retido por trinta dias.

Rastreamentos

Uma ID de rastreamento acompanha o caminho de uma solicitação pelo aplicativo. Um rastreamento coleta todos os segmentos gerados por uma única solicitação. Essa solicitação costuma ser uma solicitação HTTP GET ou POST que percorre um balanceador de carga, chega ao código da aplicação e gera chamadas subsequentes para outros serviços da AWS ou APIs da web externas. O primeiro serviço compatível com o qual a solicitação HTTP interage adiciona um cabeçalho de ID de rastreamento à solicitação e o propaga downstream para rastrear a latência, a disposição e outros dados de solicitação.

Consulte os Preços do AWS X-Ray para obter informações sobre como os rastreamentos do X-Ray são cobrados. Os dados de rastreamento são retidos por trinta dias.

Amostragem

Para garantir um rastreamento eficiente e fornecer uma amostra representativa das solicitações atendidas pela aplicação, o X-Ray SDK aplica um algoritmo de amostragem para determinar quais solicitações são rastreadas. O padrão é registrar a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais.

Para evitar cobranças incorridas para o serviço quando você está começando a usá-lo, a taxa de amostragem padrão é conservadora. Você pode configurar o X-Ray para modificar a regra de amostragem padrão e configurar regras adicionais que aplicam a amostragem com base nas propriedades do serviço ou da solicitação.

Por exemplo, pode ser conveniente desabilitar a amostragem e rastrear todas as solicitações para chamadas que modificam um estado ou lidam com usuários ou transações. Para chamadas de somente leitura de alto volume, como a sondagem de plano de fundo, as verificações de integridade ou a manutenção da conexão, você pode coletar amostras a uma taxa baixa e ainda obter dados suficientes para ver qualquer problema que surja.

Para ter mais informações, consulte Configurar regras de amostragem.

Cabeçalho de rastreamento

Todas as solicitações são rastreadas até um mínimo configurável. Após atingir esse mínimo, uma porcentagem de solicitações será rastreada para evitar custos desnecessários. A ID de rastreamento e a decisão de amostragem são adicionadas a solicitações HTTP em cabeçalhos de rastreamento chamados X-Amzn-Trace-Id. O primeiro serviço integrado do X-Ray atingido pela solicitação adiciona um cabeçalho de rastreamento, que é lido pelo X-Ray SDK e incluído na resposta.

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1

O cabeçalho de rastreamento também podem conter um ID de segmento pai se a solicitação tiver se originado de um aplicativo instrumentado. Por exemplo, se sua aplicação chamar uma API da web HTTP subsequente com um cliente HTTP instrumentado, o X-Ray SDK adicionará o ID do segmento da solicitação original ao cabeçalho de rastreamento da solicitação subsequente. Um aplicativo instrumentado que atende a solicitação de downstream pode registrar o ID de segmento pai para conectar as duas solicitações.

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1

Lineagepodem ser anexados ao cabeçalho de rastreamento pelo Lambda e Serviços da AWS outros como parte de seus mecanismos de processamento e não devem ser usados diretamente.

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1;Lineage=a87bd80c:1|68fd508a:5|c512fbe3:2

Expressões de filtro

Mesmo com amostragem, um aplicativo complexo gera uma grande quantidade de dados. O AWS X-Ray console fornece uma easy-to-navigate visão do gráfico do serviço. Ele mostra informações de integridade e desempenho que ajudam a identificar problemas e oportunidades de otimização no seu aplicativo. Para o rastreamento avançado, você pode analisar rastreamentos de solicitações individuais, ou usar expressões de filtro para encontrar rastreamentos relacionados a caminhos ou usuários específicos.

Grupos

Com a extensão de expressões de filtro, o X-Ray também comporta o recurso de grupo. Ao usar uma expressão de filtro, você pode definir critérios para aceitar rastreamentos no grupo.

Você pode chamar o grupo pelo nome ou pelo nome de recurso da Amazon (ARN) para gerar seu próprio gráfico de serviços, resumos de rastreamento e métricas da Amazon. CloudWatch Assim que um grupo é criado, os rastreamentos recebidos são verificados em relação à expressão de filtro do grupo, pois são armazenados no serviço X-Ray. As métricas do número de rastreamentos que correspondem a cada critério são publicadas a CloudWatch cada minuto.

Atualizar a expressão de filtro de um grupo não altera os dados que já estão registrados. A atualização se aplica somente aos rastreamentos subsequentes. Isso pode resultar em um gráfico mesclado das expressões novas e antigas. Para evitar isso, exclua o grupo atual e crie um novo.

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

Anotações e metadados

Quando você instrumenta seu aplicativo, o X-Ray SDK registra informações sobre solicitações de entrada e saída, os AWS recursos usados e o próprio aplicativo. É possível adicionar outras informações ao segmento documentado como anotações e metadados. Anotações e metadados são agregados no nível de rastreamento e podem ser adicionados a qualquer segmento ou subsegmento.

Anotações são pares de chave-valor simples indexados para serem usados com expressões de filtro. Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API GetTraceSummaries.

O X-Ray indexa até cinquenta anotações por rastreamento.

Metadados são pares de chave-valor com valores de qualquer tipo, inclusive objetos e listas, mas que não são indexados. Use metadados para registrar dados que você deseja armazenar no rastreamento, mas não precisa usar para pesquisar rastreamentos.

Você pode visualizar anotações e metadados na janela de detalhes do segmento ou subsegmento, na página de detalhes do Trace no console. CloudWatch

Erros, falhas e exceções

O X-Ray rastreia erros que ocorrem no código da aplicação e erros retornados por serviços subsequentes. Os erros são categorizados da seguinte forma.

Quando ocorre uma exceção enquanto a aplicação está atendendo a uma solicitação, o X-Ray SDK registra os detalhes da exceção, incluindo o rastreamento da pilha, se disponível. Você pode visualizar exceções em Detalhes do segmento no console do X-Ray.