AWS X-Ray SDK untuk Node.js - AWS X-Ray
PersyaratanManajemen dependensiSampel Node.jsKonfigurasiPermintaan masukPanggilan HTTP keluarKueri SQLSubsegmen kustomAnotasi dan metadata

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

AWS X-Ray SDK untuk Node.js

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-xray-sdk-node

Jika Anda menggunakan Express, mulai dengan menambahkan SDK sebagai middleware pada server aplikasi Anda untuk pelacakan permintaan masuk. Middleware membuat segmen 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 dan pelacakan sampel permintaan secara otomatis. Untuk fungsi lainnya, Anda dapat mengonfigurasi Lambda 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 untuk informasi selengkapnya.

Selanjutnya, gunakan X-Ray SDK untuk Node.js untuk instrumen AWS SDK Anda JavaScript di klien Node.js. 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 API web HTTP dan kueri SQL. Bungkus klien HTTP Anda dalam metode penangkapan SDK untuk mencatat informasi tentang panggilan HTTP keluar. Untuk klien SQL, menggunakan metode penangkapan untuk tipe basis data Anda.

Middleware menerapkan aturan pengambilan sampel ke permintaan masuk untuk menentukan permintaan yang dilacak. Anda dapat mengonfigurasi X-Ray SDK untuk Node.js 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. Anotasi adalah pasangan kunci-nilai sederhana yang diindeks untuk digunakan dengan ekspresi filter, 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. 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.

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.

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.

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.

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, 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.

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. 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 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()

Pencatatan log

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-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 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.

Menelusuri permintaan yang masuk dengan X-Ray SDK for Node.js

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.

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.

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.

contoh 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.

contoh 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, API eksternal, 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.

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 lingkunganAWS_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.

contoh 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 ke layanan web downstream HTTP menggunakan X-Ray SDK untuk Node.js

Ketika aplikasi Anda membuat panggilan ke layanan mikro atau HTTP API publik, Anda dapat menggunakan X-Ray SDK for Node.js klien 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() dan masih akan ditelusuri ketika mereka menggunakan asli modul http.

contoh 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.

contoh 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.

contoh 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
    }
  }
}
contoh 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

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.

contoh 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 bagian Kueri SQL di bagian. Dokumen segmen X-Ray

Menghasilkan subsegment kustom dengan X-Ray SDK untuk Node.js

Subsegmen memperluas segmen 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

Untuk membuat subsegmen kustom untuk fungsi yang membuat panggilan ke layanan hilir, gunakan fungsi captureAsyncFunc.

contoh 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.

contoh 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.

contoh 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

Anda dapat menggunakan anotasi dan metadata untuk merekam informasi tambahan tentang permintaan, lingkungan, atau aplikasi Anda. 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. Gunakan anotasi untuk mencatat data yang ingin Anda gunakan untuk mengelompokkan pelacakan di konsol tersebut, atau saat memanggil API GetTraceSummaries.

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 pada segmen. ID Pengguna dicatat dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan penelusuran.

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 simbol garis bawah (_).

  • 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();

  2. Panggil addAnnotation dengan kunci String, serta nilai Boolean, Nomor, atau String.

    document.addAnnotation("mykey", "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 annotations.key dalam ekspresi filter.

contoh 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();

  2. 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.

Mencatat ID pengguna dengan X-Ray SDK for Node.js

Catat ID pengguna pada segmen 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 mencatat ID pengguna

  1. Dapatkan referensi ke segmen atau subsegmen saat ini.

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

  2. 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.

contoh 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.