Реалізація трасування X-Ray
Моніторинг і усунення несправностей в AWS
John Q. Martin
Principal Consultant
Огляд X-Ray SDK
Важливе:
- Підтримувані мови: Python, Node.js, Java, .NET, Go, Ruby
- Два підходи: автоматичне та ручне інструментування
- SDK спілкується з демоном через UDP-порт 2000
- Ніколи не звертається безпосередньо до X-Ray API
Автоматичне vs. ручне:
Python SDK: налаштування 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)
Чотири параметри recorder:
- service — назва, що відображається на мапі сервісів
- sampling — увімк./вимк. семплювання
- context_missing — LOG_ERROR запобігає збоям
- daemon_address — куди надсилати сегменти
Після підключення middleware всі вхідні запити трасуються автоматично.
Автоматичне інструментування: Python
# Інструментувати всі підтримувані бібліотеки
from aws_xray_sdk.core import patch_all
patch_all()
# Або вибірково
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Підтримувані бібліотеки:
Ручне інструментування: Python
Декоратор:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Контекст-менеджер:
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)
Анотації та метадані в коді
Додавання анотацій:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Додавання метаданих (детальний контекст):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Анотації — це індекси, метадані — ні
- Анотації типізовані, метадані — будь-який JSON
- Індекси — для фільтрації, метадані — для налагодження
Обробка помилок у трейсах
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
- Винятки в трасованих функціях захоплюються автоматично
- Додайте анотацію з типом помилки, щоб фільтрувати в консолі
- Додайте метадані з повними деталями помилки
- Завжди перевикидайте виняток — обробка помилок застосунку має відпрацювати
Node.js SDK: налаштування Express
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Відкривати сегмент для всіх вхідних запитів
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Закривати сегмент після відповіді
app.use(xrayExpress.closeSegment());
// Автоматичне інструментування
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Реалізація в Lambda
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # інструментування викликів 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)
}
Важливе:
- Lambda надсилає базові трейси автоматично, якщо ввімкнено Active Tracing; для цього SDK не потрібен
- Встановіть X-Ray SDK, щоб додавати підсегменти, анотації та інструментувати вихідні виклики
- У консолі: Configuration → Monitoring tools
- Або в шаблоні:
Tracing: Active
ECS і Fargate: шаблон sidecar
Структура завдання:
ECS Task
|_ Application Container
| sends to xray-daemon:2000
|_ X-Ray Daemon Container
forwards to X-Ray service
Налаштування контейнера застосунку:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Визначення завдання містить:
- Контейнер демона: образ
amazon/aws-xray-daemon, UDP-порт 2000 - Контейнер застосунку: змінна середовища
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Чому sidecar?
- Демон масштабується разом із завданнями
- Збої ізольовані в межах завдання
Встановлення демона X-Ray
Встановлення за платформами:
- 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
Після встановлення:
sudo systemctl start xray
sudo systemctl enable xray
Що робить демон:
- Слухає UDP-порт 2000
- Буферизує та об'єднує сегменти
- Пересилає до X-Ray API через HTTPS
- Обробляє повторні спроби — застосунку це не потрібно
Конфігурація демона
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
- Розмір буфера; збільшуйте для великого трафіку
- Concurrency — кількість паралельних підключень до X-Ray
- Для контейнерів задайте UDP-адресу 0.0.0.0
- Local mode — true для локальної розробки без облікових даних
Дозволи IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Найпростіший підхід
Використайте керовану політику AWSXRayDaemonWriteAccess
Призначте для:
- Ролі інстансу EC2
- Ролі завдання ECS
- Ролі виконання Lambda
Без належних дозволів демон працює, але тихо не доставляє сегменти.
Шаблони розгортання демона
Підсумок уроку
- SDK: автоматичне інструментування через
patch_all(), ручне — декораторами й контекст-менеджерами - Анотації (індексуються, пошукові) vs. метадані (детальні, без індексації)
- Lambda: надсилає базові трейси автоматично; встановіть SDK для підсегментів і вихідних викликів
- ECS/Fargate: патерн контейнера- sidecar для демона
- Демон: налаштовується у cfg.yaml, потребує IAM-політики
AWSXRayDaemonWriteAccess - Розгортання: per-instance для EC2, sidecar для контейнерів
Реалізація трасування X-Ray
Моніторинг і усунення несправностей в AWS
