Application Insights SDK 2.x retirement: how to migrate to OpenTelemetry

What Microsoft has announced

Microsoft's archived page for the Classic API says: "The .NET Application Insights Classic API SDK 2.x is deprecated and retires on 03/31/2027." That is 31 March 2027.

The page also says: "To remain supported, migrate to an OpenTelemetry-based SDK 3.x or preferably the OpenTelemetry Distro." For new applications, Microsoft says to use the Distro.

The page names the ASP.NET, ASP.NET Core and Worker Service packages as part of the Classic API. The Node.js SDK 2.x is already retired.

We did not find a page that describes in detail what happens to a 2.x app after the date. Plan to be off 2.x before it.

Your options for .NET

Microsoft's migration page gives .NET teams two main choices. A third choice is open to teams that want a vendor-neutral setup.

• Application Insights .NET SDK 3.x. This is the smallest change. Per Microsoft, it "keeps most TelemetryClient and TelemetryConfiguration application programming interfaces (APIs)" and uses the Azure Monitor OpenTelemetry Exporter to send data to Application Insights.
• Microsoft OpenTelemetry Distro (NuGet package Microsoft.OpenTelemetry). Microsoft calls this a fresh start with OpenTelemetry. It can export to Azure Monitor, and its ExportTarget setting also lists Otlp and Console. Microsoft says it can combine Azure Monitor with other targets in one configuration.
• OpenTelemetry SDK with an OTLP exporter (package OpenTelemetry.Exporter.OpenTelemetryProtocol, from opentelemetry.io). Use this if you want to choose the backend yourself. Microsoft says Azure Monitor can also receive OTLP from an OpenTelemetry Collector.

Rules from Microsoft that apply to every path

Choose one instrumentation path for each application. Microsoft says: "don't initialize two distros or duplicate providers for the same signal." Do not add a Distro to an app that uses Application Insights .NET SDK 3.x.

Do not mix Application Insights 2.x and 3.x packages in one application. Upgrade all Application Insights package references together.

If you already use the Azure Monitor OpenTelemetry Distro, Microsoft says no action is needed.

The Distro for .NET does not rename or replace the Application Insights SDK packages. Microsoft treats the SDK 3.x upgrade and the Distro as separate paths.

What changes in code with SDK 3.x

Most classic Track calls still work. Microsoft says they go through an internal layer that creates OpenTelemetry signals. The migration page and the 2.x to 3.x guide list these changes:

• Remove the packages Microsoft lists as not compatible, for example Microsoft.ApplicationInsights.DependencyCollector, PerfCounterCollector, EventCounterCollector and Microsoft.Extensions.Logging.ApplicationInsights. SDK 3.x has no 3.x version of them.
• Use a connection string. InstrumentationKey is no longer supported, and 3.x can fail at startup without a connection string. Tests can use a dummy value.
• Create the configuration with TelemetryConfiguration.CreateDefault() and pass it to new TelemetryClient(config).
• TrackPageView is removed.
• TrackEvent, TrackException and TrackAvailability overloads with a metrics dictionary are removed. Use TrackMetric() instead.
• Telemetry initializers, processors and modules are removed. Move custom ones to OpenTelemetry processors. GlobalProperties adds properties to traces and logs sent by that client, not to metrics. Add metric attributes separately. A few modules, such as the unhandled-exception ones, have no direct replacement.
• Adaptive sampling is removed. Use TracesPerSecond (the default is five traces per second) or SamplingRatio. Separate settings for requests and dependencies are no longer supported.
• ITelemetryChannel is removed. For tests, use an in-memory OpenTelemetry exporter.
• Metric names must follow OpenTelemetry rules: start with a letter, and use only letters, digits, _, ., - or /.
• Check third-party packages that depend on Microsoft.ApplicationInsights 2.x, for example Serilog.Sinks.ApplicationInsights. Ask the maintainers if they support 3.x.

var config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "<ConnectionString>";
config.TracesPerSecond = 5;      // rate-limited sampling
// or
config.SamplingRatio = 0.25f;    // fixed ratio from 0.0 to 1.0
var client = new TelemetryClient(config);
client.Context.GlobalProperties["MyCustomKey"] = "MyCustomValue";

What changes if you use the Distro or plain OpenTelemetry

You leave the Application Insights API behind. Custom data goes through OpenTelemetry APIs: spans, metrics and logs. Initializers and processors become OpenTelemetry processors. For Node.js, Microsoft says this directly: the Distro does not expose the 2.x APIs.

In ASP.NET Core, the Distro starts with one call in Program.cs. Microsoft reads the connection string from the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable. It recommends the environment variable for production.

using Microsoft.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

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

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

Migration order, service by service

Do the steps in this order. Finish one service before you start the next.

• List every service that references a Microsoft.ApplicationInsights package. Note the version, the target framework and the connection setting (key or connection string).
• For each service, list what uses the old extension points: initializers, processors, modules, adaptive sampling, a custom channel, TrackPageView, and third-party packages.
• Pick a path per service. SDK 3.x fits services with many TelemetryClient calls. The Distro fits new or small services, or teams that want OpenTelemetry APIs.
• Start with a low-risk service. Remove incompatible packages, upgrade the rest together, and set a connection string.
• Rewrite the old extension points as OpenTelemetry processors. Replace adaptive sampling with TracesPerSecond or SamplingRatio.
• Check in a test environment. Microsoft suggests the OpenTelemetry console exporter, self-diagnostics logs, and a check of parent-child sampling.
• Check the cloud role name, role instance and environment in Application Insights. Microsoft says a service that shares a resource with other services needs its own cloud role name.
• Compare requests, dependencies and custom events with the old data before and after the release. Then move to the next service.