Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications

This article describes how to enable and configure OpenTelemetry-based data collection to power the experiences within Azure Monitor Application Insights. We walk through how to install the "Azure Monitor OpenTelemetry Distro." The Distro automatically collects traces, metrics, logs, and exceptions across your application and its dependencies. To learn more about collecting data using OpenTelemetry, see Data Collection Basics or OpenTelemetry FAQ.

OpenTelemetry Release Status

OpenTelemetry offerings are available for .NET, Node.js, Python and Java applications.

Language	Release Status
ASP.NET Core	⚠️ 2
.NET (Exporter)	✅ 1
Java	✅ 1
Node.js	✅ 1
Python	✅ 1

Footnotes

• ✅ 1: OpenTelemetry is available to all customers with formal support.
• ⚠️ 2: OpenTelemetry is available as a public preview. Supplemental Terms of Use for Microsoft Azure Previews

Note

For a feature-by-feature release status, see the FAQ. The ASP.NET Core Distro is undergoing additional stability testing prior to GA. You can use the .NET Exporter if you need a fully supported OpenTelemetry solution for your ASP.NET Core application.

Get started

Follow the steps in this section to instrument your application with OpenTelemetry.

Prerequisites

• An Azure subscription: Create an Azure subscription for free
• An Application Insights resource: Create an Application Insights resource

ASP.NET Core

• ASP.NET Core Application using an officially supported version of .NET Core

.NET

• Application using an officially supported version of .NET Core or .NET Framework that's at least .NET Framework 4.6.2

Java

• A Java application using Java 8+

Node.js

Note

If you rely on any properties in the not-supported table, use the distro, and we'll provide a migration guide soon. If not, the App Insights shim is your easiest path forward when it's out of beta.

• Application using an officially supported version of Node.js runtime:
  • OpenTelemetry supported runtimes
  • Azure Monitor OpenTelemetry Exporter supported runtimes

Python

• Python Application using Python 3.7+

Tip

We don't recommend using the OTel Community SDK/API with the Azure Monitor OTel Distro since it automatically loads them as dependencies.

Install the client library

ASP.NET Core

Install the latest Azure.Monitor.OpenTelemetry.AspNetCore NuGet package:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore 

.NET

Install the latest Azure.Monitor.OpenTelemetry.Exporter NuGet package:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter 

Java

Download the applicationinsights-agent-3.4.17.jar file.

Warning

If you are upgrading from an earlier 3.x version, you may be impacted by changing defaults or slight differences in the data we collect. For more information, see the migration section in the release notes. 3.4.0, 3.3.0, 3.2.0, and 3.1.0

Node.js

Install these packages:

• @azure/monitor-opentelemetry

npm install @azure/monitor-opentelemetry

The following packages are also used for some specific scenarios described later in this article:

• @opentelemetry/api
• @opentelemetry/sdk-metrics
• @opentelemetry/resources
• @opentelemetry/semantic-conventions
• @opentelemetry/sdk-trace-base

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics
npm install @opentelemetry/resources
npm install @opentelemetry/semantic-conventions
npm install @opentelemetry/sdk-trace-base

Python

Install the latest azure-monitor-opentelemetry PyPI package:

pip install azure-monitor-opentelemetry

Enable Azure Monitor Application Insights

To enable Azure Monitor Application Insights, you make a minor modification to your application and set your "Connection String." The Connection String tells your application where to send the telemetry the Distro collects, and it's unique to you.

Modify your Application

ASP.NET Core

Add UseAzureMonitor() to your application startup. Depending on your version of .NET, it is in either your startup.cs or program.cs class.

// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;

// Create a new WebApplicationBuilder instance.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry NuGet package to the application's services and configure OpenTelemetry to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the application.
var app = builder.Build();

// Run the application.
app.Run();

.NET

Add the Azure Monitor Exporter to each OpenTelemetry signal in application startup. Depending on your version of .NET, it is in either your startup.cs or program.cs class.

// Create a new tracer provider builder and add an Azure Monitor trace exporter to the tracer provider builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter();

