Conceitos e arquitetura do X-Ray

Monitoramento e Solução de Problemas na AWS

John Q. Martin

Principal Consultant

O desafio de sistemas distribuídos

Aplicativo monolítico

Fluxo linear, em um único processo
Fácil de depurar

Aplicativo distribuído

Uma requisição passa por vários serviços, BDs e APIs externas
Se falhar, qual serviço causou?

Um grande nó emaranhado de fios coloridos, mostrando a dificuldade de rastrear uma requisição em um sistema distribuído

O que é o AWS X-Ray?

X-Ray é um serviço de tracing distribuído que:

Rastreia requisições fim a fim entre serviços
Mede latência e detecta erros em cada etapa
Visualiza a arquitetura como um mapa de serviços

Exemplo de caminho da requisição:

Diagrama de uma requisição fluindo por vários serviços em um trace distribuído

Cinco capacidades principais

Cinco capacidades do X-Ray: rastreamento de requisições, análise de performance, detecção de erros, mapa de serviços e insights

Como o tracing funciona

Fluxo de tracing distribuído: uma requisição entra no Serviço A, que chama B e depois C, passando o Trace ID no cabeçalho HTTP; cada serviço emite um segmento com o mesmo Trace ID para o daemon do X-Ray, que encaminha ao X-Ray, onde tudo é montado em um único trace completo

Propagação do Trace ID e do cabeçalho

Formato do Trace ID:

Formato do Trace ID do X-Ray com número da versão, timestamp Unix em hex e identificador único

Cabeçalho HTTP:

X-Amzn-Trace-Id:
  Root=1-5e8c1234-...;
  Parent=abc123;
  Sampled=1

Root, Trace ID, igual em todos os serviços
Parent, ID do segmento upstream
Sampled, 0 ou 1, rastreado ou ignorado

O daemon do X-Ray

O que faz:

Escuta na porta UDP 2000
Recebe dados de segmentos do seu app
Faz buffer, agrupa e envia à API do X-Ray
Desacopla seu app do serviço X-Ray

Implantação por ambiente:

Implantação do daemon do X-Ray por ambiente: automática no Lambda, um serviço no EC2 e sidecar no ECS

Amostragem

Regra padrão:

Primeira requisição por segundo: sempre rastreada
5% das demais requisições: amostradas

Campos de regra customizada:

fixed_target - req/s sempre rastreadas
rate - porcentagem das demais requisições
priority - menor número vence

Estratégia de exemplo:

Regra 1 (prioridade 1):
  Erros 5xx -> 100% de amostragem

Regra 2 (prioridade 10):
  Tráfego normal -> 5% de amostragem

Segmentos

O que um segmento registra:

Nome do serviço
Hora de início e fim
Trace ID
Detalhes da requisição e resposta HTTP
Conta e região da AWS

Estados de segmento:

Cinco estados de segmento do X-Ray: em progresso, ok, erro, falha e throttle

Subsegmentos

Comparação de timeline: sem subsegmentos uma barra única de 800ms; com subsegmentos os mesmos 800ms divididos em DynamoDB 50ms, PaymentService 400ms destacado como gargalo e InventoryService 300ms

O que os subsegmentos fazem:

Dão tempo detalhado dentro de um segmento
Acompanham chamadas downstream
Transformam 800ms em:
- DynamoDB.PutItem: 50ms
- Chamada ao PaymentService: 400ms
- Chamada ao InventoryService: 300ms

Namespaces:

Três namespaces de subsegmentos: aws para chamadas AWS, remote para HTTP externo e local para código customizado

Annotations

Pontos-chave:

Pares chave-valor indexados - pesquisáveis e filtráveis
Limite: 50 indexados por trace
Tipos: string, number, boolean

Use para:

user_id, order_id, environment
version, feature flags, error codes

Sintaxe de filtro:

annotation.user_id = "user-123"

annotation.environment = "production"
AND annotation.version = "1.2.3"

Metadata

Pontos-chave:

Não indexado - não dá para pesquisar ou filtrar
Sem limite de tamanho
Aceita qualquer estrutura JSON

Use para:

Corpos completos de requisição e resposta
Mensagens de erro e stack traces
Contexto de negócio (itens do pedido, endereços)

Annotations vs. Metadata:

Tabela comparativa de annotations (indexadas e pesquisáveis) versus metadata (detalhada e não indexada)

Estrutura completa do trace

Estrutura completa de um trace com quatro segmentos e a API externa de pagamento como a operação mais lenta

Resumo da lição

X-Ray - serviço de tracing distribuído para visibilidade fim a fim entre serviços
Mecanismo de tracing - propagação do Trace ID via cabeçalhos HTTP, segmentos coletados pelo daemon, regras de amostragem configuráveis
Componentes do trace:
- Segments - registros de trabalho em nível de serviço
- Subsegments - tempo detalhado de operações downstream
- Annotations - pares chave-valor indexados para filtro e busca
- Metadata - contexto detalhado, não indexado

Vamos praticar!

Monitoramento e Solução de Problemas na AWS