X-Ray: tracing distribuído na AWS
⏱ 10 min·⭐ 45 XP
Pré-requisitos (0/1)0%
- ⬜🚀 CI/CD AWS-nativo: CodeBuild, CodeDeploy e CodePipeline(AWS Developer Associate (DVA-C02))
Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.
Integração
- Lambda: Active tracing checkbox, sem código extra pro entrypoint. Pra subsegments custom, SDK.
- API Gateway: X-Ray checkbox em stage. Propaga trace_id pros downstreams via header.
- ECS/EC2: X-Ray daemon sidecar.
- SDK: auto-instrumenta http, aws-sdk. Segment custom pra bloco crítico.
Entrada
RequisiçãoX-Amzn-Trace-Id gerado aqui
API Gatewayprimeiro segment
Serviço AVPC
Lambda de pedidossegment próprio
DynamoDBsubsegment: 12ms
Serviço BVPC
Lambda de cobrançasegment próprio
API externasubsegment: 840ms ← o gargalo
Coleta
Daemon / SDKenvia segments
X-Raymonta o service map
- → trace id
- → propaga o MESMO id
- → subsegment
- → propaga o id
- → subsegment lento
- → agrega por trace id
- Fora da AWS
- Rede e entrega
- Compute
- Banco de dados
- Gestão e governança
O valor do X-Ray não é o log: é conseguir dizer, numa requisição que atravessou quatro serviços, exatamente qual chamada consumiu o tempo. Sem propagação do trace id, isso não existe.
- O trace id nasce na borda e é propagado. O cabeçalho X-Amzn-Trace-Id acompanha a requisição por todos os serviços. É ele que permite juntar pedaços de execuções diferentes numa história só. Serviço que não propaga quebra a corrente.
- Segment é o serviço, subsegment é a chamada. Cada serviço emite um segment; dentro dele, cada chamada externa (banco, HTTP, SDK) é um subsegment com seu próprio tempo. É essa granularidade que localiza o gargalo.
- O gargalo aparece sozinho. Neste trace, o DynamoDB levou 12ms e a API externa 840ms. Sem trace distribuído você só sabia que "o endpoint está lento" — com ele, você sabe qual chamada, em qual serviço.
- Sampling é o que torna viável. Rastrear 100% em alta escala é caro. A regra padrão pega o primeiro por segundo mais um percentual do resto — o suficiente para estatística, sem custo proibitivo. Regra customizada permite 100% em rota crítica.
- Annotation vs metadata. Annotation é indexada e serve para filtrar traces (por customerId, por exemplo). Metadata não é indexada, só aparece no detalhe. Buscar por metadata não funciona — e é confusão comum na prova.
from aws_xray_sdk.core import patch_all, xray_recorder
# Um patch instrumenta boto3, requests e drivers de banco de uma vez.
patch_all()
@xray_recorder.capture("processar_pedido")
def processar(pedido):
seg = xray_recorder.current_subsegment()
# ANOTAÇÃO é indexada e pesquisável: use no que você vai FILTRAR.
# Limite de 50 por rastro — reserve para dimensão, não para conteúdo.
seg.put_annotation("cliente_tipo", pedido["tipo"])
seg.put_annotation("regiao", pedido["regiao"])
# METADADO não é indexado e não tem esse limite: use para contexto de
# depuração. Trocar os dois é o erro que faz o filtro do console não achar nada.
seg.put_metadata("payload", pedido)
with xray_recorder.in_subsegment("cobranca-externa"):
chamar_gateway_de_pagamento(pedido)
# Filtro no console, que só funciona por causa das anotações acima:
# annotation.cliente_tipo = "premium" AND responsetime > 3Onde isso entra no exame
📘 Domain 4 — Troubleshooting and Optimization· 18%
Domain 4 é o menor, mas concentrado: dado um sintoma, qual sinal usar. X-Ray para achar o salto lento entre serviços, Logs Insights para agregar evento, métrica via EMF para o que a AWS não emite. Saiba que o SDK precisa do daemon (ou da integração gerenciada no Lambda) para enviar segmento — sem isso o trace simplesmente não aparece.
Quiz rápido
Uma requisição atravessa API Gateway, duas Lambdas e o DynamoDB. Para ver o tempo de cada trecho num único trace, o que é necessário?
Sampling
💡
Rules: reservoir (N traces/segundo garantidos) + fixed rate (%) do excedente. Ex: "reservoir 1/s, fixed 5%". Custom rules por URL/service. Pra debug: 100% em staging; em prod use padrão.
Perguntas frequentes
❓ O que rastreamento distribuído mostra que registro não mostra?
A relação entre as chamadas: onde o tempo foi gasto em cada serviço da mesma requisição. Registro solto responde "o que aconteceu aqui"; o rastro responde "por que esta requisição demorou". Sem identificador correlacionando, reconstruir isso a partir de registro é arqueologia.
❓ O que é amostragem e por que ela existe?
É rastrear uma fração das requisições em vez de todas, para conter custo e sobrecarga. A regra padrão costuma pegar as primeiras por segundo e uma porcentagem do resto. O cuidado é que erro raro pode não ser amostrado — e é por isso que se configura regra específica para capturar sempre o que falha.
❓ Rastro por si resolve diagnóstico?
Não sem contexto de negócio anexado: identificador do usuário, do recurso, do fluxo. Rastro que mostra "esta chamada demorou 800 ms" sem dizer de quem e de quê aponta o sintoma e não permite reproduzir. Anotação no trecho é o que transforma rastro em investigação.
Fixando
Quiz rápido
Qual é a diferença entre annotation e metadata no X-Ray?
Quiz rápido
Por que o sampling é essencial no X-Ray em produção?
Terminou de ler?
Marcar como concluído registra o XP, mantém sua sequência e coloca 3 cartas deste módulo na fila de revisão espaçada.
Próximos passos sugeridos
Temas deste módulo
Discussão
Carregando comentários…