// Add an Azure Monitor metric exporter to the metrics provider builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter();
    });
});

Note

For more information, see the getting-started tutorial for OpenTelemetry .NET

Java

Java autoinstrumentation is enabled through configuration changes; no code changes are required.

Point the JVM to the jar file by adding -javaagent:"path/to/applicationinsights-agent-3.4.17.jar" to your application's JVM args.

Tip

For scenario-specific guidance, see Get Started (Supplemental).

Tip

If you develop a Spring Boot application, you can optionally replace the JVM argument by a programmatic configuration. For more information, see Using Azure Monitor Application Insights with Spring Boot.

Node.js

// Import the `useAzureMonitor()` function from the `@azure/monitor-opentelemetry` package.
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

// Call the `useAzureMonitor()` function to configure OpenTelemetry to use Azure Monitor.
useAzureMonitor();

Python

# Import the `configure_azure_monitor()` function from the
# `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Import the tracing api from the `opentelemetry` package.
from opentelemetry import trace

# Configure OpenTelemetry to use Azure Monitor with the specified connection
# string.
configure_azure_monitor(
    connection_string="<Your Connection String>",
)

# Get a tracer for the current module.
tracer = trace.get_tracer(__name__)

# Start a new span with the name "hello". This also sets this created span as the current span in this context. This span will be exported to Azure Monitor as part of the trace.
with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Wait for export to take place in the background.
input()

Copy the Connection String from your Application Insights Resource

Tip

If you don't already have one, now is a great time to Create an Application Insights Resource. Here's when we recommend you create a new Application Insights Resource versus use an existing one.

To copy your unique Connection String:

1. Go to the Overview pane of your Application Insights resource.
2. Find your Connection String.
3. Hover over the connection string and select the Copy to clipboard icon.

Paste the Connection String in your environment

To paste your Connection String, select from the following options:

A. Set via Environment Variable (Recommended)

Replace <Your Connection String> in the following command with your unique connection string.

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

B. Set via Configuration File - Java Only (Recommended)

Create a configuration file named applicationinsights.json, and place it in the same directory as applicationinsights-agent-3.4.17.jar with the following content:

{
  "connectionString": "<Your Connection String>"
}

Replace <Your Connection String> in the preceding JSON with your unique connection string.

C. Set via Code - ASP.NET Core, Node.js, and Python Only (Not recommended)

See Connection String Configuration for an example of setting Connection String via code.

Note

If you set the connection string in more than one place, we adhere to the following precendence:

1. Code
2. Environment Variable
3. Configuration File

Confirm data is flowing

Run your application and open your Application Insights Resource tab in the Azure portal. It might take a few minutes for data to show up in the portal.

You've now enabled Application Insights for your application. All the following steps are optional and allow for further customization.

Important

If you have two or more services that emit telemetry to the same Application Insights resource, you're required to set Cloud Role Names to represent them properly on the Application Map.

As part of using Application Insights instrumentation, we collect and send diagnostic data to Microsoft. This data helps us run and improve Application Insights. To learn more, see Statsbeat in Azure Application Insights.

Troubleshooting

ASP.NET Core

Not working? Check out the troubleshooting page for ASP.NET Core.

.NET

Not working? Check out the troubleshooting page for .NET.

Java

Not working? Check out the troubleshooting page for Java.

Node.js

Not working? Check out the troubleshooting page for Node.js.

Python

Not working? Check out the troubleshooting page for Python.

Support

Select a tab for the language of your choice to discover support options.

ASP.NET Core

• For Azure support issues, open an Azure support ticket.
• For OpenTelemetry issues, contact the OpenTelemetry .NET community directly.
• For a list of open issues related to Azure Monitor Exporter, see the GitHub Issues Page.

.NET

• For Azure support issues, open an Azure support ticket.
• For OpenTelemetry issues, contact the OpenTelemetry .NET community directly.
• For a list of open issues related to Azure Monitor Exporter, see the GitHub Issues Page.

Java

• For Azure support issues, open an Azure support ticket.
• For help with troubleshooting, review the troubleshooting steps.
• For OpenTelemetry issues, contact the OpenTelemetry community directly.
• For a list of open issues related to Azure Monitor Java Autoinstrumentation, see the GitHub Issues Page.

