Application Insights SDK 2.x wird eingestellt: Migration zu OpenTelemetry

Was Microsoft angekündigt hat

Auf der archivierten Seite zur Classic API schreibt Microsoft: "The .NET Application Insights Classic API SDK 2.x is deprecated and retires on 03/31/2027." Das ist der 31. März 2027.

Die Seite sagt außerdem: "To remain supported, migrate to an OpenTelemetry-based SDK 3.x or preferably the OpenTelemetry Distro." Für neue Anwendungen empfiehlt Microsoft die Distro.

Die Seite nennt die Pakete für ASP.NET, ASP.NET Core und Worker Service als Teil der Classic API. Das Node.js SDK 2.x ist bereits eingestellt.

Wir haben keine Seite gefunden, die genau beschreibt, was nach dem Datum mit einer 2.x-App passiert. Planen Sie, vorher von 2.x weg zu sein.

Ihre Optionen für .NET

Die Migrationsseite von Microsoft nennt für .NET zwei Hauptwege. Ein dritter Weg steht Teams offen, die ein herstellerneutrales Setup wollen.

• Application Insights .NET SDK 3.x. Das ist die kleinste Änderung. Laut Microsoft behält es "most TelemetryClient and TelemetryConfiguration application programming interfaces (APIs)" und sendet die Daten über den Azure Monitor OpenTelemetry Exporter an Application Insights.
• Microsoft OpenTelemetry Distro (NuGet-Paket Microsoft.OpenTelemetry). Microsoft beschreibt das als Neustart mit OpenTelemetry. Die Distro kann nach Azure Monitor exportieren. Die Einstellung ExportTarget nennt auch Otlp und Console. Laut Microsoft lässt sich Azure Monitor in einer Konfiguration mit anderen Zielen kombinieren.
• OpenTelemetry SDK mit OTLP-Exporter (Paket OpenTelemetry.Exporter.OpenTelemetryProtocol, von opentelemetry.io). Wählen Sie das, wenn Sie das Backend selbst bestimmen wollen. Laut Microsoft kann Azure Monitor OTLP auch von einem OpenTelemetry Collector empfangen.

Regeln von Microsoft, die für jeden Weg gelten

Wählen Sie pro Anwendung genau einen Instrumentierungsweg. Microsoft schreibt: "don't initialize two distros or duplicate providers for the same signal." Fügen Sie keine Distro zu einer Anwendung hinzu, die Application Insights .NET SDK 3.x nutzt.

Mischen Sie in einer Anwendung nicht Application-Insights-Pakete der Version 2.x und 3.x. Stellen Sie alle Application-Insights-Paketverweise gemeinsam um.

Wenn Sie schon die Azure Monitor OpenTelemetry Distro nutzen, ist laut Microsoft nichts zu tun.

Die Distro für .NET benennt die Application-Insights-SDK-Pakete nicht um und ersetzt sie nicht. Microsoft behandelt das Upgrade auf SDK 3.x und die Distro als getrennte Wege.

Was sich mit SDK 3.x im Code ändert

Die meisten klassischen Track-Aufrufe funktionieren weiter. Laut Microsoft laufen sie über eine interne Schicht, die OpenTelemetry-Signale erzeugt. Die Migrationsseite und der Leitfaden 2.x auf 3.x nennen diese Änderungen:

