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

Článek
09/30/2024

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í.

Čistá instalace
Upgradovat

Získejte základní znalosti rozhraní API (OpenTelemetry JavaScript Application Programming Interface) a sady SDK (Software Development Kit).
- Přečtěte si dokumentaci k Jazyku JavaScript openTelemetry.
- Projděte si konfiguraci OpenTelemetry služby Azure Monitor.
- Vyhodnoťte možnost Přidat, upravit a filtrovat OpenTelemetry.
applicationinsights Odinstalujte závislost z projektu.
```
npm uninstall applicationinsights
```
Odeberte implementaci sady SDK 2.X z kódu.

Odeberte veškerou instrumentaci Application Insights z kódu. Odstraňte všechny oddíly, ve kterých je klient Application Insights inicializován, změněn nebo volán.
Povolte Application Insights pomocí distribuce OpenTelemetry služby Azure Monitor.

Důležité

Před importem čehokoli jiného useAzureMonitor je nutné volat. Při prvním importu jiných knihoven může dojít ke ztrátě telemetrie. Postupujte podle pokynů, jak začít připojovat k distrou OpenTelemetry služby Azure Monitor.

Změny a omezení distribuce OpenTelemetry služby Azure Monitor

Rozhraní API ze sady Application Insights SDK 2.X nejsou dostupná v distrou OpenTelemetry služby Azure Monitor. K těmto rozhraním API můžete přistupovat prostřednictvím cesty upgradu, která není zásadní, v sadě Application Insights SDK 3.X.
Filtrování závislostí, protokolů a výjimek podle názvu operace se zatím nepodporuje.

applicationinsights Upgradujte závislost balíčku.
```
npm update applicationinsights
```
Znovu sestavte aplikaci.
Otestujte aplikaci.

Pokud se chcete vyhnout použití nepodporovaných možností konfigurace v sadě Application Insights SDK 3.X, podívejte se na nepodporované vlastnosti.

Pokud sada SDK zaznamená upozornění na nepodporované využití rozhraní API po zvýšení hlavní verze a potřebujete související funkce, pokračujte v používání sady Application Insights SDK 2.X.

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

Sdílet prostřednictvím