Pantau Node.js layanan dan aplikasi Anda dengan Application Insights

Application Insights memantau komponen Anda setelah penyebaran untuk menemukan masalah performa dan masalah lain. Anda dapat menggunakan Application Insights untuk layanan Node.js yang di-hosting di pusat data, Azure VM, dan aplikasi web Anda, dan bahkan di cloud publik lainnya.

Untuk menerima, menyimpan, dan menjelajahi data pemantauan Anda, sertakan SDK dalam kode Anda. Kemudian siapkan sumber daya Application Insights yang sesuai di Azure. SDK akan mengirimkan data ke sumber daya tersebut untuk analisis dan eksplorasi lebih lanjut.

Pustaka klien Node.js dapat secara otomatis memantau permintaan HTTP masuk dan keluar, pengecualian, dan beberapa metrik sistem. Mulai versi 0.20, pustaka klien juga dapat memantau beberapa paket pihak ketiga yang umum, seperti MongoDB, MySQL, dan Redis.

Semua peristiwa yang terkait dengan permintaan HTTP masuk dikorelasikan untuk pemecahan masalah yang lebih cepat.

Anda dapat menggunakan API TelemetryClient untuk melakukan instrumentasi dan memantau aspek tambahan aplikasi dan sistem secara manual. Kami akan menjelaskan API TelemetryClient secara lebih rinci nanti di artikel ini.

Memulai

Selesaikan tugas berikut untuk menyiapkan pemantauan aplikasi atau layanan.

Prasyarat

Sebelum memulai, pastikan Anda memiliki langganan Azure, atau dapatkan langganan baru secara gratis. Jika organisasi Anda sudah memiliki langganan Azure, admin bisa mengikuti instruksi ini untuk menambahkan Anda ke langganan tersebut.

Siapkan sumber daya Application Insights

1. Masuk ke portal Azure.
2. Buat sumber daya Application Insights.

Menyiapkan pustaka klien Node.js

Sertakan SDK di aplikasi Anda sehingga dapat mengumpulkan data.

1. Salin string koneksi sumber daya Anda dari sumber daya baru Anda. Application Insights akan menggunakan string koneksi untuk memetakan data ke sumber daya Azure Anda. Sebelum SDK dapat menggunakan string koneksi, Anda harus menentukan string koneksi dalam variabel lingkungan atau dalam kode Anda.

   

2. Tambahkan pustaka klien Node.js ke dependensi aplikasi Anda melalui package.json. Dari folder akar aplikasi Anda, jalankan:

   npm install applicationinsights --save
   

   Catatan

   Jika Anda menggunakan TypeScript, jangan instal paket "pengetikan" terpisah. Paket NPM ini berisi pengetikan bawaan.

3. Muat pustaka secara eksplisit di kode Anda. Karena SDK memasukkan instrumentasi ke dalam banyak pustaka lain, muat pustaka sedini mungkin, bahkan sebelum pernyataan require lain.

   let appInsights = require('applicationinsights');
   

4. Anda juga dapat memberikan string koneksi melalui variabel APPLICATIONINSIGHTS_CONNECTION_STRINGlingkungan , alih-alih meneruskannya secara manual ke setup() atau new appInsights.TelemetryClient(). Praktik ini memungkinkan Anda untuk menjauhkan string koneksi dari kode sumber yang diterapkan, dan Anda dapat menentukan string koneksi yang berbeda untuk lingkungan yang berbeda pula. Untuk mengonfigurasi secara manual, panggil appInsights.setup('[your connection string]');.

   Untuk opsi konfigurasi tambahan, lihat bagian berikut ini.

   Anda dapat mencoba SDK tanpa mengirim telemetri dengan mengatur appInsights.defaultClient.config.disableAppInsights = true.

5. Mulai kumpulkan dan kirim data secara otomatis dengan melakukan panggilan appInsights.start();.

Memantau aplikasi Anda

SDK secara otomatis mengumpulkan telemetri tentang runtime Node.js dan beberapa modul pihak ketiga yang umum. Gunakan aplikasi Anda untuk membuat beberapa data ini.

Lalu, di portal Azure buka sumber daya Application Insights yang Anda buat sebelumnya. Di Garis waktu ringkasan, cari beberapa titik data pertama Anda. Untuk melihat data yang lebih rinci, pilih komponen lain di bagan.

Untuk melihat topologi yang ditemukan untuk aplikasi, Anda dapat menggunakan Peta Aplikasi.

Tidak ada data

