Migrate from Application Insights Classic API SDKs to OpenTelemetry

Use Application Insights .NET software development kit (SDK) 3.x to upgrade from Application Insights .NET SDK 2.x to an OpenTelemetry (OTel)-based implementation. The 3.x SDK keeps most TelemetryClient and TelemetryConfiguration application programming interfaces (APIs) and uses the Azure Monitor OpenTelemetry Exporter to send telemetry to Application Insights.

Most classic Track* calls continue to work after the upgrade, but they're routed through an internal mapping layer that emits OpenTelemetry signals.

The following steps upgrade Application Insights .NET SDK 2.x to 3.x. Don't initialize an OpenTelemetry distro alongside Application Insights .NET SDK 3.x.

Application Insights .NET SDK 3.x overview

Application Insights .NET SDK 3.x provides these NuGet packages:

• Microsoft.ApplicationInsights for TelemetryClient and TelemetryConfiguration
• Microsoft.ApplicationInsights.AspNetCore for ASP.NET (Active Server Pages .NET) Core web apps
• Microsoft.ApplicationInsights.WorkerService for Worker Service and console apps
• Microsoft.ApplicationInsights.Web for ASP.NET apps on .NET Framework
• Microsoft.ApplicationInsights.NLogTarget for NLog integration (beta)

For code examples and detailed migration guidance, see the repository documentation:

• ApplicationInsights-dotnet README
• SDK concepts
• Migration guidance: Application Insights 2.x to 3.x

Upgrade to 3.x

Remove incompatible packages, upgrade the supported packages, and update your code and configuration.

Step 1: Remove references to incompatible packages

Remove these packages because they're not compatible with SDK 3.x:

• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel
• Microsoft.ApplicationInsights.DependencyCollector
• Microsoft.ApplicationInsights.EventCounterCollector
• Microsoft.ApplicationInsights.PerfCounterCollector
• Microsoft.ApplicationInsights.WindowsServer
• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.ApplicationInsights.Log4NetAppender
• Microsoft.ApplicationInsights.TraceListener
• Microsoft.ApplicationInsights.DiagnosticSourceListener
• Microsoft.ApplicationInsights.EtwCollector
• Microsoft.ApplicationInsights.EventSourceListener

SDK 3.x doesn't publish 3.x versions of these packages. Use the supported 3.x packages listed in Application Insights .NET SDK 3.x overview instead. The following sections describe the intended replacements for these packages. In some cases, the functionality is built into the supported 3.x packages or replaced by OpenTelemetry APIs.

Step 2: Upgrade package versions to 3.x

Upgrade any remaining supported Application Insights packages to the latest 3.x version.

Step 3: Update code and configuration for breaking changes

Review both the breaking changes reference and the detailed migration guidance. Most applications need to update code or configuration in one or more of the following areas:

• Breaking changes: Application Insights 2.x to 3.x
• Migration guidance: Application Insights 2.x to 3.x

Replace removed extensibility points

Application Insights .NET SDK 2.x provided Application Insights-specific extensibility types such as telemetry modules, initializers, processors, and channels. Application Insights .NET SDK 3.x uses OpenTelemetry extensibility instead.

For detailed guidance on replacing 2.x extensibility points, including edge cases, see migration guidance.

Configure sampling

Application Insights .NET SDK 3.x supports two sampling modes for traces (requests and dependencies):

• Set SamplingRatio (0.0 to 1.0) for percentage-based sampling.
• Set TracesPerSecond for rate-limited sampling (default: Five traces per second).

SDK 3.x applies the same sampling settings to requests and dependencies. SDK 3.x doesn't support separate sampling settings for requests and dependencies.

When a request or dependency is sampled in, SDK 3.x applies the sampling decision of the parent trace to related logs by default. To disable that behavior, set EnableTraceBasedLogsSampler to false.

You can set SamplingRatio, TracesPerSecond, and EnableTraceBasedLogsSampler in TelemetryConfiguration, appsettings.json, or applicationinsights.config.

Troubleshoot an upgrade

Use these steps to validate telemetry during an upgrade to SDK 3.x:

• Confirm that a full connection string is configured before startup. If you validate telemetry in tests without a real resource, use a dummy connection string.
• Collect Application Insights self-diagnostics logs to identify configuration errors and exporter failures.
• Add the OpenTelemetry console exporter to verify that traces, metrics, and logs emit as expected before you rely on Azure Monitor ingestion.
• If you previously unit tested telemetry by mocking ITelemetryChannel, switch to OpenTelemetry-friendly validation such as in-memory exporters or other test exporters in nonproduction environments.
• Confirm that sampling settings behave as expected by validating parent-child trace decisions.
• Validate resource attributes such as service name, role name, role instance, and environment to ensure correct attribution in Application Insights.
• If you migrated custom enrichment, verify that your properties appear where you expect. Resource-based mappings can differ from 2.x behavior.

