Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Bekerja menggunakan 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
Ada dua cara untuk menginstruksikan aplikasi Node.js Anda untuk mengirim jejak ke X-Ray:
+ [AWS Distro untuk OpenTelemetry JavaScript](xray-js-opentel-sdk.md) [- AWS Distribusi yang menyediakan serangkaian pustaka open source untuk mengirim metrik dan jejak yang berkorelasi ke beberapa solusi AWS pemantauan, termasuk Amazon,, AWS X-Ray dan Amazon OpenSearch Service CloudWatch, melalui Distro for Collector.AWS OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/collector)
+ [AWS X-Ray SDK untuk Node.js](xray-sdk-nodejs.md) [- Satu set perpustakaan untuk menghasilkan dan mengirim jejak ke X-Ray melalui daemon X-Ray.](xray-daemon.md)
Lihat informasi yang lebih lengkap di [Memilih antara AWS Distro untuk OpenTelemetry dan X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro untuk OpenTelemetry JavaScript
Dengan AWS Distro for OpenTelemetry (ADOT) JavaScript, Anda dapat menginstruksikan aplikasi Anda sekali dan mengirim metrik dan jejak yang berkorelasi ke beberapa AWS solusi pemantauan termasuk Amazon CloudWatch,, AWS X-Ray dan Amazon Service. OpenSearch Menggunakan X-Ray dengan AWS Distro untuk OpenTelemetry membutuhkan dua komponen: *OpenTelemetry SDK* diaktifkan untuk digunakan dengan X-Ray, dan *AWS Distro untuk OpenTelemetry Kolektor diaktifkan untuk* digunakan dengan X-Ray.
Untuk memulai, lihat [AWS Distro untuk OpenTelemetry JavaScript dokumentasi](https://aws-otel.github.io/docs/getting-started/javascript-sdk).
**catatan**
ADOT JavaScript didukung untuk semua aplikasi Node.js sisi server. ADOT JavaScript tidak dapat mengekspor data ke X-Ray dari klien browser.
Untuk informasi selengkapnya tentang menggunakan AWS Distro untuk OpenTelemetry with AWS X-Ray dan lainnya Layanan AWS, lihat [AWS Distro untuk OpenTelemetry atau Distro untuk AWS](https://aws-otel.github.io/) [Dokumentasi](https://aws-otel.github.io/docs/introduction). OpenTelemetry
Untuk informasi selengkapnya tentang dukungan dan penggunaan bahasa, lihat [AWS Observabilitas di GitHub](https://github.com/aws-observability).
# AWS X-Ray SDK untuk 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
X-Ray SDK untuk Node.js adalah pustaka untuk aplikasi web Express dan fungsi Node.js Lambda yang menyediakan kelas dan metode untuk menghasilkan dan mengirim pelacakan data ke daemon X-Ray. Data pelacakan mencakup informasi tentang permintaan HTTP masuk yang disajikan oleh aplikasi, dan panggilan yang dilakukan aplikasi ke layanan hilir menggunakan klien AWS SDK atau HTTP.
**catatan**
X-Ray SDK untuk Node.js adalah proyek open source yang didukung untuk Node.js versi 14.x dan lebih tinggi. Anda dapat mengikuti proyek dan mengirimkan masalah dan menarik permintaan di GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-node)- xray-sdk-node
Jika Anda menggunakan Express, mulai dengan [menambahkan SDK sebagai middleware](xray-sdk-nodejs-middleware.md) pada server aplikasi Anda untuk pelacakan permintaan masuk. Middleware membuat [segmen](xray-concepts.md#xray-concepts-segments) untuk setiap permintaan yang dilacak, dan menyelesaikan segmen ketika tanggapan dikirim. Ketika segmen terbuka Anda dapat menggunakan metode klien SDK untuk menambahkan informasi ke segmen dan membuat subsegmen untuk pelacakan panggilan hilir. SDK juga secara otomatis mencatat pengecualian yang aplikasi Anda lempar ketika segmen terbuka.
Untuk fungsi Lambda disebut oleh instrumen aplikasi atau layanan, Lambda membaca [tracing header](xray-concepts.md#xray-concepts-tracingheader) dan pelacakan sampel permintaan secara otomatis. Untuk fungsi lainnya, Anda dapat [mengonfigurasi Lambda](xray-services-lambda.md) untuk sampel dan pelacakan permintaan masuk. Dalam kedua kasus, Lambda membuat segmen dan menyediakannya ke X-Ray SDK.
**catatan**
Pada Lambda, X-Ray SDK adalah opsional. Jika Anda tidak menggunakannya dalam fungsi Anda, peta layanan Anda masih akan menyertakan simpul untuk layanan Lambda, dan satu untuk setiap fungsi Lambda. Dengan menambahkan SDK, Anda dapat melakukan instrumen kode fungsi Anda untuk menambahkan subsegmen ke segmen fungsi yang dicatat oleh Lambda. Lihat [AWS Lambda dan AWS X-Ray](xray-services-lambda.md) untuk informasi selengkapnya.
Selanjutnya, gunakan X-Ray SDK untuk Node.js untuk [instrumen AWS SDK Anda JavaScript di klien Node.js](xray-sdk-nodejs-awssdkclients.md). Setiap kali Anda melakukan panggilan ke hilir Layanan AWS atau sumber daya dengan klien yang diinstrumentasi, SDK akan mencatat informasi tentang panggilan di subsegmen. Layanan AWS dan sumber daya yang Anda akses dalam layanan muncul sebagai node hilir pada peta jejak untuk membantu Anda mengidentifikasi kesalahan dan masalah pembatasan pada koneksi individual.
X-Ray SDK untuk Node.js juga menyediakan instrumentasi untuk panggilan hilir ke web HTTP APIs dan kueri SQL. [Bungkus klien HTTP Anda dalam metode penangkapan SDK](xray-sdk-nodejs-httpclients.md) untuk mencatat informasi tentang panggilan HTTP keluar. Untuk klien SQL, [menggunakan metode penangkapan untuk tipe basis data Anda](xray-sdk-nodejs-sqlclients.md).
Middleware menerapkan aturan pengambilan sampel ke permintaan masuk untuk menentukan permintaan yang dilacak. Anda dapat [mengonfigurasi X-Ray SDK untuk Node.js](xray-sdk-nodejs-configuration.md) untuk menyesuaikan perilaku pengambilan sampel atau merekam informasi tentang sumber daya AWS komputasi tempat aplikasi Anda berjalan.
Catat informasi tambahan tentang permintaan dan pekerjaan yang dilakukan aplikasi Anda dalam [anotasi dan metadata](xray-sdk-nodejs-segment.md). Anotasi adalah pasangan kunci-nilai sederhana yang diindeks untuk digunakan dengan [ekspresi filter](xray-console-filters.md), sehingga Anda dapat mencari pelacakan yang berisi data tertentu. Entri metadata kurang bersifat membatasi dan dapat mencatat seluruh objek dan array — segala yang dapat disambungkan ke dalam JSON.
**Anotasi dan Metadata**
Anotasi dan metadata adalah teks abritari yang Anda tambahkan ke segmen dengan X-Ray SDK. Anotasi diindekskan untuk digunakan dengan ekspresi filter. Metadata tidak diindeks, tetapi dapat dilihat di segmen mentah dengan konsol X-Ray atau API. Siapa pun yang Anda berikan akses baca ke X-Ray dapat melihat data ini.
Bila Anda memiliki banyak klien diinstrumentasi dalam kode Anda, segmen permintaan tunggal dapat berisi sejumlah besar subsegmen, satu untuk setiap panggilan yang dilakukan dengan klien yang diinstrumentasi. Anda dapat mengatur dan mengelompokkan subsegmen dengan menggabungkan panggilan klien di [subsegmen kustom](xray-sdk-nodejs-subsegments.md). Anda dapat membuat subsegmen kustom untuk seluruh fungsi atau bagian dari kode, dan mencatat metadata dan anotasi pada subsegmen bukan menulis segala sesuatu pada segmen induk.
Untuk dokumentasi referensi tentang kelas SDK dan metode, lihat [AWS X-Ray Referensi API SDK untuk Node.js](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference).
## Persyaratan
X-Ray SDK untuk Node.js membutuhkan Node.js dan pustaka berikut:
+ `atomic-batcher` – 1.0.2
+ `cls-hooked` – 4.2.2
+ `pkginfo` – 0.4.0
+ `semver` – 5.3.0
SDK menarik pustaka ini saat Anda menginstalnya dengan NPM.
Untuk melacak klien AWS SDK, X-Ray SDK untuk Node.js memerlukan versi minimum AWS SDK untuk JavaScript Node.js.
+ `aws-sdk` – 2.7.15
## Manajemen dependensi
X-Ray SDK untuk Node.js tersedia dari NPM.
+ **Package** - [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
Untuk pengembangan lokal, instal SDK di direktori proyek Anda dengan npm.
```
~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
├─┬ aws-xray-sdk-core@3.3.3
│ ├── @aws-sdk/service-error-classification@3.15.0
│ ├── @aws-sdk/types@3.15.0
│ ├─┬ @types/cls-hooked@4.3.3
│ │ └── @types/node@15.3.0
│ ├── atomic-batcher@1.0.2
│ ├─┬ cls-hooked@4.2.2
│ │ ├─┬ async-hook-jl@1.7.6
│ │ │ └── stack-chain@1.3.7
│ │ └─┬ emitter-listener@1.1.2
│ │ └── shimmer@1.2.1
│ └── semver@5.7.1
├── aws-xray-sdk-express@3.3.3
├── aws-xray-sdk-mysql@3.3.3
└── aws-xray-sdk-postgres@3.3.3
```
Gunakan opsi `--save` untuk menyimpan SDK sebagai dependensi dalam aplikasi `package.json` Anda.
```
~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3
```
Jika aplikasi Anda memiliki dependensi yang versinya bertentangan dengan dependensi X-Ray SDK, kedua versi akan diinstal untuk memastikan kompatibilitas. Untuk detail selengkapnya, lihat [dokumentasi NPM resmi untuk resolusi dependensi](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html).
## Sampel Node.js
Bekerja dengan AWS X-Ray SDK untuk Node.js untuk mendapatkan end-to-end tampilan permintaan saat mereka melakukan perjalanan melalui aplikasi Node.js Anda.
+ [Node.js contoh aplikasi](https://github.com/aws-samples/aws-xray-sdk-node-sample) pada GitHub.
# 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).
# Menelusuri permintaan yang masuk dengan X-Ray SDK 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 menggunakan X-Ray SDK untuk Node.js untuk melacak permintaan HTTP masuk yang disajikan oleh aplikasi Express dan Restify pada instans EC2 di Amazon EC2,, atau Amazon ECS. AWS Elastic Beanstalk
X-Ray SDK for Node.js menyediakan perangkat tengah untuk aplikasi yang menggunakan Express dan kerangka kerja Restify. Ketika Anda menambahkan perangkat tengah X-Ray ke aplikasi Anda, X-Ray SDK for Node.js membuat segmen untuk setiap permintaan sampel. Segmen ini mencakup waktu, metode, dan disposisi permintaan HTTP. Instrumentasi tambahan membuat subsegmen pada segmen ini.
**catatan**
Untuk AWS Lambda fungsi, Lambda membuat segmen untuk setiap permintaan sampel. Untuk informasi selengkapnya, lihat [AWS Lambda dan AWS X-Ray](xray-services-lambda.md).
Setiap segmen memiliki nama yang mengidentifikasi aplikasi Anda dalam peta layanan. Segmen dapat diberi nama secara statis, atau Anda dapat mengonfigurasi SDK untuk nama itu secara dinamis berdasarkan header host dalam permintaan masuk. Penamaan dinamis memungkinkan Anda mengelompokkan pelacakan berdasarkan nama domain dalam permintaan, dan menerapkan nama default jika nama tersebut tidak cocok dengan pola yang diharapkan (misalnya, jika header host ditiru).
**Permintaan yang Diteruskan**
Jika penyeimbang beban atau perantara lainnya meneruskan permintaan ke aplikasi Anda, X-Ray akan mengambil IP klien dari header `X-Forwarded-For` dalam permintaan bukan dari sumber IP dalam paket IP. IP klien yang dicatat untuk permintaan yang diteruskan dapat ditiru, sehingga tidak dapat dipercaya.
Ketika permintaan diteruskan, SDK menetapkan bidang tambahan di segmen untuk menunjukkan ini. Jika segmen yang berisi bidang `x_forwarded_for` ditetapkan ke `true`, IP klien diambil dari header `X-Forwarded-For` dalam permintaan HTTP.
Penangan pesan membuat segmen untuk setiap permintaan masuk dengan blok `http` yang berisi informasi berikut:
+ **Metode HTTP** – DAPATKAN, POSTING, LETAKKAN, HAPUS, dll.
+ **Alamat klien** – Alamat IP klien yang mengirim permintaan.
+ **Kode respons** – Kode respons HTTP untuk permintaan yang selesai.
+ **Timing** – Waktu mulai (saat permintaan diterima) dan waktu akhir (saat respons dikirim).
+ **Agen pengguna** — `user-agent` dari permintaan.
+ **Panjang konten** — `content-length` dari respons.
**Topics**
+ [Menelusuri permintaan masuk dengan Express](#xray-sdk-nodejs-middleware-express)
+ [Menelusuri permintaan masuk dengan restify](#xray-sdk-nodejs-middleware-restify)
+ [Mengonfigurasi strategi penamaan segmen](#xray-sdk-nodejs-middleware-naming)
## Menelusuri permintaan masuk dengan Express
Untuk menggunakan perangkat tengah Express, menginisialisasi klien SDK dan menggunakan perangkat tengah dikembalikan oleh fungsi `express.openSegment` sebelum Anda menentukan rute Anda.
**Example app.js - Express**
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
Setelah Anda menentukan rute Anda, gunakan output dari `express.closeSegment` seperti yang ditunjukkan untuk menangani kesalahan yang dikembalikan oleh X-Ray SDK for Node.js.
## Menelusuri permintaan masuk dengan restify
Untuk menggunakan perangkat tengah Restify, menginisialisasi klien SDK dan menjalankan `enable`. Teruskan nama segmen dan server Restify Anda.
**Example app.js - restify**
```
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
server.get('/', function (req, res) {
res.render('index');
});
```
## Mengonfigurasi strategi penamaan segmen
AWS X-Ray menggunakan *nama layanan* untuk mengidentifikasi aplikasi Anda dan membedakannya dari aplikasi lain, database, eksternal APIs, dan AWS sumber daya yang digunakan aplikasi Anda. Saat SDK X-Ray membuat segmen untuk permintaan masuk, SDK akan mencatat nama layanan aplikasi Anda di [kolom nama](xray-api-segmentdocuments.md#api-segmentdocuments-fields).
SDK X-Ray dapat memberi nama segmen setelah nama host di header permintaan HTTP. Namun, header ini dapat ditiru, yang dapat mengakibatkan simpul tak terduga di peta layanan Anda. Untuk mencegah SDK dari penamaan segmen salah karena permintaan dengan header host palsu, Anda harus menentukan nama default untuk permintaan masuk.
Jika aplikasi Anda menyuguhkan permintaan untuk beberapa domain, Anda dapat mengonfigurasi SDK untuk menggunakan strategi penamaan dinamis untuk mencerminkan ini dalam nama segmen. Strategi penamaan dinamis mengizinkan SDK menggunakan nama host untuk permintaan yang sesuai dengan pola yang diharapkan, dan menerapkan nama default untuk permintaan yang tidak sesuai.
Misalnya, Anda boleh memiliki satu aplikasi yang melayani permintaan untuk tiga subdomain– `www.example.com`, `api.example.com`, dan `static.example.com`. Anda dapat menggunakan strategi penamaan dinamis dengan pola `*.example.com` untuk mengidentifikasi segmen untuk setiap subdomain dengan nama yang berbeda, mengakibatkan tiga simpul layanan pada peta layanan. Jika aplikasi Anda menerima permintaan dengan nama host yang tidak cocok dengan pola, Anda akan melihat simpul keempat pada peta layanan dengan nama fallback yang Anda tentukan.
Untuk menggunakan nama yang sama untuk semua segmen permintaan, tentukan nama aplikasi Anda ketika Anda memulai perangkat tengah, seperti yang ditampilkan dalam bagian sebelumnya.
**catatan**
Anda dapat menimpa nama layanan default yang Anda tentukan dalam kode dengan [variabel lingkungan](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars)`AWS_XRAY_TRACING_NAME`.
Strategi penamaan dinamis menentukan pola yang harus sesuai dengan nama host, dan nama default untuk digunakan jika nama host dalam permintaan HTTP tidak cocok dengan pola. Untuk nama segmen secara dinamis, gunakan `AWSXRay.middleware.enableDynamicNaming`.
**Example app.js - nama segmen dinamis**
Jika nama host dalam permintaan cocok dengan pola `*.example.com`, gunakan nama host. Jika tidak sesuai, gunakan `MyApp`.
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
# Menelusuri panggilan AWS SDK dengan X-Ray SDK untuk 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
[Saat aplikasi Anda melakukan panggilan Layanan AWS untuk menyimpan data, menulis ke antrean, atau mengirim notifikasi, X-Ray SDK untuk Node.js melacak panggilan hilir di subsegmen.](xray-sdk-nodejs-subsegments.md) Ditelusuri Layanan AWS, dan sumber daya yang Anda akses dalam layanan tersebut (misalnya, bucket Amazon S3 atau antrean Amazon SQS), muncul sebagai node hilir pada peta jejak di konsol X-Ray.
Klien AWS SDK instrumen yang Anda buat melalui [AWS SDK untuk JavaScript V2](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html) atau [AWS SDK untuk JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html). Setiap versi AWS SDK menyediakan metode yang berbeda untuk menginstrumentasi klien AWS SDK.
**catatan**
Saat ini, AWS X-Ray SDK untuk Node.js mengembalikan lebih sedikit informasi segmen saat menginstrumentasi klien AWS SDK untuk JavaScript V3, dibandingkan dengan menginstrumentasi klien V2. Misalnya, subsegmen yang mewakili panggilan ke DynamoDB tidak akan mengembalikan nama tabel. Jika Anda memerlukan informasi segmen ini di jejak Anda, pertimbangkan untuk menggunakan AWS SDK untuk JavaScript V2.
------
#### [ AWS SDK untuk JavaScript V2 ]
Anda dapat AWS menginstruksikan semua klien SDK V2 dengan membungkus pernyataan `aws-sdk` require Anda dalam panggilan ke. `AWSXRay.captureAWS`
**Example app.js - AWS Instrumentasi SDK**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
Untuk menginstrumentasi klien individual, bungkus klien AWS SDK Anda dalam panggilan ke`AWSXRay.captureAWSClient`. Misalnya, untuk instrumen klien `AmazonDynamoDB`:
**Example app.js - instrumentasi klien DynamoDB**
```
const AWSXRay = require('aws-xray-sdk');
...
const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```
**Awas**
Jangan gunakan kedua `captureAWS` dan `captureAWSClient` bersama-sama. Hal ini akan menyebabkan duplikat subsegment.
Jika Anda ingin menggunakan [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)dengan [ECMAScriptmodul](https://nodejs.org/api/esm.html) (ESM) untuk memuat JavaScript kode Anda, gunakan contoh berikut untuk mengimpor pustaka:
**Example app.js - AWS Instrumentasi SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Untuk instrumen semua AWS klien dengan ESM, gunakan kode berikut:
**Example app.js - AWS Instrumentasi SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```
Untuk semua layanan, Anda dapat melihat nama API yang dipanggil di konsol X-Ray. Untuk subset layanan, X-Ray SDK menambahkan informasi ke segmen untuk memberikan lebih banyak perincian di peta layanan.
Sebagai contoh, ketika Anda melakukan panggilan dengan klien DynamoDB berinstrumen, SDK menambahkan nama tabel ke segmen untuk panggilan yang menargetkan tabel. Di konsol tersebut, setiap tabel muncul sebagai simpul terpisah di peta layanan, dengan simpul DynamoDB generik untuk panggilan yang tidak menargetkan tabel.
**Example Subsegmen untuk panggilan ke DynamoDB untuk menyimpan item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Ketika Anda mengakses sumber daya bernama, panggilan ke layanan berikut membuat simpul tambahan di peta layanan. Panggilan yang tidak menargetkan sumber daya tertentu membuat simpul generik untuk layanan tersebut.
+ **Amazon DynamoDB** – Nama tabel
+ **Amazon Simple Storage Service** – Bucket dan nama kunci
+ **Amazon Simple Queue Service** – Nama antrean
------
#### [ AWS SDK untuk JavaScript V3 ]
AWS SDK untuk JavaScript V3 bersifat modular, jadi kode Anda hanya memuat modul yang dibutuhkannya. Karena itu, tidak mungkin untuk menginstruksikan semua klien AWS SDK karena V3 tidak mendukung metode ini`captureAWS`.
Jika Anda ingin menggunakan TypeScript ECMAScript Modules (ESM) untuk memuat JavaScript kode Anda, Anda dapat menggunakan contoh berikut untuk mengimpor pustaka:
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Instrumen setiap klien AWS SDK menggunakan `AWSXRay.captureAWSv3Client` metode ini. Misalnya, untuk instrumen klien `AmazonDynamoDB`:
**Example app.js - instrumentasi klien DynamoDB menggunakan SDK untuk Javascript V3**
```
const AWSXRay = require('aws-xray-sdk');
const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));
```
Saat menggunakan AWS SDK untuk JavaScript V3, metadata seperti nama tabel, bucket dan nama kunci, atau nama antrian, saat ini tidak dikembalikan, dan oleh karena itu peta jejak tidak akan berisi node diskrit untuk setiap sumber daya bernama seperti saat menginstrumentasi AWS klien SDK menggunakan V2. AWS SDK untuk JavaScript
**Example Subsegmen untuk panggilan ke DynamoDB untuk menyimpan item, saat menggunakan V3 AWS SDK untuk JavaScript**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
------
# Menelusuri panggilan ke layanan web downstream HTTP menggunakan X-Ray SDK untuk 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
Saat aplikasi Anda melakukan panggilan ke microservices atau HTTP publik APIs, Anda dapat menggunakan klien X-Ray SDK for Node.js untuk instrumen panggilan tersebut dan menambahkan API ke grafik layanan sebagai layanan hilir.
Lewati `http` atau klien `https` untuk X-Ray SDK for Node.js metode `captureHTTPs` untuk menelusuri panggilan keluar.
**catatan**
Panggilan menggunakan pustaka permintaan HTTP pihak ketiga, seperti Axios atau Superagent, didukung melalui [API `captureHTTPsGlobal()`](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) dan masih akan ditelusuri ketika mereka menggunakan asli modul `http`.
**Example app.js - klien HTTP**
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
Untuk mengaktifkan penelusuran pada semua klien HTTP, panggilan `captureHTTPsGlobal` sebelum Anda memuat `http`.
**Example app.js - klien HTTP (global)**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
Ketika Anda instrumen panggilan ke API web hilir, X-Ray SDK for Node.js mencatat subsegmen dengan informasi tentang permintaan HTTP dan respon. X-Ray menggunakan subsegmen untuk membuat segmen disimpulkan untuk API jarak jauh.
**Example Subsegmen untuk panggilan HTTP downstream**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmen yang disimpulkan untuk panggilan HTTP downstream**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Menelusuri kueri SQL dengan X-Ray SDK 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
Instrumen SQL kueri basis data dengan membungkus klien SQL Anda di X-Ray SDK yang sesuai untuk metode klien Node.js.
+ **PostgreSQL** – `AWSXRay.capturePostgres()`
```
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();
```
+ **MySQL** – `AWSXRay.captureMySQL()`
```
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);
```
Ketika Anda menggunakan klien yang diinstrumentasi untuk membuat kueri SQL, X-Ray SDK untuk Node.js mencatat informasi tentang koneksi dan permintaan di subsegmen.
## Termasuk data tambahan dalam SQL subsegmen
Anda dapat menambahkan informasi tambahan ke subsegmen yang dihasilkan untuk kueri SQL, asalkan dipetakan ke bidang SQL yang diizinkan. Misalnya, untuk mencatat string kueri SQL yang disterilkan di subsegmen, Anda dapat menambahkannya langsung ke subsegmen SQL objek.
**Example Tetapkan SQL ke subsegmen**
```
const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);
// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;
if (subs & & subs.length > 0) {
var sqlSub = subs[subs.length - 1];
sqlSub.sql.sanitized_query = queryString;
}
```
*Untuk daftar lengkap bidang SQL yang diizinkan, lihat [Kueri SQL](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql) di Panduan Pengembang.AWS X-Ray *
# Menghasilkan subsegment kustom dengan X-Ray SDK untuk Node.js
Subsegmen memperluas [segmen](xray-concepts.md#xray-concepts-segments) pelacakan dengan detail tentang pekerjaan yang dilakukan untuk melayani permintaan. Setiap kali Anda melakukan panggilan dengan klien berinstrumen, X-Ray tersebut mencatat informasi yang dihasilkan dalam subsegmen. Anda dapat membuat subsegment tambahan untuk mengelompokkan subsegment lain, untuk mengukur performa bagian kode, atau untuk mencatat anotasi dan metadata.
## Subsegmen Express Kustom
**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
Untuk membuat subsegmen kustom untuk fungsi yang membuat panggilan ke layanan hilir, gunakan fungsi `captureAsyncFunc`.
**Example app.js - subsegment Express kustom**
```
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) {
sendRequest(host, function() {
console.log('rendering!');
res.render('index');
subsegment.close();
});
});
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) {
var options = {
host: host,
path: '/',
};
var callback = function(response) {
var str = '';
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
```
Dalam contoh ini, aplikasi membuat subsegmen kustom bernama `send` untuk panggilan ke fungsi `sendRequest`. `captureAsyncFunc` melewati subsegmen yang harus Anda tutup dalam fungsi panggilan balik ketika panggilan asinkron yang dibuatnya selesai.
Untuk fungsi sinkron, Anda dapat menggunakan fungsi `captureFunc`, yang menutup subsegmen secara otomatis segera setelah blok fungsi selesai mengeksekusi.
Ketika Anda membuat subsegmen dalam segmen atau subsegmen lain, X-Ray SDK untuk Node.js menghasilkan ID untuk itu dan mencatat waktu mulai dan waktu berakhir.
**Example Subsegmen dengan metadata**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
## Subsegmen Lambda Kustom
SDK dikonfigurasi untuk secara otomatis membuat segmen fasad placeholder saat mendeteksi itu berjalan di Lambda. Untuk membuat subsegement dasar, yang akan membuat satu `AWS::Lambda::Function` node pada peta jejak X-Ray, panggil dan gunakan kembali segmen fasad. Jika Anda secara manual membuat segmen baru dengan ID baru (saat berbagi ID pelacakan, ID induk, dan sampel keputusan), Anda akan dapat mengirim segmen baru.
**Example app.js - subsegment kustom manual**
```
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically
```
# Tambahkan anotasi dan metadata ke segmen dengan X-Ray SDK 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 mencatat informasi tambahan tentang permintaan, lingkungan, atau aplikasi Anda dengan anotasi dan metadata. Anda dapat menambahkan anotasi dan metadata ke segmen yang dibuat oleh SDK X-Ray, atau subsegmen kustom yang Anda buat.
**Anotasi** adalah pasangan kunci-nilai dengan string, nomor, atau nilai-nilai Boolean. Anotasi diindekskan untuk digunakan dengan [Ekspresi filter](xray-console-filters.md). Gunakan anotasi untuk mencatat data yang ingin Anda gunakan untuk mengelompokkan pelacakan di konsol tersebut, atau saat memanggil API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
**Metadata** adalah pasangan kunci-nilai yang dapat memiliki nilai dari setiap tipe, termasuk objek dan daftar, tetapi tidak diindekskan untuk digunakan dengan ekspresi filter. Gunakan metadata untuk mencatat data tambahan yang ingin disimpan dalam pelacakan tetapi tidak perlu digunakan dengan pencarian.
Selain anotasi dan metadata, Anda juga dapat [mencatat string ID pengguna](#xray-sdk-nodejs-segment-userid) pada segmen. Pengguna IDs direkam dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan pencarian.
**Topics**
+ [Mencatat anotasi dengan X-Ray SDK for Node.js](#xray-sdk-nodejs-segment-annotations)
+ [Mencatat metadata dengan X-Ray SDK for Node.js](#xray-sdk-nodejs-segment-metadata)
+ [Merekam pengguna IDs dengan X-Ray SDK untuk Node.js](#xray-sdk-nodejs-segment-userid)
## Mencatat anotasi dengan X-Ray SDK for Node.js
Gunakan anotasi untuk mencatat informasi pada segmen atau subsegmen yang ingin diindeks untuk pencarian.
**Persyaratan Anotasi**
+ **Tombol** — Kunci untuk anotasi X-Ray dapat memiliki hingga 500 karakter alfanumerik. Anda tidak dapat menggunakan spasi atau simbol selain titik atau titik (.)
+ **Nilai** — Nilai untuk anotasi X-Ray dapat memiliki hingga 1.000 karakter Unicode.
+ Jumlah **Anotasi** — Anda dapat menggunakan hingga 50 anotasi per jejak.
**Untuk mencatat anotasi**
1. Dapatkan referensi ke segmen atau subsegmen saat ini.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Panggil `addAnnotation` dengan kunci String, serta nilai Boolean, Nomor, atau String.
```
document.addAnnotation("mykey", "my value");
```
Contoh berikut menunjukkan cara memanggil `putAnnotation` dengan kunci String yang mencakup titik, dan nilai Boolean, Number, atau String.
```
document.putAnnotation("testkey.test", "my value");
```
SDK mencatat penjelasan sebagai pasangan nilai kunci dalam objek `annotations` di dokumen segmen. Memanggil `addAnnotation` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
Untuk menemukan penelusuran yang memiliki anotasi dengan nilai-nilai tertentu, gunakan kata kunci `annotation[key]` dalam [ekspresi filter](xray-console-filters.md).
**Example app.js - anotasi**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var item = {
'email': {'S': req.body.email},
'name': {'S': req.body.name},
'preview': {'S': req.body.previewAccess},
'theme': {'S': req.body.theme}
};
var seg = AWSXRay.getSegment();
seg.addAnnotation('theme', req.body.theme);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
## Mencatat metadata dengan X-Ray SDK for Node.js
Gunakan metadata untuk mencatat informasi pada segmen atau subsegmen yang tidak perlu diindeks untuk pencarian. Nilai metadata dapat berupa string, angka, Boolean, atau objek yang dapat diserialisasikan ke dalam objek atau baris JSON.
**Untuk mencatat metadata**
1. Dapatkan referensi ke segmen atau subsegmen saat ini.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Panggil `addMetadata` dengan kunci String, Boolean, Nomor, String, atau nilai objek, dan namespace string.
```
document.addMetadata("my key", "my value", "my namespace");
```
atau
Panggil `addMetadata` hanya dengan kunci dan nilai.
```
document.addMetadata("my key", "my value");
```
Jika Anda tidak menentukan namespace, SDK menggunakan `default`. Memanggil `addMetadata` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
## Merekam pengguna IDs dengan X-Ray SDK untuk Node.js
Rekam segmen pengguna IDs berdasarkan permintaan untuk mengidentifikasi pengguna yang mengirim permintaan. Operasi ini tidak kompatibel dengan AWS Lambda fungsi karena segmen di lingkungan Lambda tidak dapat diubah. Panggilan `setUser` dapat diterapkan hanya untuk segmen, bukan subsegment.
**Untuk merekam pengguna IDs**
1. Dapatkan referensi ke segmen atau subsegmen saat ini.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Panggil `setUser()` dengan ID String pengguna yang mengirim permintaan.
```
var user = 'john123';
AWSXRay.getSegment().setUser(user);
```
Anda dapat memanggil `setUser` untuk mencatat ID pengguna segera setelah aplikasi mulai memproses permintaan. Jika Anda akan menggunakan segmen untuk mengatur ID pengguna, Anda dapat mengaitkan panggilan dalam satu baris.
**Example app.js - ID pengguna**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var userId = uuidv4();
var item = {
'userId': {'S': userId},
'email': {'S': req.body.email},
'name': {'S': req.body.name}
};
var seg = AWSXRay.getSegment().setUser(userId);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
Untuk menemukan penelusuran pada ID pengguna, gunakan kata kunci `user` dalam [ekspresi filter](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html).