Menerapkan penelusuran X-Ray
Pemantauan dan Pemecahan Masalah AWS
John Q. Martin
Principal Consultant
Sekilas X-Ray SDK
Fakta utama:
- Bahasa yang didukung: Python, Node.js, Java, .NET, Go, Ruby
- Dua pendekatan: instrumentasi otomatis dan manual
- SDK berkomunikasi dengan daemon pada port UDP 2000
- Tidak pernah berbicara langsung ke X-Ray API
Otomatis vs. Manual:
Python SDK: pengaturan 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)
Empat pengaturan recorder:
- service - nama yang ditampilkan di peta layanan
- sampling - aktif/nonaktifkan sampling
- context_missing - LOG_ERROR mencegah crash
- daemon_address - tujuan pengiriman segmen
Setelah middleware dipasang, semua request masuk otomatis ditelusuri.
Instrumentasi otomatis: Python
# Instrumentasikan semua pustaka yang didukung
from aws_xray_sdk.core import patch_all
patch_all()
# Atau pilih tertentu
from aws_xray_sdk.core import patch
patch(['boto3', 'requests', 'psycopg2'])
Pustaka yang didukung:
Instrumentasi manual: Python
Pendekatan dekorator:
@xray_recorder.capture('process_order')
def process_order(order_id):
order = get_order(order_id)
return process_payment(order)
Pendekatan context manager:
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)
Anotasi dan metadata dalam kode
Menambahkan anotasi:
xray_recorder.put_annotation(
'order_id', order_id)
xray_recorder.put_annotation(
'user_id', user_id)
Menambahkan metadata (konteks detail):
xray_recorder.put_metadata(
'order_details',
{'items': order.items,
'total': order.total})
- Anotasi diindeks, metadata tidak
- Anotasi bertipe, metadata berupa JSON apa pun
- Gunakan indeks untuk pemfilteran, metadata untuk konteks debug
Penanganan error dalam trace
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
- Pengecualian dalam fungsi yang ditelusuri tertangkap otomatis
- Tambahkan anotasi jenis error untuk memfilter di konsol
- Tambahkan metadata untuk detail error lengkap
- Selalu naikkan ulang; penanganan error aplikasi Anda tetap harus berjalan
Node.js SDK: pengaturan Express
const AWSXRay = require('aws-xray-sdk-core');
const xrayExpress = require('aws-xray-sdk-express');
const app = require('express')();
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
// Buka segmen untuk semua request masuk
app.use(xrayExpress.openSegment('MyExpressApp'));
app.get('/api/orders/:id', async (req, res) => {
const order = await fetchOrder(req.params.id);
res.json({ order });
});
// Tutup segmen setelah respons
app.use(xrayExpress.closeSegment());
// Instrumentasi otomatis
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
const https = AWSXRay.captureHTTPs(require('https'));
Implementasi Lambda
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all() # instrument panggilan 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)
}
Fakta utama:
- Lambda mengirim trace dasar secara otomatis saat Active Tracing diaktifkan; tidak perlu SDK untuk itu
- Instal X-Ray SDK untuk menambah subsegment, anotasi, dan instrumentasi panggilan hilir
- Aktifkan di konsol: Configuration → Monitoring tools
- Atau di template:
Tracing: Active
ECS dan Fargate: pola sidecar
Struktur task:
ECS Task
|_ Application Container
| mengirim ke xray-daemon:2000
|_ X-Ray Daemon Container
meneruskan ke layanan X-Ray
Konfigurasi kontainer aplikasi:
xray_recorder.configure(
service='MyECSApp',
daemon_address='xray-daemon:2000'
)
Definisi task mencakup:
- Kontainer daemon: image
amazon/aws-xray-daemon, port UDP 2000 - Kontainer aplikasi: variabel env
AWS_XRAY_DAEMON_ADDRESS=xray-daemon:2000
Mengapa sidecar?
- Daemon menskalakan bersama task Anda
- Kegagalan terisolasi per task
Menginstal X-Ray daemon
Instal per platform:
- 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
Pasca-instalasi:
sudo systemctl start xray
sudo systemctl enable xray
Fungsi daemon:
- Mendengarkan pada port UDP 2000
- Menyangga dan mengelompokkan segmen
- Meneruskan ke X-Ray API melalui HTTPS
- Menangani retry; aplikasi Anda tidak perlu
Konfigurasi daemon
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
- Ukuran buffer, tingkatkan untuk lalu lintas tinggi
- Concurrency mengatur koneksi paralel ke X-Ray
- Untuk kontainer, setel alamat UDP ke 0.0.0.0
- Local mode, true untuk pengembangan lokal tanpa kredensial
Izin IAM
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets",
"xray:GetSamplingStatisticSummaries"
],
"Resource": "*"
}
Cara termudah
Gunakan kebijakan terkelola AWSXRayDaemonWriteAccess
Lampirkan ke:
- Peran instance EC2
- Peran task ECS
- Peran eksekusi Lambda
Tanpa izin yang benar, daemon berjalan tetapi gagal diam-diam mengirim segmen.
Pola deployment daemon
Rangkuman pelajaran
- SDK: instrumentasi otomatis dengan
patch_all(), manual dengan dekorator dan context manager - Anotasi (diindeks, dapat dicari) vs. metadata (detail, tidak diindeks)
- Lambda: mengirim trace dasar otomatis; instal SDK untuk subsegment dan panggilan hilir
- ECS/Fargate: pola kontainer daemon sidecar
- Daemon: dikonfigurasi via cfg.yaml, butuh kebijakan IAM
AWSXRayDaemonWriteAccess - Deployment: per-instance untuk EC2, sidecar untuk kontainer
Menerapkan penelusuran X-Ray
Pemantauan dan Pemecahan Masalah AWS
