Menginstrumentasi Node.js kode di AWS Lambda

Lambda terintegrasi dengan AWS X-Ray untuk membantu Anda melacak, men-debug, dan mengoptimalkan aplikasi Lambda. Anda dapat menggunakan X-Ray untuk melacak permintaan saat melintasi sumber daya dalam aplikasi Anda, yang mungkin termasuk fungsi Lambda dan layanan lainnya. AWS

Untuk mengirim data penelusuran X-Ray, Anda dapat menggunakan salah satu dari dua pustaka SDK:

• AWS Distro for OpenTelemetry (ADOT) — Distribusi SDK (OTel) yang aman, siap produksi, dan AWS didukung. OpenTelemetry

• AWS X-Ray SDK for Node.js— SDK untuk menghasilkan dan mengirim data jejak ke X-Ray.

Setiap SDK menawarkan cara untuk mengirim data telemetri Anda ke layanan. X-Ray Anda kemudian dapat menggunakan X-Ray untuk melihat, memfilter, dan mendapatkan wawasan tentang metrik kinerja aplikasi Anda untuk mengidentifikasi masalah dan peluang untuk pengoptimalan.

penting

The X-Ray dan Powertools untuk AWS Lambda SDK adalah bagian dari solusi instrumentasi terintegrasi ketat yang ditawarkan oleh. AWS Lapisan Lambda ADOT adalah bagian dari standar industri untuk melacak instrumentasi yang mengumpulkan lebih banyak data secara umum, tetapi mungkin tidak cocok untuk semua kasus penggunaan. Anda dapat menerapkan penelusuran ujung ke ujung dalam X-Ray menggunakan salah satu solusi. Untuk mempelajari lebih lanjut tentang memilih di antara keduanya, lihat Memilih antara AWS Distro untuk Telemetri Terbuka dan SDK. X-Ray

Menggunakan ADOT untuk instrumen fungsi Anda Node.js

ADOT menyediakan lapisan Lambda yang dikelola sepenuhnya yang mengemas semua yang Anda butuhkan untuk mengumpulkan data telemetri menggunakan OTel SDK. Dengan menggunakan lapisan ini, Anda dapat menginstruksikan fungsi Lambda Anda tanpa harus memodifikasi kode fungsi apa pun. Anda juga dapat mengonfigurasi lapisan Anda untuk melakukan inisialisasi khusus OTel. Untuk informasi selengkapnya, lihat Konfigurasi khusus untuk Kolektor ADOT di Lambda dalam dokumentasi ADOT.

Untuk Node.js runtime, Anda dapat menambahkan layer Lambda AWS terkelola untuk ADOT Javascript untuk menginstruksikan fungsi Anda secara otomatis. Untuk petunjuk rinci tentang cara menambahkan layer ini, lihat AWS Distro untuk OpenTelemetry Lambda JavaScript Support untuk dalam dokumentasi ADOT.

Menggunakan X-Ray SDK untuk menginstruksikan fungsi Anda Node.js

Untuk merekam detail tentang panggilan yang dilakukan oleh Fungsi Peristiwa Lambda ke sumber daya lain dalam aplikasi, Anda juga dapat menggunakan. AWS X-Ray SDK for Node.js Untuk mendapatkan SDK, tambahkan paket aws-xray-sdk-core ke dependensi aplikasi Anda.

contoh kosong- nodejs/package .json

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "jest": "29.7.0"
  },
  "dependencies": {
    "@aws-sdk/client-lambda": "3.345.0",
    "aws-xray-sdk-core": "3.5.3"
  },
  "scripts": {
    "test": "jest"
  }
}

Untuk AWS menginstrumentasikan klien SDK di AWS SDK untuk JavaScript v3, bungkus instance klien dengan metode. captureAWSv3Client

contoh kosong- nodejs/function /index.js — Menelusuri AWS Klien SDK

const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