For detailed troubleshooting guidance and examples, use the following resources:

• Application Insights .NET SDK troubleshooting
• Troubleshoot missing application telemetry in Azure Monitor Application Insights
• Troubleshoot high data ingestion in Application Insights

There are typically no code changes when upgrading to 3.x. The 3.x SDK dependencies are no-op API versions of the 2.x SDK dependencies. However, when used with the 3.x Java agent, the 3.x Java agent provides the implementation for them. As a result, your custom instrumentation is correlated with the new autoinstrumentation provided by the 3.x Java agent.

Step 1: Update dependencies

Step 2: Add the 3.x Java agent

Add the 3.x Java agent to your Java Virtual Machine (JVM) command-line args, for example:

-javaagent:"<AgentDirectory>/applicationinsights-agent-3.7.9.jar"

If you're using the Application Insights 2.x Java agent, just replace your existing -javaagent:... with the previous example.

Step 3: Configure your Application Insights connection string

See Configure Azure Monitor OpenTelemetry.

Other notes

The rest of this document describes limitations and changes that you can encounter when upgrading from 2.x to 3.x, and some helpful workarounds.

TelemetryInitializers

TelemetryInitializers from the 2.x SDK don't run when you use the 3.x agent. Many of the use cases that previously required writing a TelemetryInitializer can be solved in Application Insights Java 3.x by configuring custom dimensions or using inherited attributes.

TelemetryProcessors

TelemetryProcessors from the 2.x SDK don't run when you use the 3.x agent. Many of the use cases that previously required writing a TelemetryProcessor can be solved in Application Insights Java 3.x by configuring sampling overrides.

Multiple applications in a single JVM

You can support this use case in Application Insights Java 3.x by using Cloud role name overrides (preview) and Connection string overrides (preview).

Operation names

In the Application Insights Java 2.x SDK, operation names sometimes include the full path. For example:

Operation names in Application Insights Java 3.x generally provide a better aggregated view in the Application Insights portal U/X. For example:

However, for some applications, you might still prefer the aggregated view in the U/X that the previous operation names provided. In this case, use the telemetry processors (preview) feature in 3.x to replicate the previous behavior.

The following snippet configures three telemetry processors that combine to replicate the previous behavior. The telemetry processors perform the following actions (in order):

1. The first telemetry processor is an attribute processor (has type attribute), which means it applies to all telemetry that has attributes (currently requests and dependencies, but soon also traces).

   It matches any telemetry that has attributes named http.request.method and url.path.

   Then it extracts the url.path attribute into a new attribute named tempPath.

2. The second telemetry processor is a span processor (has type span), which means it applies to requests and dependencies.

   It matches any span that has an attribute named tempPath.

   Then it combines http.request.method and tempPath to set the span name.

3. The last telemetry processor is an attribute processor, same type as the first telemetry processor.

   It matches any telemetry that has an attribute named tempPath.

   Then it deletes the attribute named tempPath. The attribute appears as a custom dimension.

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": ["http.request.method", "tempPath"],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

Sampling and missing logs

Starting with version 3.4, the agent enables rate-limited sampling by default. This sampling can cause unexpected missing logs.

Project example

This Java 2.x SDK project is migrated to a new project using the 3.x Java agent.

This guide provides two options to upgrade from the Application Insights Node.js SDK 2.X to OpenTelemetry.

• Clean install the Microsoft OpenTelemetry Distro for Node.js.

  • Remove dependencies on the Application Insights classic API.
  • Familiarize yourself with OpenTelemetry APIs and terms.
  • Position yourself to use all that OpenTelemetry offers now and in the future.

• Upgrade to Node.js SDK 3.X.

  • Postpone code changes while preserving compatibility with existing custom events and metrics.
  • Access richer OpenTelemetry instrumentation libraries.
  • Maintain eligibility for the latest bug and security fixes.

Clean install

1. Gain prerequisite knowledge of the OpenTelemetry JavaScript Application Programming Interface (API) and Software Development Kit (SDK).

   • Read OpenTelemetry JavaScript documentation.
   • Review Configure OpenTelemetry in Application Insights.
   • Evaluate Add, modify, and filter OpenTelemetry.

2. Uninstall the applicationinsights dependency from your project.

   npm uninstall applicationinsights
   

3. Remove SDK 2.X implementation from your code.

   Remove all Application Insights instrumentation from your code. Delete any sections where the Application Insights client is initialized, modified, or called.

4. Enable Application Insights with the Microsoft OpenTelemetry Distro.

   Important

