Migrasi dari Node.js Application Insights SDK 2.X ke Azure Monitor OpenTelemetry

Panduan ini menyediakan dua opsi untuk meningkatkan dari Azure Monitor Application Insights Node.js SDK 2.X ke OpenTelemetry.

• Bersihkan instal Node.js Distro OpenTelemetry Azure Monitor.
  • Hapus dependensi pada API klasik Application Insights.
  • Biasakan diri Anda dengan API dan istilah OpenTelemetry.
  • Posisikan diri Anda untuk menggunakan semua yang ditawarkan OpenTelemetry sekarang dan di masa depan.
• Tingkatkan ke Node.js SDK 3.X.
  • Menunda perubahan kode sambil mempertahankan kompatibilitas dengan peristiwa dan metrik kustom yang ada.
  • Akses pustaka instrumentasi OpenTelemetry yang lebih kaya.
  • Pertahankan kelayakan untuk perbaikan bug dan keamanan terbaru.

Bersihkan penginstalan

1. Dapatkan pengetahuan prasyarat tentang OpenTelemetry JavaScript Application Programming Interface (API) dan Software Development Kit (SDK).

   • Baca dokumentasi OpenTelemetry JavaScript.
   • Tinjau Mengonfigurasi OpenTelemetry Azure Monitor.
   • Evaluasi Tambahkan, ubah, dan filter OpenTelemetry.

2. Hapus instalan applicationinsights dependensi dari proyek Anda.

   npm uninstall applicationinsights
   

3. Hapus implementasi SDK 2.X dari kode Anda.

   Hapus semua instrumentasi Application Insights dari kode Anda. Hapus bagian apa pun tempat klien Application Insights diinisialisasi, dimodifikasi, atau dipanggil.

4. Aktifkan Application Insights dengan Distro OpenTelemetry Azure Monitor.

   Penting

   Sebelum Anda mengimpor hal lain, useAzureMonitor harus dipanggil. Mungkin ada kehilangan telemetri jika pustaka lain diimpor terlebih dahulu. Ikuti memulai untuk onboarding ke Distro OpenTelemetry Azure Monitor.

Perubahan dan batasan Distro OpenTelemetry Azure Monitor

• API dari Application Insights SDK 2.X tidak tersedia di Distro OpenTelemetry Azure Monitor. Anda dapat mengakses API ini melalui jalur peningkatan yang tidak pecah di Application Insights SDK 3.X.
• Pemfilteran dependensi, log, dan pengecualian berdasarkan nama operasi belum didukung.

Mutakhirkan

1. Tingkatkan applicationinsights dependensi paket.

   npm update applicationinsights
   

2. Bangun kembali aplikasi Anda.

3. Uji aplikasi Anda.

   Untuk menghindari penggunaan opsi konfigurasi yang tidak didukung di Application Insights SDK 3.X, lihat Properti yang tidak didukung.

   Jika SDK mencatat peringatan tentang penggunaan API yang tidak didukung setelah benjolan versi utama, dan Anda memerlukan fungsionalitas terkait, lanjutkan menggunakan Application Insights SDK 2.X.

Perubahan dan batasan

Perubahan dan batasan berikut berlaku untuk kedua jalur peningkatan.

dukungan versi Node.js

Agar versi Node.js didukung oleh ApplicationInsights 3.X SDK, itu harus memiliki dukungan yang tumpang tindih dari Azure SDK dan OpenTelemetry. Periksa runtime yang didukung OpenTelemetry untuk pembaruan terbaru. Pengguna pada versi lama seperti Node 8, yang sebelumnya didukung oleh ApplicationInsights SDK, masih dapat menggunakan solusi OpenTelemetry tetapi dapat mengalami perilaku yang tidak terduga atau melanggar. ApplicationInsights SDK juga bergantung pada Azure SDK untuk JS yang tidak menjamin dukungan untuk versi Node.js apa pun yang telah mencapai akhir masa pakai. Lihat kebijakan dukungan Azure SDK untuk JS. Agar versi Node.js didukung oleh ApplicationInsights 3.X SDK, itu harus memiliki dukungan yang tumpang tindih dari Azure SDK dan OpenTelemetry.

Opsi konfigurasi

Application Insights SDK versi 2.X menawarkan opsi konfigurasi yang tidak tersedia di Distro OpenTelemetry Azure Monitor atau dalam peningkatan versi utama ke Application Insights SDK 3.X. Untuk menemukan perubahan ini, bersama dengan opsi yang masih kami dukung, lihat dokumentasi konfigurasi SDK.

Metrik yang diperpanjang

Metrik yang diperluas didukung di Application Insights SDK 2.X; namun, dukungan untuk metrik ini berakhir di SDK ApplicationInsights versi 3.X dan Distro OpenTelemetry Azure Monitor.

Prosesor Telemetri

Meskipun Azure Monitor OpenTelemetry Distro dan Application Insights SDK 3.X tidak mendukung TelemetryProcessors, mereka memungkinkan Anda untuk melewati rentang dan prosesor rekaman log. Untuk informasi selengkapnya tentang caranya, lihat Proyek Distro OpenTelemetry Azure Monitor.

Contoh ini menunjukkan setara dengan membuat dan menerapkan prosesor telemetri yang melampirkan properti kustom di Application Insights SDK 2.X.

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

Contoh ini menunjukkan cara memodifikasi implementasi Distro OpenTelemetry Azure Monitor untuk meneruskan SpanProcessor ke konfigurasi distro.

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);