// Handler
exports.handler = async function(event, context) {
    event.Records.forEach(record => {
  ...

Runtime Lambda menetapkan beberapa variabel lingkungan untuk mengonfigurasi SDK. X-Ray Misalnya, Lambda disetel AWS_XRAY_CONTEXT_MISSING LOG_ERROR untuk menghindari kesalahan runtime dari SDK. X-Ray Untuk menetapkan strategi yang hilang dalam konteks khusus, timpa variabel lingkungan dalam konfigurasi fungsi Anda agar tidak memiliki nilai, lalu Anda dapat menetapkan konteks yang tidak memiliki strategi yang terprogram.

contoh Kode inisialisasi contoh

const AWSXRay = require('aws-xray-sdk-core');

// Configure the context missing strategy to do nothing
AWSXRay.setContextMissingStrategy(() => {});

Untuk informasi selengkapnya, lihat Bekerja dengan variabel lingkungan Lambda.

Setelah Anda menambahkan dependensi yang benar dan membuat perubahan kode yang diperlukan, aktifkan penelusuran dalam konfigurasi fungsi Anda melalui konsol Lambda atau API.

Mengaktifkan penelusuran dengan konsol Lambda

Untuk mengaktifkan penelusuran aktif di Fungsi Peristiwa Lambda Anda dengan konsol, ikuti langkah-langkah berikut:

Untuk mengaktifkan penelusuran aktif

1. Buka halaman Fungsi Acara konsol Lambda.

2. Pilih Fungsi Acara.

3. Pilih Konfigurasi dan kemudian pilih Alat Pemantauan dan operasi.

4. Di bawah Alat pemantauan tambahan, pilih Edit.

5. Di bawah Sinyal CloudWatch Aplikasi dan AWS X-Ray, pilih Aktifkan untuk jejak layanan Lambda.

6. Pilih Simpan.

Mengaktifkan penelusuran dengan Lambda API

Konfigurasikan penelusuran pada fungsi Lambda Anda dengan AWS CLI AWS atau SDK, gunakan operasi API berikut:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Contoh AWS CLI perintah berikut memungkinkan penelusuran aktif pada fungsi bernama my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

Mode penelusuran adalah bagian dari konfigurasi khusus versi saat Anda mempublikasikan versi fungsi Anda. Anda tidak dapat mengubah mode pelacakan pada versi yang telah diterbitkan.

Mengaktifkan penelusuran dengan CloudFormation

Untuk mengaktifkan penelusuran pada AWS::Lambda::Function sumber daya dalam CloudFormation templat, gunakan TracingConfig properti.

contoh fungsi-inline.yml. — Konfigurasi penelusuran

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Untuk sumber AWS::Serverless::Function daya AWS Serverless Application Model (AWS SAM), gunakan Tracing properti.

contoh template.yml — Konfigurasi penelusuran

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Menafsirkan jejak X-Ray

Fungsi Acara Anda memerlukan izin untuk mengunggah data jejak ke X-Ray. Saat Anda mengaktifkan penelusuran di konsol Lambda, Lambda menambahkan izin yang diperlukan ke peran eksekusi Fungsi Acara Anda. Atau, tambahkan kebijakan AWSXRayDaemonWriteAccess ke peran eksekusi.

Setelah mengonfigurasi penelusuran aktif, Anda dapat mengamati permintaan tertentu melalui aplikasi Anda. Grafik X-Ray layanan menunjukkan informasi tentang aplikasi Anda dan semua komponennya. Contoh berikut menunjukkan aplikasi dengan dua fungsi. Fungsi utama memproses kejadian dan terkadang mengembalikan kesalahan. Fungsi kedua di bagian atas memproses kesalahan yang muncul di grup log pertama dan menggunakan AWS SDK untuk memanggil X-Ray, Amazon Simple Storage Service (Amazon S3) Service, dan Amazon Logs. CloudWatch

X-Ray tidak melacak semua permintaan ke aplikasi Anda. X-Ray menerapkan algoritma pengambilan sampel untuk memastikan bahwa penelusuran efisien, sambil tetap memberikan sampel yang representatif dari semua permintaan. Tingkat pengambilan sampel adalah 1 permintaan per detik dan 5 persen dari permintaan tambahan. Anda tidak dapat mengonfigurasi laju X-Ray pengambilan sampel untuk fungsi Anda.

Di X-Ray, jejak mencatat informasi tentang permintaan yang diproses oleh satu atau beberapa layanan. Lambda mencatat 2 segmen per jejak, yang menciptakan dua node pada grafik layanan. Gambar berikut menyoroti dua node ini:

Node pertama di sebelah kiri mewakili layanan Lambda, yang menerima permintaan pemanggilan. Node kedua mewakili fungsi Lambda spesifik Anda. Contoh berikut menunjukkan jejak dengan dua segmen ini. Keduanya bernama fungsi saya, tetapi yang satu memiliki asal AWS::Lambda dan yang lainnya memiliki asal usul. AWS::Lambda::Function Jika AWS::Lambda segmen menunjukkan kesalahan, layanan Lambda mengalami masalah. Jika AWS::Lambda::Function segmen menunjukkan kesalahan, fungsi Anda mengalami masalah.

Contoh ini memperluas AWS::Lambda::Function segmen untuk menunjukkan tiga subsegmennya.

catatan

AWS saat ini menerapkan perubahan pada layanan Lambda. Karena perubahan ini, Anda mungkin melihat perbedaan kecil antara struktur dan konten pesan log sistem dan segmen jejak yang dipancarkan oleh Fungsi Peristiwa Lambda yang berbeda di Anda. Akun AWS

Contoh jejak yang ditunjukkan di sini menggambarkan segmen fungsi gaya lama. Perbedaan antara segmen gaya lama dan baru dijelaskan dalam paragraf berikut.

Perubahan ini akan diterapkan selama beberapa minggu mendatang, dan semua fungsi di semua Wilayah AWS kecuali China GovCloud dan wilayah akan bertransisi untuk menggunakan pesan log format baru dan segmen pelacakan.

Segmen fungsi gaya lama berisi subsegmen berikut:

• Inisialisasi – Mewakili waktu yang dihabiskan untuk memuat fungsi dan menjalankan kode inisialisasi. Subsegmen ini hanya muncul untuk peristiwa pertama yang diproses oleh setiap instance fungsi Anda.

• Doa - Merupakan waktu yang dihabiskan untuk menjalankan kode handler Anda.

• Overhead - Merupakan waktu yang dihabiskan runtime Lambda untuk mempersiapkan diri untuk menangani acara berikutnya.

Segmen fungsi gaya baru tidak berisi subsegmen. Invocation Sebagai gantinya, subsegmen pelanggan dilampirkan langsung ke segmen fungsi. Untuk informasi lebih lanjut tentang struktur segmen fungsi gaya lama dan baru, lihat. Memahami X-Ray jejak

Anda juga dapat melakukan instrumentasi klien HTTP, merekam kueri SQL, dan membuat subsegmen khusus dengan anotasi dan metadata. Untuk informasi selengkapnya, lihat AWS X-Ray SDK for Node.jsdi Panduan AWS X-Ray Pengembang.

Harga

Anda dapat menggunakan X-Ray tracing gratis setiap bulan hingga batas tertentu sebagai bagian dari Tingkat AWS Gratis. Di luar ambang batas itu, X-Ray biaya untuk penyimpanan dan pengambilan jejak. Untuk informasi selengkapnya, lihat harga AWS X-Ray.

Menyimpan dependensi runtime dalam lapisan (SDK) X-Ray

Jika Anda menggunakan X-Ray SDK untuk menginstruksikan klien AWS SDK kode fungsi Anda, paket penerapan Anda bisa menjadi cukup besar. Untuk menghindari mengunggah dependensi runtime setiap kali Anda memperbarui kode fungsi, paketkan X-Ray SDK dalam lapisan Lambda.

Contoh berikut menunjukkan AWS::Serverless::LayerVersion sumber daya yang menyimpan file AWS X-Ray SDK for Node.js.

contoh template.yml - Lapisan Dependensi

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs24.x

Dengan konfigurasi ini, Anda memperbarui lapisan pustaka hanya jika Anda mengubah dependensi runtime Anda. Karena paket penerapan fungsi hanya berisi kode Anda, ini dapat membantu mengurangi waktu upload.

Membuat lapisan untuk dependensi memerlukan perubahan build untuk menghasilkan arsip lapisan sebelum penerapan. Untuk contoh pekerjaan, lihat contoh aplikasi blank-nodejs.