Implementarea trasării X-Ray
Monitorizare și depanare în AWS
John Q. Martin
Principal Consultant
Prezentare generală a SDK-ului X-Ray
Date esențiale:
- Limbaje acceptate: Python, Node.js, Java, .NET, Go, Ruby
- Două abordări: instrumentare automată și manuală
- SDK-ul comunică cu daemonul prin UDP pe portul 2000
- Nu comunică direct cu API-ul X-Ray
Automată vs. manuală:
SDK Python: configurare 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)
Patru setări ale recorderului:
- service - numele afișat în harta serviciilor
- sampling - activează/dezactivează eșantionarea
- context_missing - LOG_ERROR previne blocajele
- daemon_address - destinația segmentelor
Odată atașat middleware-ul, toate cererile primite sunt trasate automat.
Instrumentare automată: Python
# Instrument all supported libraries
from aws_xray_sdk.core import patch_all
patch_all()
# Or selectively
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Biblioteci acceptate:
Instrumentare manuală: Python
Abordarea cu decorator:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Abordarea cu 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)
Adnotări și metadate în cod
Adăugare adnotări:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Adăugare metadate (context detaliat):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Adnotările sunt indexate, metadatele nu
- Adnotările sunt tipizate, metadatele acceptă orice JSON
- Folosește indexurile pentru filtrare, metadatele pentru depanare
Gestionarea erorilor în trasări
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
- Excepțiile din funcțiile trasate sunt capturate automat
- Adaugă o adnotare pentru tipul de eroare, ca să poți filtra în consolă
- Adaugă metadate pentru detaliile complete ale erorii
- Reruncă întotdeauna excepția — gestionarea erorilor aplicației trebuie să ruleze în continuare
SDK Node.js: configurare Express
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Open segment for all incoming requests
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Close segment after response
app.use(xrayExpress.closeSegment());
// Automatic instrumentation
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Implementare Lambda
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # instrument AWS SDK calls
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)
}
Date esențiale:
- Lambda trimite trasări de bază automat când Active Tracing este activat, fără SDK
- Instalează SDK-ul X-Ray pentru a adăuga subsegmente, adnotări și a instrumenta apelurile downstream
- Activare din consolă: Configuration → Monitoring tools
- Sau în șablon:
Tracing: Active
ECS și Fargate: pattern sidecar
Structura unui task:
ECS Task
|_ Application Container
| sends to xray-daemon:2000
|_ X-Ray Daemon Container
forwards to X-Ray service
Configurare container aplicație:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Definiția taskului include:
- Containerul daemon: imaginea
amazon/aws-xray-daemon, portul UDP 2000 - Containerul aplicației: variabila de mediu
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
De ce sidecar?
- Daemonul scalează odată cu taskurile
- Erorile sunt izolate per task
Instalarea daemonului X-Ray
Instalare după platformă:
- 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
După instalare:
sudo systemctl start xray
sudo systemctl enable xray
Ce face daemonul:
- Ascultă pe portul UDP 2000
- Buferizează și grupează segmentele
- Le trimite la API-ul X-Ray prin HTTPS
- Gestionează reîncercările — aplicația ta nu trebuie să se ocupe de asta
Configurarea daemonului
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
- Dimensiunea bufferului – mărește-o pentru trafic ridicat
- Concurrency stabilește conexiunile paralele către X-Ray
- Pentru containere, setează adresa UDP la 0.0.0.0
- Local mode – activează-l pentru dezvoltare locală fără credențiale
Permisiuni IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Cea mai simplă abordare
Folosește politica gestionată AWSXRayDaemonWriteAccess
Atașeaz-o la:
- Rolul instanței EC2
- Rolul taskului ECS
- Rolul de execuție Lambda
Fără permisiunile corecte, daemonul rulează, dar segmentele nu sunt livrate — fără nicio eroare vizibilă.
Pattern-uri de deployment ale daemonului
Rezumatul lecției
- SDK: instrumentare automată cu
patch_all(), manuală cu decoratori și context manageri - Adnotări (indexate, căutabile) vs. metadate (detaliate, neindexate)
- Lambda: trimite trasări de bază automat; instalează SDK-ul pentru subsegmente și apeluri downstream
- ECS/Fargate: pattern cu container daemon sidecar
- Daemon: configurat prin cfg.yaml, necesită politica IAM
AWSXRayDaemonWriteAccess - Deployment: per instanță pentru EC2, sidecar pentru containere
Implementarea trasării X-Ray
Monitorizare și depanare în AWS
