Instal probe Node.js secara manual - Cloud Monitor - Alibaba Cloud Documentation Center

Setelah Anda menginstal probe Node.js, ARMS mulai memantau aplikasi Anda. Anda dapat melihat data penting, termasuk topologi aplikasi, jejak (traces), dan analisis SQL. Topik ini menjelaskan cara menginstal probe Node.js secara manual untuk aplikasi Node.js.

Prasyarat

Lingkungan build Anda harus dapat terhubung ke internet publik atau jaringan internal Alibaba Cloud. Security group-nya harus mengizinkan lalu lintas TCP keluar pada Port 80 dan 443.
Verifikasi versi Node.js Anda. Kami merekomendasikan menggunakan Node.js 14.x atau yang lebih baru.
Pastikan proyek Anda menggunakan alat manajemen paket seperti npm, yarn, atau pnpm.

Catatan penggunaan

Jika aplikasi Anda menggunakan framework yang didukung, seperti Express, Koa, atau Fastify, probe akan mendeteksinya secara otomatis dan melakukan instrumentasi non-intrusif.
Untuk aplikasi dengan skrip startup kustom, pastikan probe dimuat dengan benar sebelum aplikasi dimulai.
Jika aplikasi Anda menggunakan cluster mode, pastikan probe dimuat dengan benar di setiap proses worker.

Langkah 1: Instal SDK probe

Pilih metode instalasi:

Instal dari repositori npm: npm install @loongsuite/cms_node_sdk.
Instal dengan yarn: yarn add @loongsuite/cms_node_sdk.
Instal dengan pnpm: pnpm add @loongsuite/cms_node_sdk.

Langkah 2: Konfigurasi variabel lingkungan

Tambahkan secara manual variabel lingkungan berikut ke aplikasi Node.js Anda:

# Metode 1: Tambahkan variabel lingkungan untuk semua proses di shell saat ini
export ARMS_APP_NAME=your-app-name   # Nama aplikasi Anda.
export ARMS_REGION_ID=your-region-id   # ID wilayah untuk Akun Alibaba Cloud Anda.
export ARMS_LICENSE_KEY=your-license-key   # Kunci lisensi Alibaba Cloud Anda.

# Metode 2: Tambahkan variabel lingkungan untuk proses tertentu
ARMS_APP_NAME=your-app-name ARMS_REGION_ID=your-region-id ARMS_LICENSE_KEY=your-license-key node -r @loongsuite/cms_node_sdk/register app.js

Anda dapat memperoleh kunci lisensi melalui OpenAPI atau dari Pusat Integrasi di Konsol CMS 2.0.

Instal di lingkungan Docker (opsional)

Untuk lingkungan Docker, modifikasi Dockerfile Anda berdasarkan contoh berikut.

# Tambahkan variabel lingkungan
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## Lingkungan Anda yang sudah ada

Langkah 3: Inisialisasi probe

SDK Node.js mendukung dua mode. Pilih salah satu sesuai kebutuhan Anda:

Pendekatan pemrograman

Inisialisasi SDK langsung dalam kode Anda. Anda harus menyediakan informasi berikut di file titik masuk (entry point) aplikasi Anda:

serviceName: Nama aplikasi Anda (wajib).
licenseKey: Kunci lisensi Alibaba Cloud Anda (wajib).
regionId: ID wilayah Alibaba Cloud Anda (wajib), seperti cn-hangzhou atau cn-shanghai.

Pendekatan CommonJS:

// Harus menjadi baris pertama di app.js atau index.js
const { NodeSDK } = require('@loongsuite/cms_node_sdk');

// Inisialisasi SDK (licenseKey, serviceName, dan regionId wajib)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Nama aplikasi
  licenseKey: 'your-license-key',      // Dapatkan dari Konsol ARMS
  regionId: 'cn-hangzhou',             // Wilayah Alibaba Cloud Anda
  // workspace: 'your-workspace',      // Opsional: ruang kerja
});

// Jalankan SDK
sdk.start();

// Kode aplikasi Anda dimulai di sini
const express = require('express');
const app = express();
// ... kode lainnya

Pendekatan ES Module:

// Harus menjadi baris pertama di app.mjs atau index.mjs
import { NodeSDK } from '@loongsuite/cms_node_sdk';

// Inisialisasi SDK (licenseKey, serviceName, dan regionId wajib)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Nama aplikasi
  licenseKey: 'your-license-key',      // Dapatkan dari Konsol ARMS
  regionId: 'cn-hangzhou',             // Wilayah Alibaba Cloud Anda
  // workspace: 'your-workspace',      // Opsional: ruang kerja
});

// Jalankan SDK
sdk.start();

// Kode aplikasi Anda dimulai di sini
import express from 'express';
const app = express();
// ... kode lainnya

