X-Ray izlemeyi uygulama
AWS'i İzleme ve Sorun Giderme
John Q. Martin
Principal Consultant
X-Ray SDK genel bakış
Temel bilgiler:
- Desteklenen diller: Python, Node.js, Java, .NET, Go, Ruby
- İki yaklaşım: otomatik ve manuel araçlama
- SDK, UDP 2000 portunda daemona iletişim kurar
- X-Ray API ile asla doğrudan konuşmaz
Otomatik vs. Manuel:
Python SDK: Flask kurulumu
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)
Dört recorder ayarı:
- service - hizmet haritasında görünen ad
- sampling - örneklemeyi aç/kapat
- context_missing - LOG_ERROR çöküşleri engeller
- daemon_address - segmentlerin gönderileceği yer
Middleware eklendikten sonra tüm gelen istekler otomatik izlenir.
Otomatik araçlama: Python
# Desteklenen tüm kütüphaneleri araçla
from aws_xray_sdk.core import patch_all
patch_all()
# Ya da seçmeli olarak
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Desteklenen kütüphaneler:
Manuel araçlama: Python
Dekoratör yaklaşımı:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Bağlam yöneticisi yaklaşımı:
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)
Kodda açıklamalar ve meta veriler
Açıklama (annotation) ekleme:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Meta veri ekleme (ayrıntılı bağlam):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Açıklamalar endekslenir, meta veriler endekslenmez
- Açıklamalar tipli, meta veriler herhangi bir JSON olabilir
- Filtreleme için açıklama, hata ayıklama bağlamı için meta veri kullan
İzlerde hata yönetimi
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
- İzlenen fonksiyonlardaki istisnalar otomatik yakalanır
- Konsolda filtrelemek için hata türüne bir açıklama ekle
- Tüm hata ayrıntıları için meta veri ekle
- Her zaman yeniden yükselt; uygulamanın hata yönetimi yine çalışmalı
Node.js SDK: Express kurulumu
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Tüm gelen istekler için segment aç
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Yanıttan sonra segmenti kapat
app.use(xrayExpress.closeSegment());
// Otomatik araçlama
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Lambda uygulaması
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # AWS SDK çağrılarını araçla
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)
}
Temel bilgiler:
- Active Tracing etkinse Lambda temel izleri otomatik gönderir; bunun için SDK gerekmez
- Alt segmentler, açıklamalar ve aşağı akış çağrıları için X-Ray SDK'yı kur
- Konsolda etkinleştir: Configuration → Monitoring tools
- Ya da şablonda:
Tracing: Active
ECS ve Fargate: sidecar deseni
Görev yapısı:
ECS Task
|_ Uygulama Container'ı
| xray-daemon:2000'a gönderir
|_ X-Ray Daemon Container'ı
X-Ray servisine iletir
Uygulama container yapılandırması:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Görev tanımı şunları içerir:
- Daemon container:
amazon/aws-xray-daemonimajı, UDP 2000 portu - Uygulama container: çevre değişkeni
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Neden sidecar?
- Daemon, görevlerinle birlikte ölçeklenir
- Hatalar görev bazında yalıtılır
X-Ray daemonu kurma
Platforma göre kurulum:
- 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
Kurulum sonrası:
sudo systemctl start xray
sudo systemctl enable xray
Daemon ne yapar:
- UDP 2000 portunu dinler
- Segmentleri arabelleğe alır ve gruplayıp gönderir
- X-Ray API'ye HTTPS üzerinden iletir
- Yeniden denemeleri yönetir; uygulamanın gerek duymaz
Daemon yapılandırması
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
- Arabellek boyutu; yüksek trafik için artır
- Concurrency, X-Ray'e paralel bağlantıları ayarlar
- Container'lar için UDP adresini 0.0.0.0 yap
- Local mode, kimlik bilgisi olmadan yerel geliştirme için true
IAM izinleri
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
En kolay yaklaşım
Yönetilen ilke AWSXRayDaemonWriteAccess kullan
Şunlara ekle:
- EC2 instance rolü
- ECS task rolü
- Lambda yürütme rolü
Doğru izinler olmadan daemon çalışır ama segmentleri sessizce gönderemez.
Daemon dağıtım desenleri
Ders özeti
- SDK:
patch_all()ile otomatik, dekoratör ve bağlam yöneticileri ile manuel araçlama - Açıklamalar (endeksli, aranabilir) vs. meta veriler (ayrıntılı, endeksli değil)
- Lambda: temel izleri otomatik gönderir; alt segmentler ve aşağı akış çağrıları için SDK kur
- ECS/Fargate: sidecar daemon container deseni
- Daemon: cfg.yaml ile yapılandırılır,
AWSXRayDaemonWriteAccessIAM ilkesine ihtiyaç duyar - Dağıtım: EC2 için instance başına, container'lar için sidecar
X-Ray izlemeyi uygulama
AWS'i İzleme ve Sorun Giderme
