title | description | ms.topic | ms.date | ms.devlang | ms.custom | ms.reviewer |
---|---|---|---|---|---|---|
Enable Azure Monitor OpenTelemetry for .NET, Java, Node.js, and Python applications |
This article provides guidance on how to enable Azure Monitor on applications by using OpenTelemetry. |
conceptual |
07/29/2024 |
csharp |
devx-track-dotnet, devx-track-extended-java, devx-track-python |
mmcc |
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 Azure Monitor OpenTelemetry Distro provides an OpenTelemetry distribution that includes support for features specific to Azure Monitor. The Distro enables automatic telemetry by including OpenTelemetry instrumentation libraries for collecting traces, metrics, logs, and exceptions, and allows collecting custom telemetry. You can also use the Live Metrics feature included in the Distro to monitor and collect more telemetry from live, in-production web applications. For more information about the advantages of using the Azure Monitor OpenTelemetry Distro, see Why should I use the "Azure Monitor OpenTelemetry Distro"?.
To learn more about collecting data using OpenTelemetry, see Data Collection Basics or OpenTelemetry FAQ.
OpenTelemetry offerings are available for .NET, Node.js, Python, and Java applications.
Note
- For a feature-by-feature release status, see the FAQ.
- The second tab of this article covers all .NET scenarios, including classic ASP.NET, console apps, Windows Forms (WinForms), etc.
Follow the steps in this section to instrument your application with OpenTelemetry.
- An Azure subscription: Create an Azure subscription for free
- An Application Insights resource: Create an Application Insights resource
- ASP.NET Core Application using an officially supported version of .NET
Tip
If you're migrating from the Application Insights Classic API, see our migration documentation.
- Application using an officially supported version of .NET Core or .NET Framework that's at least .NET Framework 4.6.2
Tip
If you're migrating from the Application Insights Classic API, see our migration documentation.
- A Java application using Java 8+
- A Java application using GraalVM 17+
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:
Tip
If you're migrating from the Application Insights Classic API, see our migration documentation.
- Python Application using Python 3.8+
Tip
If you're migrating from OpenCensus, see our migration documentation.
Install the latest Azure.Monitor.OpenTelemetry.AspNetCore
NuGet package:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Install the latest Azure.Monitor.OpenTelemetry.Exporter
NuGet package:
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
Download the applicationinsights-agent-3.5.4.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.5.0, 3.4.0, 3.3.0, 3.2.0, and 3.1.0
For Spring Boot native applications:
- Import the OpenTelemetry Bills of Materials (BOM).
- Add the Spring Cloud Azure Starter Monitor dependency.
- Follow these instructions for the Azure SDK JAR (Java Archive) files.
For Quarkus native applications:
- Add the Quarkus OpenTelemetry Exporter for Azure dependency.
Install these packages:
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
Install the latest azure-monitor-opentelemetry PyPI package:
pip install azure-monitor-opentelemetry
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.
Add UseAzureMonitor()
to your application startup, located in your 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 OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();
// Build the application.
var app = builder.Build();
// Run the application.
app.Run();
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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
var metricsProvider = Sdk.CreateMeterProviderBuilder()
.AddAzureMonitorMetricExporter();
// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
var loggerFactory = LoggerFactory.Create(builder =>
{
builder.AddOpenTelemetry(options =>
{
options.AddAzureMonitorLogExporter();
});
});
Note
For more information, see the getting-started tutorial for OpenTelemetry .NET
Java autoinstrumentation is enabled through configuration changes; no code changes are required.
Point the Java virtual machine (JVM) to the jar file by adding -javaagent:"path/to/applicationinsights-agent-3.5.4.jar"
to your application's JVM args.
Tip
Sampling is enabled by default at a rate of 5 requests per second, aiding in cost management. Telemetry data may be missing in scenarios exceeding this rate. For more information on modifying sampling configuration, see sampling overrides.
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.
Several automatic instrumentations are enabled through configuration changes; no code changes are required
// 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();
# 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
# APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
configure_azure_monitor()
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:
:::image type="content" source="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png" alt-text="Screenshot that shows Application Insights overview and connection string." lightbox="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png":::
- Go to the Overview pane of your Application Insights resource.
- Find your Connection String.
- Hover over the connection string and select the Copy to clipboard icon.
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.5.4.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 precedence:
- Code
- Environment Variable
- Configuration File
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.
:::image type="content" source="media/opentelemetry/server-requests.png" alt-text="Screenshot of the Application Insights Overview tab with server requests and server response time highlighted.":::
Application Insights is now enabled 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.
Azure Monitor OpenTelemetry sample applications are available for all supported languages.
- 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.
- 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.
- See Add and modify Azure Monitor OpenTelemetry for details on adding and modifying Azure Monitor OpenTelemetry.
- Review Java autoinstrumentation configuration options.
- Review the source code in the Azure Monitor Java autoinstrumentation GitHub repository.
- Learn more about OpenTelemetry and its community in the OpenTelemetry Java GitHub repository.
- Enable usage experiences by seeing Enable web or browser user monitoring.
- Review the release notes on GitHub.
- See Add and modify Azure Monitor OpenTelemetry for details on adding and modifying Azure Monitor OpenTelemetry.
- Review the source code in the Azure Monitor OpenTelemetry Distro in Spring Boot native image Java application and Quarkus OpenTelemetry Exporter for Azure.
- Learn more about OpenTelemetry and its community in the OpenTelemetry Java GitHub repository.
- Learn more features for Spring Boot native image applications in OpenTelemetry SpringBoot starter
- Learn more features for Quarkus native applications in Quarkus OpenTelemetry Exporter for Azure.
- Review the release notes on GitHub.
- 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.
- See Add and modify Azure Monitor OpenTelemetry for details on adding and modifying Azure Monitor OpenTelemetry.
- Review the source code and extra documentation in the Azure Monitor Distro GitHub repository.
- See extra samples and use cases in Azure Monitor Distro samples.
- Review the changelog on GitHub.
- Install the PyPI package, check for updates, or view release notes on the Azure Monitor Distro PyPI Package page.
- Become more familiar with Azure Monitor Application Insights and OpenTelemetry in the Azure Monitor Example Application.
- Learn more about OpenTelemetry and its community in the OpenTelemetry Python GitHub repository.
- See available OpenTelemetry instrumentations and components in the OpenTelemetry Contributor Python GitHub repository.
- Enable usage experiences by enabling web or browser user monitoring.