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

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.

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 the latest @azure/monitor-opentelemetry package:

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

Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace, add OpenTelemetry, and configure it to use Azure Monitor in your program.cs class:

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

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

Add the Azure Monitor Exporter to each OpenTelemetry signal in the 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();
    });
});

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.

Autoinstrumentation is 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()

• 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.

Step 1: Enable diagnostic logging

The Azure Monitor Exporter uses EventSource for its internal logging. The exporter logs are available to any EventListener by opting in to the source that's named OpenTelemetry-AzureMonitor-Exporter. For troubleshooting steps, see OpenTelemetry Troubleshooting on GitHub.

Step 2: Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Known issues

The following items are known issues for the Azure Monitor OpenTelemetry Exporters:

• The operation name is missing from dependency telemetry. The missing operation name causes failures and adversely affects performance tab experience.

• The device model is missing from request and dependency telemetry. The missing device model adversely affects device cohort analysis.

Step 1: Enable diagnostic logging

The Azure Monitor Exporter uses EventSource for its internal logging. The exporter logs are available to any EventListener by opting in to the source that's named OpenTelemetry-AzureMonitor-Exporter. For troubleshooting steps, see OpenTelemetry Troubleshooting on GitHub.

Step 2: Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Known issues

The following items are known issues for the Azure Monitor OpenTelemetry Exporters:

• The operation name is missing from dependency telemetry. The missing operation name causes failures and adversely affects performance tab experience.

• The device model is missing from request and dependency telemetry. The missing device model adversely affects device cohort analysis.

Step 1: Enable diagnostic logging

By default, diagnostic logging is enabled in Azure Monitor Application Insights. For more information, see Troubleshoot guide: Azure Monitor Application Insights for Java.

Step 2: Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Known issues

• If you download the Application Insights client library for installation from a browser, sometimes the downloaded JAR file is corrupted and is about half the size of the source file. If you experience this problem, download the JAR file by running the curl or wget command, as shown in the following example command calls:

  curl --location --output applicationinsights-agent-3.4.11.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.4.11/applicationinsights-agent-3.4.11.jar
  

  wget --output-document=applicationinsights-agent-3.4.11.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.4.11/applicationinsights-agent-3.4.11.jar
  

  Note

  The example command calls apply to Application Insights for Java version 3.4.11. To find the version number and URL address of the current release of Application Insights for Java, see https://github.com/microsoft/ApplicationInsights-Java/releases.

The following steps are applicable to Spring Boot native applications.

Step 1: Verify the OpenTelemetry version

You might notice the following message during the application startup:

WARN  c.a.m.a.s.OpenTelemetryVersionCheckRunner - The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency.
The OpenTelemetry version should be <version>

In this case, you have to import the OpenTelemetry Bills of Materials by following the OpenTelemetry documentation in the Spring Boot starter.

Step 2: Enable self-diagnostics

If something doesn't work as expected, you can enable self-diagnostics at the DEBUG level to get some insights. To do so, set the self-diagnostics level to ERROR, WARN, INFO, DEBUG, or TRACE by using the APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL environment variable.

To enable self-diagnostics at the DEBUG level when running a docker container, run the following command:

docker run -e APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL=DEBUG <image-name>

Third-party information disclaimer

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, about the performance or reliability of these products.

Step 1: Enable diagnostic logging

Azure Monitor Exporter uses the OpenTelemetry API logger for internal logs. To enable the logger, run the following code snippet:

const { diag, DiagConsoleLogger, DiagLogLevel } = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

Step 2: Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Known issues

The following items are known issues for the Azure Monitor OpenTelemetry Exporters:

• The operation name is missing from dependency telemetry. The missing operation name causes failures and adversely affects performance tab experience.

• The device model is missing from request and dependency telemetry. The missing device model adversely affects device cohort analysis.

• The database server name is missing from the dependency name. Because the database server name isn't included, OpenTelemetry Exporters incorrectly aggregate tables that have the same name onto different servers.

Step 1: Enable diagnostic logging

The Microsoft Azure Monitor Exporter uses the Python standard logging library for its internal logging. OpenTelemetry API and Azure Monitor Exporter logs are assigned a severity level of WARNING or ERROR for irregular activity. The INFO severity level is used for regular or successful activity.

By default, the Python logging library sets the severity level to WARNING. Therefore, you must change the severity level to see logs under this severity setting. The following example code shows how to output logs of all severity levels to the console and a file:

...
import logging

logging.basicConfig(format = "%(asctime)s:%(levelname)s:%(message)s", level = logging.DEBUG)

logger = logging.getLogger(__name__)
file = logging.FileHandler("example.log")
stream = logging.StreamHandler()
logger.addHandler(file)
logger.addHandler(stream)
...

Step 2: Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Step 3: Avoid duplicate telemetry

Duplicate telemetry is often caused if you create multiple instances of processors or exporters. Make sure that you run only one exporter and processor at a time for each telemetry pillar (logs, metrics, and distributed tracing).

The following sections describe scenarios that can cause duplicate telemetry.

Duplicate trace logs in Azure Functions

If you see a pair of entries for each trace log within Application Insights, you probably enabled the following types of logging instrumentation:

• The native logging instrumentation in Azure Functions
• The azure-monitor-opentelemetry logging instrumentation within the distribution

To prevent duplication, you can disable the distribution's logging, but leave the native logging instrumentation in Azure Functions enabled. To do this, set the OTEL_LOGS_EXPORTER environment variable to None.

Duplicate telemetry in "Always On" Azure Functions

If the Always On setting in Azure Functions is set to On, Azure Functions keeps some processes running in the background after each run is complete. For instance, suppose that you have a five-minute timer function that calls configure_azure_monitor each time. After 20 minutes, you then might have four metric exporters that are running at the same time. This situation might be the source of your duplicate metrics telemetry.

In this situation, either set the Always On setting to Off, or try manually shutting down the providers between each configure_azure_monitor call. To shut down each provider, run shutdown calls for each current meter, tracer, and logger provider, as shown in the following code:

get_meter_provider().shutdown()
get_tracer_provider().shutdown()
get_logger_provider().shutdown()

Azure Workbooks and Jupyter Notebooks

Azure Workbooks and Jupyter Notebooks might keep exporter processes running in the background. To prevent duplicate telemetry, clear the cache before you make more calls to configure_azure_monitor.

Step 4: Make sure that Flask request data is collected

If you implement a Flask application, you might find that you can't collect Requests table data from Application Insights while you use the Azure Monitor OpenTelemetry Distro client library for Python. This issue could occur if you don't structure your import declarations correctly. You might be importing the flask.Flask web application framework before you call the configure_azure_monitor function to instrument the Flask library. For example, the following code doesn't successfully instrument the Flask app:

from azure.monitor.opentelemetry import configure_azure_monitor
from flask import Flask

configure_azure_monitor()

app = Flask(__name__)

Instead, we recommend that you import the flask module as a whole, and then call configure_azure_monitor to configure OpenTelemetry to use Azure Monitor before you access flask.Flask:

from azure.monitor.opentelemetry import configure_azure_monitor
import flask

configure_azure_monitor()

app = flask.Flask(__name__)

Alternatively, you can call configure_azure_monitor before you import flask.Flask:

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from flask import Flask

app = Flask(__name__)

• 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.

• 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.

• 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.

• For Azure support issues, open an Azure support ticket.
• For OpenTelemetry issues, contact the OpenTelemetry community directly.
• For a list of open issues with Spring Boot native applications, see the GitHub Issues Page.
• For a list of open issues with Quarkus native applications, see the GitHub Issues Page.

• 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.

• 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.