Migrera från Node.js Application Insights SDK 2.X till Azure Monitor OpenTelemetry

Den här guiden innehåller två alternativ för att uppgradera från Azure Monitor Application Insights Node.js SDK 2.X till OpenTelemetry.

• Installera Node.js Azure Monitor OpenTelemetry Distro.
  • Ta bort beroenden för det klassiska API:et Application Insights.
  • Bekanta dig med OpenTelemetry-API:er och termer.
  • Placera dig själv för att använda allt som OpenTelemetry erbjuder nu och i framtiden.
• Uppgradera till Node.js SDK 3.X.
  • Skjut upp kodändringar samtidigt som kompatibiliteten med befintliga anpassade händelser och mått bevaras.
  • Få åtkomst till mer omfattande OpenTelemetry-instrumentationsbibliotek.
  • Behåll behörigheten för de senaste fel- och säkerhetskorrigeringarna.

Ren installation

1. Få nödvändiga kunskaper om OpenTelemetry JavaScript Application Programming Interface (API) och Software Development Kit (SDK).

   • Läs Dokumentation om OpenTelemetry JavaScript.
   • Läs Konfigurera Azure Monitor OpenTelemetry.
   • Utvärdera Lägg till, ändra och filtrera OpenTelemetry.

2. Avinstallera beroendet applicationinsights från projektet.

   npm uninstall applicationinsights
   

3. Ta bort SDK 2.X-implementeringen från koden.

   Ta bort all Application Insights-instrumentation från koden. Ta bort alla avsnitt där Application Insights-klienten initieras, ändras eller anropas.

4. Aktivera Application Insights med Azure Monitor OpenTelemetry Distro.

   Viktigt!

   Innan du importerar något annat useAzureMonitor måste du anropas. Det kan uppstå telemetriförlust om andra bibliotek importeras först. Följ komma igång för att registrera till Azure Monitor OpenTelemetry Distro.

Ändringar och begränsningar i Azure Monitor OpenTelemetry Distro

• API:erna från Application Insights SDK 2.X är inte tillgängliga i Azure Monitor OpenTelemetry Distro. Du kan komma åt dessa API:er via en icke-banbrytande uppgraderingssökväg i Application Insights SDK 3.X.
• Det finns ännu inte stöd för att filtrera beroenden, loggar och undantag efter åtgärdsnamn.

Uppgradera

1. applicationinsights Uppgradera paketberoendet.

   npm update applicationinsights
   

2. Återskapa programmet.

3. Testa ditt program.

   Information om hur du undviker att använda konfigurationsalternativ som inte stöds i Application Insights SDK 3.X finns i Egenskaper som inte stöds.

   Om SDK loggar varningar om API-användning som inte stöds efter en större version, och du behöver de relaterade funktionerna, fortsätter du att använda Application Insights SDK 2.X.

Ändringar och begränsningar

Följande ändringar och begränsningar gäller för båda uppgraderingsvägarna.

stöd för Node.js version

För att en version av Node.js ska kunna stödjas av ApplicationInsights 3.X SDK måste den ha överlappande stöd från både Azure SDK och OpenTelemetry. Kontrollera de senaste uppdateringarna i OpenTelemetry-körningen som stöds. Användare i äldre versioner som Node 8, som tidigare stöddes av ApplicationInsights SDK, kan fortfarande använda OpenTelemetry-lösningar men kan uppleva oväntat eller icke-bakåtkompatibelt beteende. ApplicationInsights SDK är också beroende av Azure SDK för JS som inte garanterar stöd för Node.js versioner som har nått slutet av livslängden. Se Azure SDK för JS-supportprincip. För att en version av Node.js ska kunna stödjas av ApplicationInsights 3.X SDK måste den ha överlappande stöd från både Azure SDK och OpenTelemetry.

Konfigurationsalternativ

Application Insights SDK version 2.X erbjuder konfigurationsalternativ som inte är tillgängliga i Azure Monitor OpenTelemetry Distro eller i huvudversionsuppgraderingen till Application Insights SDK 3.X. Information om hur du hittar dessa ändringar finns i dokumentationen för SDK-konfiguration tillsammans med de alternativ som vi fortfarande stöder.

Utökade mått

Utökade mått stöds i Application Insights SDK 2.X. Stödet för dessa mått upphör dock i både version 3.X av ApplicationInsights SDK och Azure Monitor OpenTelemetry Distro.

Telemetriprocessorer

Även om Azure Monitor OpenTelemetry Distro och Application Insights SDK 3.X inte stöder TelemetryProcessors, kan du skicka span- och loggpostprocessorer. Mer information om hur du gör finns i Projektet Azure Monitor OpenTelemetry Distro.

Det här exemplet visar motsvarigheten till att skapa och tillämpa en telemetriprocessor som kopplar en anpassad egenskap i 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;
}

Det här exemplet visar hur du ändrar en Azure Monitor OpenTelemetry Distro-implementering för att skicka en SpanProcessor till konfigurationen av distributionen.

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