Mengonfigurasi X-Ray SDK for Python

X-Ray SDK for Python mencakup kelas bernama xray_recorder yang menyediakan pencatat global. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan middleware yang membuat segmen untuk panggilan HTTP masuk.

Plugin layanan

Gunakan plugins untuk mencatat informasi tentang layanan yang meng-hosting aplikasi Anda.

Plugin

• Amazon EC2 — EC2Plugin menambahkan ID instans, Availability Zone, dan Grup CloudWatch Log.

• Elastic Beanstalk – ElasticBeanstalkPlugin menambahkan nama lingkungan, label versi, dan ID deployment.

• Amazon ECS – ECSPlugin menambahkan ID kontainer.

Untuk menggunakan plugin, hubungi configure di xray_recorder.

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()

catatan

Karena plugins diteruskan sebagai tuple, pastikan untuk menyertakan , saat menentukan plugin tunggal. Misalnya, plugins = ('EC2Plugin',)

Anda juga dapat menggunakan variabel lingkungan, yang diutamakan daripada nilai yang ditetapkan dalam kode, untuk mengonfigurasi pencatat.

Konfigurasikan plugin sebelum pustaka patch untuk mencatat panggilan hilir.

SDK juga menggunakan pengaturan plugin untuk mengatur bidang origin pada segmen. Ini menunjukkan jenis AWS sumber daya yang menjalankan aplikasi Anda. Saat Anda menggunakan beberapa plugin, SDK menggunakan urutan resolusi berikut untuk menentukan asal: ElasticBeanstalk > EKS > ECS > EC2.

Aturan pengambilan sampel

SDK menggunakan aturan pengambilan sampel yang Anda tetapkan di konsol X-Ray untuk menentukan permintaan yang akan dicatat. Aturan default menelusuri permintaan pertama setiap detik, dan lima persen permintaan tambahan di semua layanan yang mengirim pelacakan ke X-Ray. Buat aturan tambahan di konsol X-Ray untuk menyesuaikan jumlah data yang dicatat untuk setiap aplikasi Anda.

SDK menerapkan aturan kustom sesuai urutan penetapannya. Jika permintaan cocok dengan beberapa aturan kustom, SDK hanya menerapkan aturan pertama.

catatan

Jika SDK tidak dapat mencapai X-Ray untuk mendapatkan aturan sampling, SDK akan kembali ke aturan lokal default dari permintaan pertama yang diterima pada awal setiap detik, dan lima persen dari permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil API pengambilan sampel, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai proksi TCP untuk panggilan API yang dibuat oleh SDK.

Anda juga dapat mengonfigurasi SDK untuk memuat aturan sampling dari dokumen JSON. SDK dapat menggunakan aturan lokal sebagai cadangan jika terjadi kasus tidak dapat mengambil sampel X-Ray, atau menggunakan aturan lokal secara eksklusif.

contoh sampling-rules.json

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

Contoh ini menentukan satu aturan kustom dan aturan default. Aturan kustom menerapkan tingkat pengambilan sampel lima persen tanpa jumlah minimum permintaan untuk melacak jalur di /api/move/. Aturan default menelusuri permintaan pertama setiap detik dan 10 persen dari permintaan tambahan.

Kerugian dari menentukan aturan secara lokal adalah bahwa target tetap diterapkan oleh setiap instans pencatat secara independen, alih-alih dikelola oleh layanan X-Ray. Ketika Anda men-deploy lebih banyak host, laju tetap akan dikalikan, sehingga sulit untuk mengontrol jumlah data yang dicatat.

Pada AWS Lambda, Anda tidak dapat mengubah laju pengambilan sampel. Jika fungsi Anda dipanggil oleh layanan yang diinstrumentasikan, panggilan yang menghasilkan permintaan yang sampelnya diambil oleh layanan yang akan dicatat oleh Lambda. Jika pelacakan aktif diaktifkan dan tidak ada header pelacakan, Lambda membuat keputusan pengambilan sampel.

Untuk mengonfigurasi aturan pengambilan sampel cadangan, panggil xray_recorder.configure, tempat aturan berupa kamus yang memuat aturan atau jalur absolut ke file JSON yang berisi aturan pengambilan sampel.

xray_recorder.configure(sampling_rules=rules)

Untuk menggunakan hanya aturan lokal, konfigurasikan pencatat dengan LocalSampler.

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())

Anda juga dapat mengonfigurasi pencatat global untuk menonaktifkan pengambilan sampel dan instrumen semua permintaan masuk.

contoh main.py - Nonaktifkan sampling

xray_recorder.configure(sampling=False)

Pencatatan log

SDK menggunakan modul logging Python bawaan dengan tingkat pencatatan WARNING default. Dapatkan referensi ke pencatat untuk kelas aws_xray_sdk dan panggil setLevel untuk mengonfigurasi tingkat log yang berbeda untuk pustaka dan sisa aplikasi Anda.

