Implementace trasování X-Ray
Monitoring and Troubleshooting AWS
John Q. Martin
Principal Consultant
Přehled X-Ray SDK
Klíčové informace:
- Podporované jazyky: Python, Node.js, Java, .NET, Go, Ruby
- Dva přístupy: automatická a manuální instrumentace
- SDK komunikuje s daemonem přes UDP port 2000
- Nikdy nekomunikuje přímo s X-Ray API
Automatická vs. manuální:
Python SDK: nastavení 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)
Čtyři nastavení recorderu:
- service – název zobrazený v mapě služeb
- sampling – zapnutí/vypnutí vzorkování
- context_missing – LOG_ERROR zabraňuje pádům
- daemon_address – kam odesílat segmenty
Po připojení middleware jsou všechny příchozí požadavky automaticky trasovány.
Automatická instrumentace: 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'])
Podporované knihovny:
Manuální instrumentace: Python
Přístup přes dekorátor:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Přístup přes 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)
Anotace a metadata v kódu
Přidávání anotací:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Přidávání metadat (podrobný kontext):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Anotace jsou indexovány, metadata nikoli
- Anotace jsou typované, metadata jsou libovolná JSON
- Indexy používej k filtrování, metadata pro ladění
Zpracování chyb v trasách
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
- Výjimky uvnitř trasovaných funkcí jsou zachyceny automaticky
- Přidej anotaci typu chyby pro filtrování v konzoli
- Přidej metadata s úplnými detaily chyby
- Vždy znovu vyvolej výjimku – obsluha chyb aplikace musí proběhnout
Node.js SDK: nastavení 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'));
Implementace v 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)
}
Klíčové informace:
- Lambda odesílá základní trasy automaticky při zapnutém Active Tracing – SDK k tomu nepotřebuješ
- X-Ray SDK nainstaluj pro přidání subsegmentů, anotací a instrumentaci downstream volání
- Zapnutí v konzoli: Configuration → Monitoring tools
- Nebo v šabloně:
Tracing: Active
ECS a Fargate: sidecar vzor
Struktura tasku:
ECS Task
|_ Application Container
| sends to xray-daemon:2000
|_ X-Ray Daemon Container
forwards to X-Ray service
Konfigurace kontejneru aplikace:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Definice tasku obsahuje:
- Kontejner daemona: obraz
amazon/aws-xray-daemon, UDP port 2000 - Kontejner aplikace: proměnná prostředí
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Proč sidecar?
- Daemon se škáluje spolu s tasky
- Selhání jsou izolována na úrovni tasku
Instalace X-Ray daemona
Instalace podle platformy:
- 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
Po instalaci:
sudo systemctl start xray
sudo systemctl enable xray
Co daemon dělá:
- Naslouchá na UDP portu 2000
- Ukládá do vyrovnávací paměti a dávkuje segmenty
- Přeposílá do X-Ray API přes HTTPS
- Řeší opakované pokusy – aplikace to dělat nemusí
Konfigurace daemona
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
- Velikost vyrovnávací paměti – zvyš při vysokém provozu
- Concurrency nastavuje paralelní připojení k X-Ray
- Pro kontejnery nastav UDP adresu na 0.0.0.0
- Local mode – true pro lokální vývoj bez přihlašovacích údajů
Oprávnění IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Nejjednodušší přístup
Použij spravovanou politiku AWSXRayDaemonWriteAccess
Připoj k:
- Roli instance EC2
- Roli tasku ECS
- Prováděcí roli Lambda
Bez správných oprávnění daemon běží, ale segmenty tiše nedoručí.
Vzory nasazení daemona
Shrnutí lekce
- SDK: automatická instrumentace přes
patch_all(), manuální přes dekorátory a context managery - Anotace (indexované, prohledávatelné) vs. metadata (podrobná, neindexovaná)
- Lambda: odesílá základní trasy automaticky; SDK nainstaluj pro subsegmenty a downstream volání
- ECS/Fargate: sidecar vzor s kontejnerem daemona
- Daemon: konfigurován přes cfg.yaml, vyžaduje IAM politiku
AWSXRayDaemonWriteAccess - Nasazení: per-instance pro EC2, sidecar pro kontejnery
Implementace trasování X-Ray
Monitoring and Troubleshooting AWS
