Teilen über

Migrieren von Node.js Application Insights-SDK 2.X zu Azure Monitor OpenTelemetry

  • Artikel

Dieser Leitfaden bietet zwei Möglichkeiten zum Migrieren vom Azure Monitor Application Insights Node.js-SDK 2.X zu OpenTelemetry.

  • Nehmen Sie eine Neuinstallation von Node.js Azure Monitor OpenTelemetry Distro vor.
    • Entfernen Sie Abhängigkeiten von der klassischen Application Insights-API.
    • Machen Sie sich mit OpenTelemetry-APIs und -Benennungen vertraut.
    • Bringen Sie sich in die Lage, alle aktuellen und zukünftigen OpenTelemetry-Angebote nutzen zu können.
  • Nehmen Sie ein Upgrade auf Node.js-SDK 3.X vor.
    • Verschieben Sie Codeänderungen, während Sie die Kompatibilität mit vorhandenen benutzerdefinierten Ereignissen und Metriken beibehalten.
    • Greifen Sie auf umfangreichere OpenTelemetry-Instrumentierungsbibliotheken zu.
    • Behalten Sie die Berechtigung für die neuesten Fehler- und Sicherheitsfixes.

  1. Erwerben Sie erforderliche Kenntnisse für die OpenTelemetry JavaScript-API (Application Programming Interface) und das -SDK (Software Development Kit).

  2. Deinstallieren Sie die applicationinsights-Abhängigkeit aus Ihrem Projekt.

    npm uninstall applicationinsights

  3. Entfernen Sie die SDK 2.X-Implementierung aus Ihrem Code.

    Entfernen Sie die gesamte Application Insights-Instrumentierung aus Ihrem Code. Löschen Sie alle Abschnitte, in denen der Application Insights-Client initialisiert, geändert oder aufgerufen wird.

  4. Aktivieren Sie Application Insights mit der Azure Monitor OpenTelemetry-Distribution.

    Wichtig

    Bevor Sie etwas anderes importieren, muss useAzureMonitor aufgerufen werden. Es kann zu Telemetrieverlusten kommen, wenn zuerst andere Bibliotheken importiert werden. Befolgen Sie die ersten Schritte, um das Onboarding auf die Azure Monitor OpenTelemetry-Distribution durchzuführen.

Änderungen und Einschränkungen der Azure Monitor OpenTelemetry-Distribution

  • Die APIs aus dem Application Insights SDK 2.X sind in der Azure Monitor OpenTelemetry-Distribution nicht verfügbar. Sie können über einen geschützten Upgradepfad im Application Insights SDK 3.X auf diese APIs zugreifen.
  • Das Filtern von Abhängigkeiten, Protokollen und Ausnahmen nach Vorgangsname wird noch nicht unterstützt.

Änderungen und Einschränkungen

Die folgenden Änderungen und Einschränkungen gelten für beide Upgradepfade.

Node.js-Versionsunterstützung

Damit eine Version von Node.js vom ApplicationInsights 3.X SDK unterstützt werden kann, muss sie überlappende Unterstützung sowohl vom Azure SDK als auch von OpenTelemetry haben. Überprüfen Sie die von OpenTelemetry unterstützten Laufzeiten auf die neuesten Updates. Benutzer mit älteren Versionen wie beispielsweise Node 8, die zuvor vom Application Insights SDK unterstützt wurden, können weiterhin OpenTelemetry-Lösungen verwenden. Es kann aber zu unerwartetem Verhalten oder zu Unterbrechungen kommen. Das ApplicationInsights SDK hängt auch vom Azure SDK für JS ab, das keine Unterstützung für alle Node.js-Versionen garantiert, die das Ende der Lebensdauer erreicht haben. Siehe Supportrichtlinie des Azure SDK für JS. Damit eine Version von Node.js vom ApplicationInsights 3.X SDK unterstützt werden kann, muss sie überlappende Unterstützung sowohl vom Azure SDK als auch von OpenTelemetry haben.

Konfigurationsoptionen

Das Application Insights SDK, Version 2.X, bietet Konfigurationsoptionen, die in der Azure Monitor OpenTelemetry-Distribution oder im Upgrade der Hauptversion auf Application Insights SDK 3.X nicht verfügbar sind. Um diese Änderungen zusammen mit den Optionen zu finden, die wir weiterhin unterstützen, lesen Sie die SDK-Konfigurationsdokumentation.

Erweiterte Metriken

Erweiterte Metriken werden im Application Insights SDK 2.X unterstützt. Die Unterstützung für diese Metriken endet jedoch sowohl in Version 3.X des ApplicationInsights SDK als auch in der Azure Monitor OpenTelemetry-Distribution.

Telemetrieprozessoren

Während die Azure Monitor OpenTelemetry-Distribution und Application Insights SDK 3.X TelemetryProcessors nicht unterstützen, können Sie Span- und Protokolldatensatzprozessoren übergeben. Weitere Informationen dazu finden Sie im Azure Monitor OpenTelemetry-Distributionsprojekt.

Dieses Beispiel zeigt das Äquivalent zum Erstellen und Anwenden eines Telemetrieprozessors, der eine benutzerdefinierte Eigenschaft im Application Insights SDK 2.X anfügt.

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

In diesem Beispiel wird gezeigt, wie Sie die Implementierung einer Azure Monitor OpenTelemetry-Distribution so ändern, dass ein SpanProcessor an die Konfiguration der Distribution übergeben wird.

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