Implementando o rastreamento com X-Ray
Monitoramento e Solução de Problemas na AWS
John Q. Martin
Principal Consultant
Visão geral do X-Ray SDK
Pontos-chave:
- Linguagens compatíveis: Python, Node.js, Java, .NET, Go, Ruby
- Duas abordagens: instrumentação automática e manual
- SDK se comunica com o daemon na porta UDP 2000
- Nunca fala direto com a API do X-Ray
Automática vs. Manual:
SDK Python: configuração no Flask
from flask import Flask
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(
service='MyFlaskApp',
sampling=True,
context_missing='LOG_ERROR',
daemon_address='127.0.0.1:2000'
)
XRayMiddleware(app, xray_recorder)
Quatro configurações do recorder:
- service - nome exibido no mapa de serviços
- sampling - ativa/desativa amostragem
- context_missing - LOG_ERROR evita falhas
- daemon_address - para onde enviar segmentos
Após anexar o middleware, todas as requisições de entrada são rastreadas automaticamente.
Instrumentação automática: Python
# Instrumentar todas as bibliotecas compatíveis
from aws_xray_sdk.core import patch_all
patch_all()
# Ou selecionar
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Bibliotecas compatíveis:
Instrumentação manual: Python
Abordagem com decorator:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Abordagem com context manager:
def process_order(order_id):
with xray_recorder.capture('fetch_order'):
order = db.query(Order).filter_by(
id=order_id).first()
with xray_recorder.capture('process_payment'):
return payment_service.charge(order.total)
Anotações e metadados no código
Adicionando anotações:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Adicionando metadados (contexto detalhado):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Anotações são indexadas; metadados não
- Anotações são tipadas; metadados podem ser qualquer JSON
- Use índices para filtrar e metadados para depuração
Tratamento de erros nos traces
def process_order(order_id):
try:
order = get_order(order_id)
payment = process_payment(order)
return payment
except PaymentError as e:
xray_recorder.put_annotation(
'error_type', 'payment_failed')
xray_recorder.put_metadata(
'error_details',
{'message': str(e), 'order_id': order_id})
raise
- Exceções em funções rastreadas são capturadas automaticamente
- Adicione uma anotação com o tipo de erro para filtrar no console
- Adicione metadados com os detalhes completos do erro
- Sempre relance; o tratamento de erro da sua aplicação ainda precisa rodar
SDK Node.js: configuração no Express
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Segmento aberto para todas as requisições
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Fecha o segmento após a resposta
app.use(xrayExpress.closeSegment());
// Instrumentação automática
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Implementação no Lambda
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # instrumenta chamadas do AWS SDK
def lambda_handler(event, context):
xray_recorder.put_annotation(
'user_id', event['user_id'])
result = process_user(event['user_id'])
return {
'statusCode': 200,
'body': json.dumps(result)
}
Pontos-chave:
- Lambda envia traces básicos automaticamente com Active Tracing habilitado; não precisa de SDK para isso
- Instale o X-Ray SDK para adicionar subsegmentos, anotações e instrumentar chamadas downstream
- Habilite no console: Configuration → Monitoring tools
- Ou no template:
Tracing: Active
ECS e Fargate: padrão sidecar
Estrutura da task:
ECS Task
|_ Application Container
| envia para xray-daemon:2000
|_ X-Ray Daemon Container
encaminha para o serviço X-Ray
Config do container da app:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
A definição da task inclui:
- Container do daemon: imagem
amazon/aws-xray-daemon, porta UDP 2000 - Container da app: var de ambiente
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Por que sidecar?
- Daemon escala com suas tasks
- Falhas ficam isoladas por task
Instalando o daemon do X-Ray
Instalação por plataforma:
- Amazon Linux 2
- sudo yum install -y aws-xray-daemon-3.x.rpm
- Ubuntu
- sudo dpkg -i aws-xray-daemon-3.x.deb
- Windows
- xray.exe -f cfg.yaml install
- Docker
- docker run -p 2000:2000/udp amazon/aws-xray-daemon
Pós-instalação:
sudo systemctl start xray
sudo systemctl enable xray
O que o daemon faz:
- Escuta na porta UDP 2000
- Faz buffer e agrupa segmentos
- Encaminha para a API do X-Ray via HTTPS
- Lida com tentativas; sua app não precisa
Configuração do daemon
TotalBufferSizeMB: 24
Concurrency: 8
Region: "us-east-1"
Socket:
UDPAddress: "127.0.0.1:2000"
TCPAddress: "127.0.0.1:2000"
Logging:
LogLevel: "info"
LogPath: "/var/log/xray/xray-daemon.log"
LocalMode: false
- Tamanho do buffer; aumente para alto tráfego
- Concurrency define conexões paralelas com o X-Ray
- Em containers, defina o endereço UDP como 0.0.0.0
- Local mode: true para dev local sem credenciais
Permissões IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Abordagem mais fácil
Use a política gerenciada AWSXRayDaemonWriteAccess
Anexe a:
- Função da instância EC2
- Função da task ECS
- Função de execução do Lambda
Sem as permissões corretas, o daemon roda, mas falha silenciosamente ao enviar segmentos.
Padrões de implantação do daemon
Resumo da lição
- SDK: instrumentação automática com
patch_all(), manual com decorators e context managers - Anotações (indexadas, pesquisáveis) vs. metadados (detalhados, não indexados)
- Lambda: envia traces básicos automaticamente; instale o SDK para subsegmentos e chamadas downstream
- ECS/Fargate: padrão de container sidecar para o daemon
- Daemon: configurado via cfg.yaml; precisa da política IAM
AWSXRayDaemonWriteAccess - Implantação: por instância no EC2; sidecar em containers
Implementando o rastreamento com X-Ray
Monitoramento e Solução de Problemas na AWS
