Migrate from the Node.js Application Insights SDK 2.X to Azure Monitor OpenTelemetry

This guide provides two options to upgrade from the Azure Monitor 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, useAzureMonitor must be called. There might be telemetry loss if other libraries are imported first. 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. You can access these APIs through a nonbreaking upgrade path in the Application Insights SDK 3.X.
• Filtering dependencies, logs, and exceptions by operation name is not yet supported.

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

For a version of Node.js to be supported by the ApplicationInsights 3.X SDK, it must have overlapping support from both the Azure SDK and OpenTelemetry. Check the OpenTelemetry supported runtimes for the latest updates. Users on older versions like Node 8, previously supported by the ApplicationInsights SDK, can still use OpenTelemetry solutions but can experience unexpected or breaking behavior. The ApplicationInsights SDK also depends on the Azure SDK for JS which does not guarantee support for any Node.js versions that have reached end-of-life. See the Azure SDK for JS support policy. For a version of Node.js to be supported by the ApplicationInsights 3.X SDK, it must have overlapping support from both the Azure SDK and OpenTelemetry.

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 we still support, see SDK configuration documentation.

Extended metrics

Extended metrics are supported in the Application Insights SDK 2.X; 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 TelemetryProcessors, they do allow you to pass span and log record processors. For more information on how, 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);