Karena SDK membatch data untuk pengiriman, mungkin ada penundaan sebelum item muncul di portal. Jika Anda tidak melihat data di sumber daya, cobalah beberapa perbaikan berikut:

• Lanjutkan menggunakan aplikasi. Lakukan lebih banyak tindakan untuk menghasilkan lebih banyak telemetri.
• Klik Refresh di tampilan sumber daya portal. Bagan me-refresh sendiri secara berkala, tetapi me-refresh secara manual akan memaksanya untuk segera me-refresh.
• Pastikan port keluar yang diperlukan terbuka.
• Gunakan Pencarian untuk mencari peristiwa tertentu.
• Periksa FAQ.

Penggunaan dasar

Untuk kumpulan permintaan HTTP out-of-the-box, peristiwa pustaka pihak ketiga yang populer, pengecualian yang tidak tertangani, dan metrik sistem:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Muat pustaka require("applicationinsights") Application Insights sedini mungkin dalam skrip Anda sebelum Anda memuat paket lain. Langkah ini diperlukan agar pustaka Application Insights dapat menyiapkan paket yang akan datang untuk pelacakan. Jika Anda mengalami konflik dengan pustaka lain yang melakukan persiapan serupa, coba muat pustaka Application Insights setelah itu.

Karena cara JavaScript dalam menangani panggilan balik, ada pekerjaan tambahan yang diperlukan untuk melacak permintaan di seluruh dependensi eksternal dan panggilan balik yang akan datang. Secara default, pelacakan tambahan ini diaktifkan. Nonaktifkan dengan memanggil seperti yang setAutoDependencyCorrelation(false) dijelaskan di bagian konfigurasi SDK.

Migrasi dari versi sebelum 0.22

Ada perubahan mencolok antara rilis sebelum versi 0.22 dan setelahnya. Perubahan ini dirancang untuk menghadirkan konsistensi dengan Application Insights SDK lainnya dan memungkinkan ekstensibilitas di masa mendatang.

Secara umum, Anda dapat bermigrasi dengan tindakan berikut:

• Ganti referensi ke appInsights.client dengan appInsights.defaultClient.
• Ganti referensi ke appInsights.getClient() dengan new appInsights.TelemetryClient().
• Ganti semua argumen ke metode client.track* dengan satu objek yang berisi properti bernama sebagai argumen. Lihat petunjuk jenis bawaan IDE atau TelemetryTypes untuk objek yang dikecualikan untuk setiap jenis telemetri.

Jika Anda mengakses fungsi konfigurasi SDK tanpa menautkannya ke appInsights.setup(), Anda sekarang dapat menemukan fungsi-fungsi ini di appInsights.Configurations. Contohnya appInsights.Configuration.setAutoCollectDependencies(true). Tinjau perubahan pada konfigurasi default di bagian berikutnya.

Konfigurasi SDK

Objek appInsights menyediakan sejumlah metode konfigurasi. Metode tersebut tercantum dalam cuplikan berikut dengan nilai default-nya.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Untuk menghubungkan peristiwa sepenuhnya dalam layanan, pastikan mengatur .setAutoDependencyCorrelation(true). Dengan kumpulan opsi ini, SDK dapat melacak konteks di seluruh panggilan balik asinkron di Node.js.

Tinjau deskripsi mereka dalam petunjuk jenis bawaan IDE Anda atau applicationinsights.ts untuk informasi terperinci dan argumen sekunder opsional.

Pengambilan sampel

Secara default, SDK mengirimkan semua data yang dikumpulkan ke layanan Application Insights. Jika Anda ingin mengaktifkan pengambilan sampel untuk mengurangi jumlah data, atur bidang samplingPercentage pada objek config klien. Pengaturan samplingPercentage ke 100 (default) berarti semua data akan dikirim, dan 0 berarti tidak ada yang akan dikirim.

Jika Anda menggunakan korelasi otomatis, semua data yang terkait dengan satu permintaan disertakan atau dikecualikan sebagai unit.

Tambahkan kode seperti berikut ini untuk mengaktifkan pengambilan sampel:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Beberapa peran untuk aplikasi multi-komponen

Dalam beberapa skenario, aplikasi Anda mungkin terdiri dari beberapa komponen yang ingin Anda instrumen semua dengan string koneksi yang sama. Anda masih ingin melihat komponen-komponen ini sebagai unit terpisah di portal, seolah-olah mereka menggunakan string koneksi terpisah. Contohnya adalah simpul terpisah di Peta Aplikasi. Anda perlu mengonfigurasi RoleName bidang secara manual untuk membedakan telemetri satu komponen dari komponen lain yang mengirim data ke sumber daya Application Insights Anda.