• Entfernen Sie die Pakete, die Microsoft als nicht kompatibel auflistet, zum Beispiel Microsoft.ApplicationInsights.DependencyCollector, PerfCounterCollector, EventCounterCollector und Microsoft.Extensions.Logging.ApplicationInsights. Für sie gibt es keine 3.x-Version.
• Nutzen Sie einen Connection String. InstrumentationKey wird nicht mehr unterstützt, und 3.x kann beim Start fehlschlagen, wenn kein Connection String gesetzt ist. Tests können einen Platzhalterwert nutzen.
• Erzeugen Sie die Konfiguration mit TelemetryConfiguration.CreateDefault() und übergeben Sie sie an new TelemetryClient(config).
• TrackPageView entfällt.
• Überladungen von TrackEvent, TrackException und TrackAvailability mit einem Metrics-Dictionary entfallen. Nutzen Sie stattdessen TrackMetric().
• Telemetry Initializer, Processors und Modules entfallen. Überführen Sie eigene in OpenTelemetry-Processors. GlobalProperties ergänzt Eigenschaften an Traces und Logs, die dieser Client sendet, nicht aber an Metriken. Ergänzen Sie Metrikattribute separat. Für einige Module, etwa die für unbehandelte Exceptions, gibt es keinen direkten Ersatz.
• Adaptive Sampling entfällt. Nutzen Sie TracesPerSecond (Standard: fünf Traces pro Sekunde) oder SamplingRatio. Getrennte Einstellungen für Requests und Dependencies werden nicht mehr unterstützt.
• ITelemetryChannel entfällt. Nutzen Sie in Tests einen In-Memory-Exporter von OpenTelemetry.
• Metriknamen müssen den OpenTelemetry-Regeln folgen: Sie beginnen mit einem Buchstaben und enthalten nur Buchstaben, Ziffern, _, ., - oder /.
• Prüfen Sie Pakete von Drittanbietern, die von Microsoft.ApplicationInsights 2.x abhängen, zum Beispiel Serilog.Sinks.ApplicationInsights. Fragen Sie die Maintainer, ob sie 3.x unterstützen.

var config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "<ConnectionString>";
config.TracesPerSecond = 5;      // ratenbegrenztes Sampling
// oder
config.SamplingRatio = 0.25f;    // festes Verhältnis von 0.0 bis 1.0
var client = new TelemetryClient(config);
client.Context.GlobalProperties["MyCustomKey"] = "MyCustomValue";

Was sich mit der Distro oder reinem OpenTelemetry ändert

Sie verlassen die Application-Insights-API. Eigene Daten laufen über OpenTelemetry-APIs: Spans, Metriken und Logs. Initializer und Processors werden zu OpenTelemetry-Processors. Für Node.js sagt Microsoft das direkt: Die Distro stellt die 2.x-APIs nicht bereit.

In ASP.NET Core startet die Distro mit einem Aufruf in Program.cs. Microsoft liest den Connection String aus der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING. Für Produktion empfiehlt Microsoft die Umgebungsvariable.

using Microsoft.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

var app = builder.Build();
app.Run();

Reihenfolge der Migration, Service für Service

Gehen Sie in dieser Reihenfolge vor. Schließen Sie einen Service ab, bevor Sie den nächsten beginnen.

• Listen Sie jeden Service auf, der ein Microsoft.ApplicationInsights-Paket nutzt. Notieren Sie Version, Target Framework und die Verbindungseinstellung (Key oder Connection String).
• Listen Sie je Service auf, was die alten Erweiterungspunkte nutzt: Initializer, Processors, Modules, Adaptive Sampling, einen eigenen Channel, TrackPageView und Pakete von Drittanbietern.
• Wählen Sie pro Service einen Weg. SDK 3.x passt zu Services mit vielen TelemetryClient-Aufrufen. Die Distro passt zu neuen oder kleinen Services und zu Teams, die OpenTelemetry-APIs nutzen wollen.
• Beginnen Sie mit einem Service mit geringem Risiko. Entfernen Sie nicht kompatible Pakete, stellen Sie die übrigen gemeinsam um und setzen Sie einen Connection String.
• Schreiben Sie die alten Erweiterungspunkte als OpenTelemetry-Processors neu. Ersetzen Sie Adaptive Sampling durch TracesPerSecond oder SamplingRatio.
• Prüfen Sie in einer Testumgebung. Microsoft nennt den OpenTelemetry Console Exporter, die Self-Diagnostics-Logs und eine Prüfung der Sampling-Entscheidungen zwischen Parent und Child.
• Prüfen Sie Cloud Role Name, Role Instance und Environment in Application Insights. Laut Microsoft braucht ein Service, der sich eine Ressource mit anderen Services teilt, einen eigenen Cloud Role Name.
• Vergleichen Sie Requests, Dependencies und Custom Events vor und nach dem Release mit den alten Daten. Danach folgt der nächste Service.