Реализация трассировки X-Ray
Мониторинг и устранение неполадок в AWS
John Q. Martin
Principal Consultant
Обзор X-Ray SDK
Ключевые факты:
- Поддерживаемые языки: Python, Node.js, Java, .NET, Go, Ruby
- Два подхода: автоматическая и ручная инструментация
- SDK взаимодействует с агентом через UDP-порт 2000
- Прямого обращения к X-Ray API не происходит
Автоматическая и ручная инструментация:
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)
Четыре настройки регистратора:
- service — имя в карте сервисов
- sampling — включение/отключение сэмплирования
- context_missing — LOG_ERROR предотвращает сбои
- daemon_address — адрес отправки сегментов
После подключения middleware все входящие запросы трассируются автоматически.
Автоматическая инструментация: 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'])
Поддерживаемые библиотеки:
Ручная инструментация: 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]);
// 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'));
Реализация в 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)
}
Ключевые факты:
- При включённой активной трассировке Lambda отправляет базовые трассировки автоматически — SDK для этого не нужен
- Установите X-Ray SDK, чтобы добавлять подсегменты, аннотации и инструментировать downstream-вызовы
- Включение в консоли: 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(), ручная — с декораторами и контекстными менеджерами - Аннотации (индексируются, доступны для поиска) и метаданные (детальные, без индексации)
- Lambda: базовые трассировки отправляются автоматически; SDK нужен для подсегментов и downstream-вызовов
- ECS/Fargate: паттерн sidecar-контейнера с агентом
- Агент: настраивается через cfg.yaml, требует политику IAM
AWSXRayDaemonWriteAccess - Развёртывание: на каждый экземпляр для EC2, sidecar — для контейнеров
Реализация трассировки X-Ray
Мониторинг и устранение неполадок в AWS