Gunakan kode berikut untuk mengatur RoleName bidang:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Browser SDK Loader

Instrumentasi web otomatis dapat diaktifkan untuk server simpul melalui injeksi Skrip Pemuat SDK JavaScript (Web) berdasarkan konfigurasi.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

atau dengan mengatur variabel APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = truelingkungan .

Instrumentasi Web diaktifkan pada respons server simpul ketika semua persyaratan berikut terpenuhi:

• Respons memiliki kode 200status .
• Metode respons adalah GET.
• Respons server memiliki Content-Type html.
• Respons server berisi dan <head> </head> Tag.
• Jika respons dikompresi, respons hanya boleh memiliki satu Content-Encoding jenis, dan jenis pengodean harus salah satu dari gzip, br atau deflate.
• Respons tidak berisi titik akhir CDN Instrumentasi web /cadangan saat ini. (titik akhir CDN Instrumentasi Web saat ini dan cadangan di sini)

titik akhir CDN Instrumentasi web dapat diubah dengan mengatur variabel APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"lingkungan . string koneksi Instrumentasi web dapat diubah dengan mengatur variabel lingkunganAPPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Instrumentasi pihak ketiga otomatis

Untuk melacak konteks di seluruh panggilan asinkron, beberapa perubahan diperlukan di pustaka pihak ketiga, seperti MongoDB dan Redis. Secara default, Application Insights diagnostic-channel-publishers menggunakan untuk monyet-patch beberapa pustaka ini. Fitur ini dapat dinonaktifkan dengan mengatur variabel lingkungan APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

Patch monyet individual dapat dinonaktifkan dengan mengatur APPLICATION_INSIGHTS_NO_PATCH_MODULES variabel lingkungan ke daftar paket yang dipisahkan koma untuk dinonaktifkan. Misalnya, gunakan APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis untuk menghindari patching console paket dan redis .

Saat ini, sembilan paket diinstrumentasikan: bunyan,console,,mongodb,mongodb-core,mysql,redis,winston,pg dan pg-pool. Untuk informasi tentang versi mana dari paket ini yang di-patch, lihat README diagnostic-channel-publishers.

Patch bunyan, , dan console menghasilkan peristiwa pelacakan Application Insights berdasarkan apakah setAutoCollectConsole winstondiaktifkan. Sisanya menghasilkan peristiwa dependensi Application Insights berdasarkan apakah setAutoCollectDependencies diaktifkan.

Metrik langsung

Untuk mengaktifkan pengiriman metrik langsung dari aplikasi Anda ke Azure, gunakan setSendLiveMetrics(true). Saat ini, pemfilteran metrik langsung di portal tidak didukung.

Metrik yang diperpanjang

Untuk mengaktifkan pengiriman metrik native yang diperpanjang dari aplikasi Anda ke Azure, instal paket metrik asli terpisah. SDK secara otomatis dimuat saat diinstal dan mulai mengumpulkan metrik asli Node.js.

npm install applicationinsights-native-metrics

Saat ini, paket metrik asli melakukan autocollection waktu CPU pengumpulan sampah, kotak centang loop peristiwa, dan penggunaan heap:

• Pengumpulan sampah: Jumlah waktu CPU yang digunakan untuk setiap jenis pengumpulan sampah, dan berapa banyak kejadian dari setiap jenis.
• Loop peristiwa: Jumlah kotak centang yang terjadi dan berapa banyak waktu CPU yang digunakan secara total.
• Heap vs. non-heap: Berapa banyak penggunaan memori aplikasi Anda dalam heap atau non-heap.

Mode pelacakan terdistribusi

Secara default, SDK mengirim header yang dipahami oleh aplikasi atau layanan lain yang diinstrumentasikan dengan Application Insights SDK. Anda dapat mengaktifkan pengiriman dan penerimaan header Konteks Pelacakan W3C selain header AI yang ada. Dengan cara ini, Anda tidak akan memutuskan korelasi dengan salah satu layanan warisan yang ada. Mengaktifkan header W3C memungkinkan aplikasi Anda untuk berkorelasi dengan layanan lain yang tidak berinstrumentasi dengan Application Insights tetapi itu mengadopsi standar W3C ini.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

API TelemetryClient

