Mettre en œuvre la traçabilité X-Ray
Surveillance et dépannage sur AWS
John Q. Martin
Principal Consultant
Aperçu du SDK X-Ray
Faits clés :
- Langages pris en charge : Python, Node.js, Java, .NET, Go, Ruby
- Deux approches : instrumentation automatique et manuelle
- Le SDK communique avec le démon sur le port UDP 2000
- Ne parle jamais directement à l'API X-Ray
Automatique vs manuel :
SDK Python : configuration 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)
Quatre paramètres du recorder :
- service – nom affiché dans la carte des services
- sampling – activer/désactiver l'échantillonnage
- context_missing – LOG_ERROR évite les plantages
- daemon_address – destination des segments
Une fois le middleware ajouté, toutes les requêtes entrantes sont tracées automatiquement.
Instrumentation automatique : Python
# Instrumenter toutes les bibliothèques prises en charge
from aws_xray_sdk.core import patch_all
patch_all()
# Ou sélectionner
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Bibliothèques prises en charge :
Instrumentation manuelle : Python
Approche avec décorateur :
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Approche avec gestionnaire de contexte :
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)
Annotations et métadonnées dans le code
Ajouter des annotations :
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Ajouter des métadonnées (contexte détaillé) :
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Les annotations sont indexées, pas les métadonnées
- Les annotations sont typées, les métadonnées sont n'importe quel JSON
- Utilisez les index pour filtrer, les métadonnées pour le débogage
Gestion des erreurs dans les 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
- Les exceptions dans les fonctions tracées sont capturées automatiquement
- Ajoutez une annotation pour le type d'erreur afin de filtrer dans la console
- Ajoutez des métadonnées pour tous les détails de l'erreur
- Relancez toujours l'exception ; la gestion d'erreurs de votre application doit quand même s'exécuter
SDK Node.js : configuration Express
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Ouvrir un segment pour toutes les requêtes entrantes
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Fermer le segment après la réponse
app.use(xrayExpress.closeSegment());
// Instrumentation automatique
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Implantation Lambda
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # instrumenter les appels au SDK AWS
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)
}
Faits clés :
- Lambda envoie des traces de base automatiquement quand Active Tracing est activé ; aucun SDK requis pour cela
- Installez le SDK X-Ray pour ajouter des sous-segments, des annotations et instrumenter les appels en aval
- Activer dans la console : Configuration → Outils de surveillance
- Ou dans le modèle :
Tracing: Active
ECS et Fargate : modèle sidecar
Structure de la tâche :
Tâche ECS
|_ Conteneur d'application
| envoie à xray-daemon:2000
|_ Conteneur du démon X-Ray
transfère au service X-Ray
Configuration du conteneur d'app :
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
La définition de tâche inclut :
- Conteneur du démon : image
amazon/aws-xray-daemon, port UDP 2000 - Conteneur app : variable d'env.
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Pourquoi un sidecar ?
- Le démon s'adapte à vos tâches
- Les pannes sont isolées par tâche
Installer le démon X-Ray
Installation par plateforme :
- 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
Après l'installation :
sudo systemctl start xray
sudo systemctl enable xray
Rôle du démon :
- Écoute sur le port UDP 2000
- Met en mémoire tampon et regroupe les segments
- Transfère à l'API X-Ray via HTTPS
- Gère les reprises ; votre app n'a pas à le faire
Configuration du démon
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
- Taille du tampon ; augmenter pour un trafic élevé
- Concurrency définit les connexions parallèles à X-Ray
- Pour les conteneurs, définir l'adresse UDP à 0.0.0.0
- Mode local : true pour le dev local sans justificatifs
Autorisations IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Approche la plus simple
Utilisez la stratégie gérée AWSXRayDaemonWriteAccess
À attacher à :
- Rôle d'instance EC2
- Rôle de tâche ECS
- Rôle d'exécution Lambda
Sans les permissions adéquates, le démon s'exécute mais échoue en silence à livrer les segments.
Modèles de déploiement du démon
Résumé de la leçon
- SDK : instrumentation automatique avec
patch_all(), manuelle avec décorateurs et gestionnaires de contexte - Annotations (indexées, recherchables) vs métadonnées (détaillées, non indexées)
- Lambda : envoie des traces de base automatiquement ; installez le SDK pour les sous-segments et les appels en aval
- ECS/Fargate : modèle de conteneur démon sidecar
- Démon : configuré via cfg.yaml, nécessite la stratégie IAM
AWSXRayDaemonWriteAccess - Déploiement : par instance pour EC2, sidecar pour les conteneurs
Mettre en œuvre la traçabilité X-Ray
Surveillance et dépannage sur AWS
