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

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.

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