Call useMicrosoftOpenTelemetry() before loading libraries you want to instrument. If those libraries load first, you might lose telemetry. For ESM applications, preload the Microsoft OpenTelemetry Distro loader.

Follow getting started to install @microsoft/opentelemetry and enable Azure Monitor export.

Microsoft OpenTelemetry Distro changes and limitations

• The Microsoft OpenTelemetry Distro doesn't expose the Application Insights SDK 2.x APIs. Use OpenTelemetry APIs for custom events, metrics, and spans. Keep the Application Insights SDK 3.x upgrade path separate if you need its classic API compatibility.
• Review the Microsoft OpenTelemetry Distro's instrumentation and processor options when replacing filters and other SDK-specific configuration.

Upgrade

1. Upgrade the applicationinsights package dependency to version 3.x.

   npm install applicationinsights@^3
   

2. Rebuild your application.

3. Test your application.

   To avoid using unsupported configuration options in the Application Insights SDK 3.X, see Unsupported Properties.

   If the SDK logs warnings about unsupported API usage after a major version bump, and you need the related functionality, continue using the Application Insights SDK 2.X.

Changes and limitations

The following sections distinguish the Microsoft OpenTelemetry Distro clean-install path from the Application Insights SDK upgrade path.

Node.js version support

The Microsoft OpenTelemetry Distro for Node.js requires Node.js 22 or later. See its runtime and startup requirements.

The Application Insights 3.x SDK supports a Node.js version when both the Azure SDK for JavaScript and OpenTelemetry support that Node.js version. For current OpenTelemetry runtime support, see OpenTelemetry supported runtimes.

If you use an older Node.js version such as Node 8, OpenTelemetry solutions can run but can produce unexpected behavior or breaking changes. The Application Insights SDK relies on the Azure SDK for JavaScript, and the Azure SDK for JavaScript support policy doesn't guarantee support for Node.js versions that reached end of life. For details, see Azure SDK for JS support policy.

Configuration options

The Microsoft OpenTelemetry Distro uses MicrosoftOpenTelemetryOptions, not the Application Insights SDK 2.x configuration API. Azure Monitor-specific options are nested under azureMonitor; resource, sampling, instrumentation, and processor options are at the top level. See the Microsoft OpenTelemetry Distro configuration reference.

For the separate Application Insights SDK 3.x upgrade path, review the SDK's unsupported properties.

Extended metrics

The Application Insights SDK 2.x extended-metrics configuration doesn't carry over to the Microsoft OpenTelemetry Distro. Review the distro's standard metrics and performance-counter settings instead. For the Application Insights SDK 3.x path, review its unsupported properties.

Telemetry processors

The Microsoft OpenTelemetry Distro uses OpenTelemetry span and log record processors instead of classic telemetry processors. Register them with spanProcessors or logRecordProcessors. See the Microsoft OpenTelemetry Distro configuration reference. For the separate SDK 3.x path, use that SDK's configuration guidance.

This example shows the equivalent of creating and applying a telemetry processor that attaches a custom property in the Application Insights SDK 2.X.

import * as applicationInsights from "applicationinsights";
applicationInsights.setup("<ConnectionString>");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: applicationInsights.Contracts.EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

This example registers a span processor with the Microsoft OpenTelemetry Distro to add a custom property before export. Set APPLICATIONINSIGHTS_CONNECTION_STRING before running it.

import { Context, Span } from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";

// Import the Microsoft OpenTelemetry Distro.
const { useMicrosoftOpenTelemetry } = require("@microsoft/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();
    }
}