Untuk deskripsi lengkap tentang API TelemetryClient, lihat API Application Insights untuk peristiwa dan metrik kustom.

Anda dapat melacak permintaan, peristiwa, metrik, atau pengecualian apa pun dengan menggunakan pustaka klien Application Insights untuk Node.js. Contoh kode berikut menunjukkan beberapa API yang dapat digunakan:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Melacak dependensi Anda

Gunakan kode berikut untuk melacak dependensi Anda:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Contoh utilitas menggunakan trackMetric untuk mengukur berapa lama penjadwalan loop peristiwa berlangsung:

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Menambahkan properti kustom ke semua peristiwa

Gunakan kode berikut untuk menambahkan properti kustom ke semua peristiwa:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Melacak permintaan GET HTTP

Gunakan kode berikut untuk melacak permintaan GET HTTP secara manual:

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Atau, Anda dapat melacak permintaan dengan menggunakan trackNodeHttpRequest metode :

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Melacak waktu mulai server

Gunakan kode berikut untuk melacak waktu mulai server:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Membersihkan

Secara default, telemetri di-buffer selama 15 detik sebelum dikirim ke server penyerapan. Jika aplikasi Anda memiliki umur pendek, seperti alat CLI, mungkin perlu untuk menghapus telemetri buffer Anda secara manual saat aplikasi berakhir dengan menggunakan appInsights.defaultClient.flush().

Jika SDK mendeteksi bahwa aplikasi Anda mengalami crash, SDK memanggil flush untuk Anda dengan menggunakan appInsights.defaultClient.flush({ isAppCrashing: true }). Dengan opsi isAppCrashingflush , aplikasi Anda diasumsikan dalam keadaan abnormal dan tidak cocok untuk mengirim telemetri. Sebagai gantinya, SDK menyimpan semua telemetri yang di-buffer ke penyimpanan persisten dan memungkinkan aplikasi Anda dihentikan. Ketika aplikasi Anda dimulai lagi, aplikasi mencoba mengirim telemetri apa pun yang disimpan ke penyimpanan persisten.

Praproses data dengan prosesor telemetri

Anda dapat memproses dan memfilter data yang dikumpulkan sebelum dikirim untuk retensi dengan menggunakan prosesor telemetri. Prosesor telemetri dipanggil satu per satu dengan urutan saat ditambahkan sebelum item telemetri dikirim ke cloud.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Jika prosesor telemetri mengembalikan false, item telemetri tersebut tidak dikirim.

Semua prosesor telemetri akan menerima data telemetri dan amplopnya untuk diperiksa dan diubah. Prosesor ini juga menerima objek konteks. Konten objek ini ditentukan oleh contextObjects parameter saat memanggil metode trek untuk telemetri yang dilacak secara manual. Untuk telemetri yang dikumpulkan secara otomatis, objek ini diisi dengan informasi permintaan yang tersedia dan konten permintaan persisten sebagaimana disediakan oleh appInsights.getCorrelationContext() (jika korelasi dependensi otomatis diaktifkan).

Jenis TypeScript untuk prosesor telemetri adalah:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Misalnya, prosesor yang menghapus tumpukan data pelacakan dari pengecualian mungkin ditulis dan ditambahkan sebagai berikut:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Menggunakan beberapa string koneksi

Anda dapat membuat beberapa sumber daya Application Insights dan mengirim data yang berbeda ke setiap sumber daya tersebut dengan menggunakan setiap string koneksinya.

Contohnya:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Opsi konfigurasi tingkat lanjut

Objek klien berisi properti config dengan banyak pengaturan opsional untuk skenario tingkat lanjut. Untuk mengaturnya, gunakan:

client.config.PROPERTYNAME = VALUE;

Properti ini khusus klien, sehingga Anda dapat mengonfigurasi appInsights.defaultClient secara terpisah dari klien yang dibuat dengan new appInsights.TelemetryClient().

Tanya jawab umum

Bagaimana cara menonaktifkan korelasi telemetri?

Untuk menonaktifkan korelasi telemetri, gunakan correlationHeaderExcludedDomains properti dalam konfigurasi. Untuk informasi selengkapnya, lihat ApplicationInsights-node.js.

Pemecahan Masalah

Untuk informasi pemecahan masalah, termasuk skenario "tanpa data" dan menyesuaikan log, lihat Memecahkan Masalah pemantauan Application Insights aplikasi dan layanan Node.js.

Langkah berikutnya

• Memantau telemetri Anda di portal
• Menulis kueri Analitik melalui telemetri Anda