The Azure Monitor Distro is a client library that sends telemetry data to Azure Monitor following the OpenTelemetry Specification. This library can be used to instrument your ASP.NET Core applications to collect and send telemetry data to Azure Monitor for analysis and monitoring, powering experiences in Application Insights.
Getting started
Prerequisites
Azure Subscription: To use Azure services, including Azure Monitor Distro, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a free trial or use your Visual Studio Subscription benefits when you create an account.
Azure Application Insights Connection String: To send telemetry data to the monitoring service you'll need connection string from Azure Application Insights. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for Create an Application Insights resource and copy the connection string.
ASP.NET Core App: An ASP.NET Core application is required to instrument it with Azure Monitor Distro. You can either bring your own app or follow the Get started with ASP.NET Core MVC to create a new one.
What is Included in the Distro
The Azure Monitor Distro is a distribution of the .NET OpenTelemetry SDK with internally vendored instrumentation libraries, including:
Traces
ASP.NET Core Instrumentation: Provides automatic tracing for incoming HTTP requests to ASP.NET Core applications.
HTTP Client Instrumentation: Provides automatic tracing for outgoing HTTP requests made using .
Nightly builds are available from this repo's dev feed.
These are provided without support and are not intended for production workloads.
Enabling Azure Monitor OpenTelemetry in your application
The following examples demonstrate how to integrate the Azure Monitor Distro into your application.
Example 1
To enable Azure Monitor Distro, add UseAzureMonitor() to your Program.cs file and set the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable to the connection string from your Application Insights resource.
// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);
// The following line enables Azure Monitor Distro.
builder.Services.AddOpenTelemetry().UseAzureMonitor();
// This code adds other services for your application.
builder.Services.AddMvc();
var app = builder.Build();
Example 2
To enable Azure Monitor Distro with a hard-coded connection string, add UseAzureMonitor() to your Program.cs with the AzureMonitorOptions containing the connection string.
// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);
// The following line enables Azure Monitor Distro with hard-coded connection string.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000");
// This code adds other services for your application.
builder.Services.AddMvc();
var app = builder.Build();
Note that in the examples above, UseAzureMonitor is added to the IServiceCollection in the Program.cs file. You can also add it in the ConfigureServices method of your Startup.cs file.
Note
Multiple calls to AddOpenTelemetry.UseAzureMonitor() will NOT result in multiple providers. Only a single TracerProvider, MeterProvider and LoggerProvider will be created in the target IServiceCollection. To establish multiple providers use the Sdk.CreateTracerProviderBuilder() and/or Sdk.CreateMeterProviderBuilder() and/or LoggerFactory.CreateLogger methods with the Azure Monitor Exporter instead of using Azure Monitor Distro.
Authenticate the client
Azure Active Directory (AAD) authentication is an optional feature that can be used with Azure Monitor Distro. To enable AAD authentication, set the Credential property in AzureMonitorOptions. This is made easy with the Azure Identity library, which provides support for authenticating Azure SDK clients with their corresponding Azure services.
// Call UseAzureMonitor and set Credential to authenticate through Active Directory.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
o.Credential = new DefaultAzureCredential();
});
With this configuration, the Azure Monitor Distro will use the credentials of the currently logged-in user or of the service principal to authenticate and send telemetry data to Azure Monitor.
Note that the Credential property is optional. If it is not set, Azure Monitor Distro will use the Instrumentation Key from the Connection String to send data to Azure Monitor.
Advanced configuration
Customizing Sampling Percentage
When using the Azure Monitor Distro, the sampling percentage for telemetry data is set to 100% (1.0F) by default. For example, let's say you want to set the sampling percentage to 50%. You can achieve this by modifying the code as follows:
If you need to instrument a library or framework that isn't included in the Azure Monitor Distro, you can add additional instrumentation using the OpenTelemetry Instrumentation packages. For example, to add instrumentation for gRPC clients, you can add the OpenTelemetry.Instrumentation.GrpcNetClient package and use the following code:
Azure Monitor Distro uses the Azure Monitor exporter to send data to Application Insights. However, if you need to send data to other services, including Application Insights, you can add another exporter. For example, to add the Console exporter, you can install the OpenTelemetry.Exporter.Console package and use the following code:
Sets the value of the service.name resource attribute. If service.name is also provided in OTEL_RESOURCE_ATTRIBUTES, then OTEL_SERVICE_NAME takes precedence.
Key concepts
The Azure Monitor Distro is a distribution package that facilitates users in sending telemetry data to Azure Monitor. It encompasses the .NET OpenTelemetry SDK and internally vendored instrumentation libraries for ASP.NET Core, HttpClient, and SQLClient, ensuring seamless integration and data collection.
The Azure Monitor Distro uses EventSource for its own internal logging. The logs are available to any EventListener by opting into the source named "OpenTelemetry-AzureMonitor-Exporter".
OpenTelemetry also provides it's own self-diagnostics feature to collect internal logs.
An example of this is available in our demo project here.
Add AddHttpClientInstrumentation or AddSqlClientInstrumentation to the TracerProvider configuration. Detailed guidance can be found in the OpenTelemetry documentation for HTTP and SQL Client.
Note: If all telemetries are missing or if the above troubleshooting steps do not help, please collect self-diagnostics logs.
Next steps
For more information on Azure SDK, please refer to this website
