X-Ray ट्रेसिंग लागू करना
Monitoring और Troubleshooting 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 - सेगमेंट कहाँ भेजें
मिडलवेयर जुड़ते ही सभी इनकमिंग रिक्वेस्ट ऑटोमैटिकली ट्रेस होते हैं।
ऑटोमेटिक इन्स्ट्रूमेंटेशन: 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})
- एनोटेशन इंडेक्स होते हैं, मेटाडेटा नहीं
- एनोटेशन typed होते हैं, मेटाडेटा कोई भी 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
- ट्रेस्ड फंक्शन के अंदर की exceptions ऑटोमेटिकली कैप्चर होती हैं
- कंसोल में फ़िल्टर करने के लिए error type का एनोटेशन जोड़ें
- पूरे error विवरण के लिए मेटाडेटा जोड़ें
- हमेशा दोबारा raise करें, आपकी ऐप की error हैंडलिंग फिर भी चलनी चाहिए
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)
}
मुख्य बातें:
- Active Tracing सक्षम होने पर Lambda मूल ट्रेस ऑटोमेटिक भेजता है, उसके लिए SDK जरूरी नहीं
- सब-सेगमेंट, एनोटेशन, और डाउनस्ट्रीम कॉल्स इंस्ट्रूमेंट करने के लिए X-Ray SDK इंस्टॉल करें
- कंसोल में सक्षम करें: Configuration → Monitoring tools
- या टेम्पलेट में:
Tracing: Active
ECS और Fargate: साइडकार पैटर्न
टास्क संरचना:
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'
)
टास्क डेफिनिशन में शामिल:
- Daemon कंटेनर:
amazon/aws-xray-daemonइमेज, UDP पोर्ट 2000 - App कंटेनर: env var
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
साइडकार क्यों?
- डेमन आपके टास्क के साथ स्केल होता है
- फ़ेल्योर प्रति टास्क आइसोलेट रहते हैं
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 पर listen करता है
- सेगमेंट buffer और batch करता है
- HTTPS के ज़रिए X-Ray API को फॉरवर्ड करता है
- retries संभालता है, आपकी ऐप को ज़रूरत नहीं
डेमन कॉन्फ़िगरेशन
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 address को 0.0.0.0 करें
- Local mode, लोकल डेवलपमेंट बिना credentials के लिए true करें
IAM परमिशन
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
सबसे आसान तरीका
मैनेज्ड पॉलिसी AWSXRayDaemonWriteAccess उपयोग करें
अटैच करें:
- EC2 इंस्टेंस रोल
- ECS टास्क रोल
- Lambda execution रोल
सही permissions न हों तो डेमन चलता है पर सेगमेंट चुपचाप डिलीवर नहीं होते।
डेमन डिप्लॉयमेंट पैटर्न
पाठ सारांश
- SDK:
patch_all()से ऑटोमेटिक, डेकोरेटर और कॉन्टेक्स्ट मैनेजर से मैनुअल - एनोटेशन (इंडेक्स्ड, सर्चेबल) बनाम मेटाडेटा (विस्तृत, non-indexed)
- Lambda: बेसिक ट्रेसेज़ ऑटोमेटिक; सब-सेगमेंट और डाउनस्ट्रीम कॉल्स के लिए SDK इंस्टॉल करें
- ECS/Fargate: साइडकार डेमन कंटेनर पैटर्न
- डेमन: cfg.yaml से कॉन्फ़िग,
AWSXRayDaemonWriteAccessIAM पॉलिसी चाहिए - डिप्लॉयमेंट: EC2 पर per-instance, कंटेनरों के लिए साइडकार
X-Ray ट्रेसिंग लागू करना
Monitoring और Troubleshooting AWS