Node.js

• For Azure support issues, open an Azure support ticket.
• For OpenTelemetry issues, contact the OpenTelemetry JavaScript community directly.
• For a list of open issues related to Azure Monitor Exporter, see the GitHub Issues Page.

Python

• For Azure support issues, open an Azure support ticket.
• For OpenTelemetry issues, contact the OpenTelemetry Python community directly.
• For a list of open issues related to Azure Monitor Distro, see the GitHub Issues Page.

OpenTelemetry feedback

To provide feedback:

• Fill out the OpenTelemetry community's customer feedback survey.
• Tell Microsoft about yourself by joining the OpenTelemetry Early Adopter Community.
• Engage with other Azure Monitor users in the Microsoft Tech Community.
• Make a feature request at the Azure Feedback Forum.

Next steps

ASP.NET Core

• For details on adding and modifying Azure Monitor OpenTelemetry, see Add and modify Azure Monitor OpenTelemetry
• To further configure the OpenTelemetry distro, see Azure Monitor OpenTelemetry configuration
• To review the source code, see the Azure Monitor AspNetCore GitHub repository.
• To install the NuGet package, check for updates, or view release notes, see the Azure Monitor AspNetCore NuGet Package page.
• To become more familiar with Azure Monitor and OpenTelemetry, see the Azure Monitor Example Application.
• To learn more about OpenTelemetry and its community, see the OpenTelemetry .NET GitHub repository.
• To enable usage experiences, enable web or browser user monitoring.

.NET

• For details on adding and modifying Azure Monitor OpenTelemetry, see Add and modify Azure Monitor OpenTelemetry
• To further configure the OpenTelemetry distro, see Azure Monitor OpenTelemetry configuration
• To review the source code, see the Azure Monitor Exporter GitHub repository.
• To install the NuGet package, check for updates, or view release notes, see the Azure Monitor Exporter NuGet Package page.
• To become more familiar with Azure Monitor and OpenTelemetry, see the Azure Monitor Example Application.
• To learn more about OpenTelemetry and its community, see the OpenTelemetry .NET GitHub repository.
• To enable usage experiences, enable web or browser user monitoring.

Java

• For details on adding and modifying Azure Monitor OpenTelemetry, see Add and modify Azure Monitor OpenTelemetry
• Review Java autoinstrumentation configuration options.
• To review the source code, see the Azure Monitor Java autoinstrumentation GitHub repository.
• To learn more about OpenTelemetry and its community, see the OpenTelemetry Java GitHub repository.
• To enable usage experiences, see Enable web or browser user monitoring.
• See the release notes on GitHub.

Node.js

• For details on adding and modifying Azure Monitor OpenTelemetry, see Add and modify Azure Monitor OpenTelemetry
• To review the source code, see the Azure Monitor OpenTelemetry GitHub repository.
• To install the npm package and check for updates, see the @azure/monitor-opentelemetry npm Package page.
• To become more familiar with Azure Monitor Application Insights and OpenTelemetry, see the Azure Monitor Example Application.
• To learn more about OpenTelemetry and its community, see the OpenTelemetry JavaScript GitHub repository.
• To enable usage experiences, enable web or browser user monitoring.

Python

• For details on adding and modifying Azure Monitor OpenTelemetry, see Add and modify Azure Monitor OpenTelemetry
• To review the source code and extra documentation, see the Azure Monitor Distro GitHub repository.
• To see extra samples and use cases, see Azure Monitor Distro samples.
• See the release notes on GitHub.
• To install the PyPI package, check for updates, or view release notes, see the Azure Monitor Distro PyPI Package page.
• To become more familiar with Azure Monitor Application Insights and OpenTelemetry, see the Azure Monitor Example Application.
• To learn more about OpenTelemetry and its community, see the OpenTelemetry Python GitHub repository.
• To see available OpenTelemetry instrumentations and components, see the OpenTelemetry Contributor Python GitHub repository.
• To enable usage experiences, enable web or browser user monitoring.