Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Mengonfigurasi SDK X-Ray for Node.js **catatan** Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 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. **Topics** + [Plugin layanan](#xray-sdk-nodejs-configuration-plugins) + [Aturan pengambilan sampel](#xray-sdk-nodejs-configuration-sampling) + [Logging](#xray-sdk-nodejs-configuration-logging) + [Alamat daemon X-Ray](#xray-sdk-nodejs-configuration-daemon) + [Variabel-variabel lingkungan](#xray-sdk-nodejs-configuration-envvars) ## 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, konfigurasikan klien X-Ray SDK for Node.js dengan menggunakan metode `config`. **Example 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. 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](xray-console-sampling.md) 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 sampling APIs, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai proxy TCP untuk panggilan API yang dilakukan 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. **Example 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. AWS Lambda Aktif, 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`. **Example 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. **Example 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() ``` ## Logging Untuk mencatat output dari SDK, panggil `AWSXRay.setLogger(logger)`, tempat `logger`merupakan 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](#xray-sdk-nodejs-configuration-envvars). 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. **Example 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 berdasarkan nama atau IPv4 alamat. **Example 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. **Example 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](#xray-sdk-nodejs-configuration-envvars) `AWS_XRAY_DAEMON_ADDRESS`. ## Variabel-variabel lingkungan Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Node.js. SDK mendukung variabel berikut. + `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. + `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](xray-daemon-configuration.md) 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\$1XRAY\$1DEBUG\$1MODE disetel ke`TRUE`. + `AWS_XRAY_TRACING_NAME` – Mengatur nama layanan yang digunakan SDK untuk segmen. Timpa nama segmen yang Anda [tetapkan di middleware Express](xray-sdk-nodejs-middleware.md).