// Configure Azure Monitor export and the options used by this sample.
const options = {
    azureMonitor: {
        azureMonitorExporterOptions: {
            connectionString: "<ConnectionString>",
        },
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};

// Initialize the Microsoft OpenTelemetry Distro.
useMicrosoftOpenTelemetry(options);

Follow these steps to migrate Python applications to the Microsoft OpenTelemetry Distro.

Step 1: Uninstall OpenCensus libraries

Uninstall all libraries related to OpenCensus, including all PyPI packages that start with opencensus-*.

pip freeze | grep opencensus | xargs pip uninstall -y

Step 2: Remove OpenCensus from your code

Remove all instances of the OpenCensus SDK and the Azure Monitor OpenCensus exporter from your code.

Check for import statements starting with opencensus to find all integrations, exporters, and instances of OpenCensus API/SDK that you must remove.

The following examples show import statements that you must remove.

from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

from opencensus.ext.azure.log_exporter import AzureLogHandler

Step 3: Familiarize yourself with OpenTelemetry Python APIs and SDKs

The following documentation provides prerequisite knowledge of the OpenTelemetry Python APIs and SDKs:

• OpenTelemetry Python documentation
• Microsoft OpenTelemetry Distro documentation on configuration and telemetry.

Set up the Microsoft OpenTelemetry Distro

Follow the getting started article to install microsoft-opentelemetry and initialize it with use_microsoft_opentelemetry(enable_azure_monitor=True). Set APPLICATIONINSIGHTS_CONNECTION_STRING before starting your application. Remove the older distro initialization if you previously used configure_azure_monitor().

Changes and limitations

The following changes and limitations can occur when migrating from OpenCensus to OpenTelemetry.

Python versions earlier than 3.10

The Microsoft OpenTelemetry Distro for Python requires Python 3.10 or later. For prerequisites and supported versions, see the Microsoft OpenTelemetry Distro for Python.

For Python version status and end-of-life dates, go to Python version support.

If you stay on Python 2.7, 3.4, 3.5, or 3.6, OpenTelemetry solutions can run but can produce unexpected behavior or breaking changes that Microsoft doesn't support.

For OpenCensus, the last released version of opencensus-ext-azure runs on these Python versions. The project doesn't publish new releases.

Configurations

OpenCensus Python configuration doesn't map one-to-one to the Microsoft OpenTelemetry Distro. Use its configuration reference and OpenTelemetry APIs. Enable Azure Monitor explicitly with enable_azure_monitor=True. Azure Monitor exporter settings use prefixed keywords such as azure_monitor_connection_string and azure_monitor_exporter_credential.

The distro supports additional span processors, log record processors, and metric readers. Configure sampling through OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG. For a custom pipeline outside the distro, the standalone Azure Monitor OpenTelemetry exporter retains its existing package name and API.

Cohesion with Azure Functions

To provide distributed tracing capabilities for Python applications that call other Python applications within an Azure function, the package opencensus-extension-azure-functions creates a connected distributed graph.

Currently, the OpenTelemetry solutions for Azure Monitor don't support this scenario. As a workaround, you can manually propagate the trace context in your Azure functions application as shown in the following example.

from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator


# Context parameter is provided for the body of the function
def main(req, context):
    functionsCurrentContext = {
        "traceparent": context.trace_context.Traceparent,
        "tracestate": context.trace_context.Tracestate,
    }
    parentContext = TraceContextTextMapPropagator().extract(
        carrier=functionsCurrentContext
    )
    token = attach(parentContext)

    ...
    # Function logic
    ...
    detach(token)

Extensions and exporters

The OpenCensus SDK provides integrations to collect telemetry and exporters to send telemetry. In OpenTelemetry, integrations are called instrumentations. OpenTelemetry also uses the term exporters.

OpenTelemetry Python instrumentations and exporters cover the OpenCensus set and add more libraries. OpenTelemetry provides a direct upgrade in library coverage and functionality.

The Microsoft OpenTelemetry Distro includes OpenTelemetry Python instrumentation libraries. It instruments supported libraries when they are installed in your application. Review the Microsoft OpenTelemetry Distro's instrumentation list and defaults.

As for the other OpenTelemetry Python instrumentations that aren't included in this list, you can still manually instrument with them. However, stability and behavior aren't guaranteed or supported in those cases. Therefore, use them at your own discretion.

If you want to suggest a community instrumentation library for inclusion in the distro, post or up-vote an idea in the feedback community. The Microsoft OpenTelemetry Distro includes Azure Monitor export and can also send telemetry through OTLP. See Enable the OTLP exporter.

Telemetry processors

The OpenTelemetry world doesn't have telemetry processors, but it does have APIs and classes that you can use to replicate the same behavior.

Setting cloud role name and cloud role instance

To set the cloud role name and cloud role instance, see OpenTelemetry configuration. The Microsoft OpenTelemetry Distro reads standard OpenTelemetry resource environment variables, and its Azure Monitor integration maps the resource attributes to the Application Insights fields.

Modifying spans with SpanProcessors

Coming soon.

Modifying metrics with Views

Coming soon.

Performance counters

The OpenCensus Python Azure Monitor exporter automatically collects system and performance related metrics called performance counters. These metrics appear in performanceCounters in your Application Insights instance. In OpenTelemetry, you no longer send these metrics explicitly to performanceCounters. Metrics related to incoming and outgoing requests can be found under standard metrics. If you want OpenTelemetry to autocollect system related metrics, you can use the experimental system metrics instrumentation, contributed by the OpenTelemetry Python community. This package is experimental and isn't officially supported by Microsoft.

Support

To review troubleshooting steps, support options, or to provide OpenTelemetry feedback, see OpenTelemetry troubleshooting, support, and feedback for Azure Monitor Application Insights.