Migrace ze sady Node.js Application Insights SDK 2.X na OpenTelemetry služby Azure Monitor

Tato příručka obsahuje dvě možnosti upgradu ze sady Azure Monitor Application Insights Node.js SDK 2.X na OpenTelemetry.

• Vyčistěte instalaci Node.js distribuce OpenTelemetry služby Azure Monitor.
  • Odeberte závislosti v klasickém rozhraní API Application Insights.
  • Seznamte se s rozhraními API a termíny OpenTelemetry.
  • Umístěte se k používání všech nabídek OpenTelemetry nyní a v budoucnu.
• Upgradujte na Node.js SDK 3.X.
  • Odložte změny kódu při zachování kompatibility s existujícími vlastními událostmi a metrikami.
  • Získejte přístup k bohatším knihovnám instrumentace OpenTelemetry.
  • Udržujte nárok na nejnovější chyby a opravy zabezpečení.

Změny a omezení

Následující změny a omezení platí pro obě cesty upgradu.

podpora verzí Node.js

Aby sada ApplicationInsights 3.X SDK podporovala verzi Node.js, musí mít překrývající se podporu ze sady Azure SDK i OpenTelemetry. Nejnovější aktualizace najdete v podporovaných modulech runtime OpenTelemetry. Uživatelé ve starších verzích, jako je Node 8, dříve podporovaní sadou ApplicationInsights SDK, můžou stále používat řešení OpenTelemetry, ale můžou zaznamenat neočekávané nebo zásadní chování. Sada ApplicationInsights SDK také závisí na sadě Azure SDK pro JS, která nezaručuje podporu pro žádné Node.js verze, které dosáhly konce životnosti. Prohlédněte si zásady podpory js sady Azure SDK. Aby sada ApplicationInsights 3.X SDK podporovala verzi Node.js, musí mít překrývající se podporu ze sady Azure SDK i OpenTelemetry.

Možnosti konfigurace

Sada Application Insights SDK verze 2.X nabízí možnosti konfigurace, které nejsou dostupné v distrou OpenTelemetry služby Azure Monitor nebo v upgradu hlavní verze na Sadu Application Insights SDK 3.X. Pokud chcete tyto změny najít, společně s možnostmi, které stále podporujeme, najdete v dokumentaci ke konfiguraci sady SDK.

Rozšířené metriky

Rozšířené metriky jsou podporovány v sadě Application Insights SDK 2.X; Podpora těchto metrik však končí ve verzi 3.X sady ApplicationInsights SDK i v distrou OpenTelemetry služby Azure Monitor.

Procesory telemetrie

I když sada Azure Monitor OpenTelemetry Distro a Application Insights SDK 3.X nepodporují telemetrické procesory, umožňují předávat procesory záznamů protokolů a rozsahu. Další informace o tom, jak, najdete v projektu OpenTelemetry Distro služby Azure Monitor.

Tento příklad ukazuje ekvivalent vytvoření a použití procesoru telemetrie, který připojí vlastní vlastnost v sadě 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;
}

Tento příklad ukazuje, jak upravit implementaci distribuce OpenTelemetry služby Azure Monitor tak, aby předal spanProcessor konfiguraci distribuce.

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