contoh app.py - Pencatatan

logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

Gunakan log debug untuk mengidentifikasi masalah, seperti subsegmen yang tidak tertutup, saat Anda menghasilkan subsegmen secara manual.

Konfigurasi pencatat dalam kode

Pengaturan tambahan tersedia dari metode configure pada xray_recorder.

• context_missing – Mengatur ke LOG_ERROR untuk menghindari mengembalikan pengecualian ketika kode instrumentasi Anda mencoba mencatat data ketika tidak ada segmen yang terbuka.

• daemon_address – Mengatur host dan port listener daemon X-Ray.

• service – Mengatur nama layanan yang digunakan SDK untuk segmen.

• plugins— Rekam informasi tentang AWS sumber daya aplikasi Anda.

• sampling – Atur ke False untuk menonaktifkan pengambilan sampel.

• sampling_rules – Mengatur jalur dari file JSON yang berisi Aturan pengambilan sampel.

contoh main.py - Nonaktifkan pengecualian konteks yang hilang

from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')

Konfigurasi pencatat dengan Django

Jika Anda menggunakan kerangka kerja Django, Anda dapat menggunakan file settings.py Django untuk mengonfigurasi opsi pada pencatat global.

• AUTO_INSTRUMENT (hanya Django) – Mencatat subsegmen untuk basis data bawaan dan operasi penyajian templat.

• AWS_XRAY_CONTEXT_MISSING – Mengatur ke LOG_ERROR untuk menghindari mengembalikan pengecualian ketika kode instrumentasi Anda mencoba untuk mencatat data ketika tidak ada segmen yang terbuka.

• AWS_XRAY_DAEMON_ADDRESS – Mengatur host dan port listener daemon X-Ray.

• AWS_XRAY_TRACING_NAME – Mengatur nama layanan yang digunakan SDK untuk segmen.

• PLUGINS— Rekam informasi tentang AWS sumber daya aplikasi Anda.

• SAMPLING – Atur ke False untuk menonaktifkan pengambilan sampel.

• SAMPLING_RULES – Mengatur jalur dari file JSON yang berisi Aturan pengambilan sampel.

Untuk mengaktifkan konfigurasi pencatat di settings.py, tambahkan middleware Django ke daftar aplikasi terinstal.

contoh settings.py – Aplikasi terinstal

INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

Mengonfigurasi pengaturan yang tersedia dalam kamus bernama XRAY_RECORDER.

contoh settings.py – Aplikasi terinstal

XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
    'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
    'SAMPLING': False,
}

Variabel-variabel lingkungan

Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Python. SDK mendukung variabel berikut:

• AWS_XRAY_TRACING_NAME – Mengatur nama layanan yang digunakan SDK untuk segmen. Menimpa nama layanan yang Anda tetapkan secara terprogram.

• AWS_XRAY_SDK_ENABLED – Ketika diatur ke false, menonaktifkan SDK. Secara default, SDK diaktifkan kecuali variabel lingkungan diatur ke salah.

  • Ketika dinonaktifkan, pencatat global secara otomatis menghasilkan segmen dan subsegmen dummy yang tidak dikirim ke daemon, dan patch otomatis dinonaktifkan. Middlewares ditulis sebagai pembungkus atas pencatat global. Semua segmen dan subsegmen generasi melalui middleware juga menjadi segmen dummy dan subsegment dummy.

  • Menetapkan nilai AWS_XRAY_SDK_ENABLEDmelalui variabel lingkungan atau melalui interaksi langsung dengan objek global_sdk_config dari pustaka aws_xray_sdk. Pengaturan ke variabel lingkungan menimpa interaksi ini.

• AWS_XRAY_DAEMON_ADDRESS – Mengatur host dan port listener daemon X-Ray. Secara default, SDK menggunakan 127.0.0.1:2000 untuk data pelacakan (UDP) dan pengambilan sampel (TCP). Gunakan variabel ini jika Anda telah mengonfigurasi daemon untuk mendengarkan di port berbeda atau jika berjalan pada host yang berbeda.

  format

  • Port yang sama – address:port

  • Port yang berbeda – tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING— Setel RUNTIME_ERROR untuk melempar pengecualian saat kode instrumentasi Anda mencoba merekam data saat tidak ada segmen yang terbuka.

  Nilai Valid

  • RUNTIME_ERROR— Lempar pengecualian runtime.

  • LOG_ERROR— Log kesalahan dan lanjutkan (default).

  • IGNORE_ERROR— Abaikan kesalahan dan lanjutkan.

  Kesalahan yang berkaitan dengan segmen atau subsegmen yang hilang dapat terjadi ketika Anda mencoba untuk menggunakan klien yang diinstrumentasi dalam kode perusahaan rintisan yang berjalan ketika tidak ada permintaan terbuka, atau dalam kode yang memunculkan thread baru.

variabel lingkungan menimpa nilai yang ditetapkan dalam kode.