Implementacja śledzenia X-Ray
Monitoring and Troubleshooting AWS
John Q. Martin
Principal Consultant
Przegląd X-Ray SDK
Najważniejsze informacje:
- Obsługiwane języki: Python, Node.js, Java, .NET, Go, Ruby
- Dwa podejścia: automatyczna i ręczna instrumentacja
- SDK komunikuje się z daemonem przez UDP port 2000
- Nigdy nie łączy się bezpośrednio z X-Ray API
Automatyczna vs. ręczna:
Python SDK: konfiguracja 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)
Cztery ustawienia rejestratora:
- service — nazwa widoczna na mapie usług
- sampling — włącz/wyłącz próbkowanie
- context_missing — LOG_ERROR zapobiega awariom
- daemon_address — adres docelowy segmentów
Po podłączeniu middleware wszystkie przychodzące żądania są śledzone automatycznie.
Automatyczna instrumentacja: 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'])
Obsługiwane biblioteki:
Ręczna instrumentacja: Python
Podejście z dekoratorem:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Podejście z menedżerem kontekstu:
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)
Adnotacje i metadane w kodzie
Dodawanie adnotacji:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Dodawanie metadanych (szczegółowy kontekst):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Adnotacje są indeksowane, metadane — nie
- Adnotacje mają typy, metadane mogą być dowolnym JSON
- Indeksów używaj do filtrowania, metadanych — do debugowania
Obsługa błędów w śladach
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
- Wyjątki wewnątrz śledzonych funkcji są przechwytywane automatycznie
- Dodaj adnotację z typem błędu, aby filtrować w konsoli
- Dodaj metadane z pełnymi szczegółami błędu
- Zawsze ponownie rzucaj wyjątek — obsługa błędów w aplikacji musi działać dalej
Node.js SDK: konfiguracja 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'));
Implementacja w 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)
}
Najważniejsze informacje:
- Przy włączonym Active Tracing Lambda wysyła podstawowe ślady automatycznie — bez SDK
- Zainstaluj X-Ray SDK, aby dodawać podsegmenty, adnotacje i śledzić wywołania downstream
- Włączanie w konsoli: Configuration → Monitoring tools
- Lub w szablonie:
Tracing: Active
ECS i Fargate: wzorzec sidecar
Struktura zadania:
ECS Task
|_ Application Container
| sends to xray-daemon:2000
|_ X-Ray Daemon Container
forwards to X-Ray service
Konfiguracja kontenera aplikacji:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Definicja zadania obejmuje:
- Kontener daemona: obraz
amazon/aws-xray-daemon, UDP port 2000 - Kontener aplikacji: zmienna środowiskowa
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Dlaczego sidecar?
- Daemon skaluje się razem z zadaniami
- Awarie są izolowane per zadanie
Instalacja daemona X-Ray
Instalacja według 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 instalacji:
sudo systemctl start xray
sudo systemctl enable xray
Co robi daemon:
- Nasłuchuje na UDP port 2000
- Buforuje i grupuje segmenty w partie
- Przesyła do X-Ray API przez HTTPS
- Obsługuje ponowne próby — aplikacja nie musi tego robić
Konfiguracja 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
- Rozmiar bufora — zwiększ przy dużym ruchu
- Concurrency określa liczbę równoległych połączeń z X-Ray
- Dla kontenerów ustaw adres UDP na 0.0.0.0
- Local mode — wartość true dla lokalnego środowiska bez poświadczeń
Uprawnienia IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Najprostsze podejście
Użyj zarządzanej polityki AWSXRayDaemonWriteAccess
Dołącz do:
- roli instancji EC2
- roli zadania ECS
- roli wykonania Lambda
Bez odpowiednich uprawnień daemon działa, ale po cichu nie dostarcza segmentów.
Wzorce wdrożenia daemona
Podsumowanie lekcji
- SDK: automatyczna instrumentacja przez
patch_all(), ręczna — przez dekoratory i menedżery kontekstu - Adnotacje (indeksowane, przeszukiwalne) vs. metadane (szczegółowe, nieindeksowane)
- Lambda: podstawowe ślady wysyłane automatycznie; SDK potrzebny do podsegmentów i wywołań downstream
- ECS/Fargate: wzorzec kontenera sidecar z daemonem
- Daemon: konfigurowany przez cfg.yaml, wymaga polityki IAM
AWSXRayDaemonWriteAccess - Wdrożenie: per-instance dla EC2, sidecar dla kontenerów
Implementacja śledzenia X-Ray
Monitoring and Troubleshooting AWS
