Migrate from Application Insights Classic API SDKs to Azure Monitor 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.

If you build a new application or you already use the Azure Monitor OpenTelemetry Distro, use the Azure Monitor OpenTelemetry Distro instead. Don't use Application Insights .NET SDK 3.x and the Azure Monitor OpenTelemetry Distro in the same application.

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

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:path/to/applicationinsights-agent-3.7.8.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 tempName.

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 updates the span name from the attribute tempPath.

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": "https?://[^/]+(?<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 Node.js Azure Monitor OpenTelemetry Distro.

  • 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 Azure Monitor OpenTelemetry.
   • 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 Azure Monitor OpenTelemetry Distro.

   Important

   Before you import anything else, call useAzureMonitor. If you import other libraries first, you might lose telemetry. Follow getting started to onboard to the Azure Monitor OpenTelemetry Distro.

Azure Monitor OpenTelemetry Distro changes and limitations

• The APIs from the Application Insights SDK 2.X aren't available in the Azure Monitor OpenTelemetry Distro. While Application Insights SDK 3.X provides a nonbreaking upgrade path for telemetry ingestion (such as custom events and metrics), most SDK 2.X APIs aren't supported and require code changes to OpenTelemetry-based APIs.
• Filtering dependencies, logs, and exceptions by operation name isn't supported yet.

Upgrade

1. Upgrade the applicationinsights package dependency.

   npm update applicationinsights
   

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 changes and limitations apply to both upgrade paths.

Node.js version support

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 Application Insights SDK version 2.X offers configuration options that aren't available in the Azure Monitor OpenTelemetry Distro or in the major version upgrade to Application Insights SDK 3.X. To find these changes, along with the options the SDK still supports, see SDK configuration documentation.

Extended metrics

The Application Insights SDK 2.X supports extended metrics. However, support for these metrics ends in both version 3.X of the ApplicationInsights SDK and the Azure Monitor OpenTelemetry Distro.

Telemetry processors

While the Azure Monitor OpenTelemetry Distro and Application Insights SDK 3.X don't support telemetry processors, they do allow you to pass span and log record processors. For more information, see Azure Monitor OpenTelemetry Distro project.

This example shows the equivalent of creating and applying a telemetry processor that attaches a custom property in the 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;
}

This example shows how to modify an Azure Monitor OpenTelemetry Distro implementation to pass a SpanProcessor to the configuration of the distro.

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

Follow these steps to migrate Python applications to the Azure Monitor 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
• Azure Monitor Distro documentation on configuration and telemetry

Step 4: Set up the Azure Monitor OpenTelemetry Distro

Follow the getting started article to onboard to the Azure Monitor OpenTelemetry Distro.

Changes and limitations

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

Python versions earlier than 3.10

The Azure Monitor OpenTelemetry Distro for Python requires Python 3.10 or later. For prerequisites and supported versions, see the Azure Monitor Opentelemetry Distro client library 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 provides configuration options related to the collection and exporting of telemetry. You can achieve the same configurations, and more, by using the OpenTelemetry Python APIs and SDK. The OpenTelemetry Azure monitor Python Distro is a one-stop shop for the most common monitoring needs for your Python applications. Since the Distro encapsulates the OpenTelemetry APIs and SDK, some configuration for more uncommon use cases might not currently be supported. Instead, you can opt to onboard onto the Azure monitor OpenTelemetry exporter, which, by using the OpenTelemetry APIs and SDKs, should be able to fit your monitoring needs. Some of these configurations include:

• Custom propagators
• Custom samplers
• Adding extra span, log processors, and metrics readers

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):
  functions_current_context = {
    "traceparent": context.trace_context.Traceparent,
    "tracestate": context.trace_context.Tracestate
  }
  parent_context = TraceContextTextMapPropagator().extract(
      carrier=functions_current_context
  )
  token = attach(parent_context)

  ...
  # 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 Azure Monitor OpenTelemetry Distro includes several popular OpenTelemetry Python instrumentations. Use these instrumentations without adding code. Microsoft supports these instrumentations.

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. For exporters, the Azure Monitor OpenTelemetry distro comes bundled with the Azure Monitor OpenTelemetry exporter. If you want to use other exporters as well, you can use them with the distro, like in this example.

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 for your telemetry, see OpenTelemetry configuration. The OpenTelemetry Azure Monitor Distro automatically fetches the values from the environment variables and fills the respective 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.