Mengonfigurasi SDK X-Ray for Node.js

Anda dapat mengonfigurasi SDK X-Ray for Node.js dengan plugin untuk menyertakan informasi tentang layanan yang dijalankan aplikasi Anda, mengubah perilaku pengambilan sampel default, atau menambahkan aturan pengambilan sampel yang berlaku untuk permintaan ke jalur tertentu.

Plugin layanan

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

Plugin

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

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

• Amazon ECS – ECSPlugin menambahkan ID kontainer.

Untuk menggunakan plugin, konfigurasikan klien X-Ray SDK for Node.js dengan menggunakan metode config.

contoh app.js - plugin

var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

SDK juga menggunakan pengaturan plugin untuk mengatur bidang origin pada segmen. Hal ini menunjukkan tipeAWS sumber daya yang menjalankan aplikasi Anda. Bila Anda menggunakan beberapa plugin, SDK menggunakan urutan resolusi berikut untuk menentukan asal: ElasticBeanstalk > 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 pengambilan sampel, SDK akan beralih ke aturan lokal default dari permintaan pertama setiap detik, dan lima persen 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 cadangan, beri tahu SDK X-Ray for Node.js untuk memuat aturan pengambilan sampel dari file dengan setSamplingRules.

contoh app.js - aturan pengambilan sampel dari suatu file

var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

Anda juga dapat menentukan aturan dalam kode dan meneruskannya ke setSamplingRules sebagai objek.

contoh app.js - aturan pengambilan sampel untuk suatu objek

var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

Untuk hanya menggunakan aturan lokal, hubungi disableCentralizedSampling.

AWSXRay.middleware.disableCentralizedSampling()

Mencatat

Untuk mencatat output dari SDK, panggil AWSXRay.setLogger(logger), tempat loggermerupakan obyek yang menyediakan metode pencatatan standar (warn, info, dll.).

Secara default SDK akan mencatat pesan kesalahan ke konsol tersebut menggunakan metode standar pada objek konsol. Tingkat log pencatat bawaan dapat diatur dengan menggunakan variabel lingkungan AWS_XRAY_DEBUG_MODE atau AWS_XRAY_LOG_LEVEL. Untuk daftar nilai tingkat log yang valid, lihat Variabel lingkungan.

Jika Anda ingin memberikan format yang berbeda atau tujuan untuk log maka Anda dapat memberikan SDK dengan implementasi Anda sendiri dari antarmuka pencatat seperti yang ditunjukkan di bawah ini. Setiap objek yang mengimplementasikan antarmuka ini dapat digunakan. Yang berarti banyak pustaka pencatatan, misalnya Winston, dapat digunakan dan diteruskan ke SDK secara langsung.

contoh app.js - pencatatan

var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

Panggil setLogger sebelum Anda menjalankan metode konfigurasi lain untuk memastikan bahwa Anda menangkap output dari operasi tersebut.

Alamat daemon X-Ray

Jika daemon X-Ray mendengar di port atau host selain 127.0.0.1:2000, Anda dapat mengonfigurasi X-Ray SDK for Node.js untuk mengirim data penelusuran ke alamat yang berbeda.

AWSXRay.setDaemonAddress('host:port');

Anda dapat menentukan host dengan nama atau dengan alamat IPv4.

contoh app.js - alamat daemon

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

Jika Anda mengonfigurasi daemon untuk mendengar di port yang berbeda untuk TCP dan UDP, Anda dapat menentukan keduanya dalam pengaturan alamat daemon.

contoh app.js - alamat daemon pada port terpisah

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

Anda juga dapat mengatur alamat daemon dengan menggunakan Variabel lingkungan AWS_XRAY_DAEMON_ADDRESS.

Variabel lingkungan

Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Node.js. SDK mendukung variabel berikut.

• AWS_XRAY_CONTEXT_MISSING— MengaturRUNTIME_ERROR ke pengecualian ketika kode instrumentasi Anda mencoba mencatat data ketika tidak ada segmen yang terbuka.

  Nilai yang Valid

  • RUNTIME_ERROR- Lempar pengecualian runtime.

  • LOG_ERROR— Mencatat kesalahan dan melanjutkan (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.

• AWS_XRAY_DAEMON_ADDRESS – Mengatur host dan port pendengar 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_DEBUG_MODE – Atur ke TRUE untuk mengonfigurasi SDK untuk meng-output log ke konsol, di tingkat debug.

• AWS_XRAY_LOG_LEVEL – Mengatur tingkat log untuk pencatat default. Nilai yang valid adalah debug, info, warn, error, dan silent. Nilai ini diabaikan ketika AWS_XRAY_DEBUG_MODE diatur ke TRUE.

• AWS_XRAY_TRACING_NAME – Mengatur nama layanan yang digunakan SDK untuk segmen. Timpa nama segmen yang Anda tetapkan di middleware Express.