Penting:

Parameter serviceName, licenseKey, dan regionId wajib diisi.
Anda harus memanggil sdk.start() sebelum mengimpor modul aplikasi lainnya (seperti express atau mysql) agar instrumentasi otomatis berfungsi dengan benar.

Injeksi otomatis

Untuk instrumentasi tanpa kode (codeless), konfigurasikan SDK dengan variabel lingkungan dan muat sebelumnya (preload) saat startup menggunakan flag -r.

Mode ini menggunakan variabel lingkungan yang dikonfigurasi di Langkah 2, sehingga tidak diperlukan perubahan kode.

Langkah 4: Jalankan aplikasi

Jalankan aplikasi dalam mode pemrograman

Jika Anda menggunakan mode pemrograman (Mode 1), jalankan aplikasi Anda dengan perintah standar:

node app.js

Jalankan aplikasi menggunakan injeksi otomatis (mode register)

Jika Anda menggunakan mode register (Mode 2 di Langkah 3), muat probe sebelumnya dengan menggunakan flag -r Node.js:

node -r @loongsuite/cms_node_sdk/register app.js

Flag -r menginisialisasi probe Node.js ARMS dan mengaktifkan instrumentasi non-intrusif.

Jalankan aplikasi dengan loader ESM (proyek ESM)

Jika proyek Anda menggunakan ES module, Anda dapat menggunakan loader Node.js untuk secara otomatis menginjeksi SDK selama fase pemuatan modul:

node --experimental-loader=@loongsuite/cms_node_sdk/import-hooks app.mjs

Metode ini cocok untuk proyek ESM murni dan memerlukan penambahan flag --experimental-loader pada perintah startup.

Verifikasi instalasi

Sekitar satu menit kemudian, verifikasi bahwa aplikasi Anda muncul di Konsol ARMS di bawah Pemantauan Aplikasi > Daftar Aplikasi. Instalasi berhasil jika aplikasi terdaftar dan melaporkan data.

Konfigurasi lanjutan

Konfigurasi kustom

Anda juga dapat menyesuaikan perilaku probe secara pemrograman:

const { NodeSDK } = require('@loongsuite/cms_node_sdk');

const sdk = new NodeSDK({
  serviceName: 'my-custom-service',
  licenseKey: 'your-license-key',
  regionId: 'cn-hangzhou',
  workspace: 'your-workspace',
  // Konfigurasi kustom lainnya, seperti kebijakan pengambilan sampel atau eksporter kustom
});

sdk.start();

Konfigurasi dengan variabel lingkungan (mode register)

Saat menggunakan mode register, variabel lingkungan berikut didukung:

Parameter	Deskripsi	Wajib
`ARMS_APP_NAME`	Nama aplikasi	Ya
`ARMS_LICENSE_KEY`	Kunci lisensi ARMS	Ya
`ARMS_REGION_ID`	ID wilayah ARMS (contoh: cn-hangzhou)	Ya
`ARMS_WORKSPACE`	Ruang kerja ARMS	Tidak
`CMS_ENABLE_CONSOLE_EXPORTER`	Mengaktifkan console exporter. Nilai yang valid: `true`, `false`.	Tidak
`CMS_OTLP_ENDPOINT`	URL endpoint ekspor OTLP.	Tidak
`OTEL_LOG_LEVEL`	Mengatur tingkat log probe. Nilai yang valid: `debug`, `info`, `warn`, `error`.	Tidak. Default: `info`.

FAQ

Apakah probe memengaruhi performa aplikasi?

Dirancang untuk overhead minimal, dampak performa probe biasanya kurang dari 5%.

Framework Node.js apa saja yang didukung?

Probe mendukung framework web Node.js utama seperti Express, Koa, Fastify, Hapi, dan Restify, serta klien database untuk MySQL, PostgreSQL, Redis, dan MongoDB.

Apakah SDK harus diimpor terlebih dahulu?

Ya. Anda harus memanggil sdk.start() atau menggunakan flag preload -r sebelum mengimpor modul aplikasi lainnya (seperti express atau mysql). Jika tidak, instrumentasi otomatis akan gagal untuk modul-modul tersebut.

Bagaimana cara menonaktifkan probe?

Untuk mematikan probe secara graceful, panggil metode sdk.shutdown(). Jika Anda menggunakan mode register, probe akan dimatikan secara otomatis saat proses berakhir.

Apakah TypeScript didukung?

Ya. SDK ditulis dalam TypeScript dan mencakup definisi tipe lengkap.

Dapatkah saya mengunci versi probe?

Ya. Anda dapat menginstal versi tertentu dari probe dengan menjalankan perintah berikut:

npm install @loongsuite/cms_node_sdk@<version>

Ganti <version> dengan nomor versi aktual.