Azure.Monitor.OpenTelemetry.AspNetCore
1.2.0
Prefix Reserved
See the version list below for details.
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore --version 1.2.0
NuGet\Install-Package Azure.Monitor.OpenTelemetry.AspNetCore -Version 1.2.0
<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" Version="1.2.0" />
paket add Azure.Monitor.OpenTelemetry.AspNetCore --version 1.2.0
#r "nuget: Azure.Monitor.OpenTelemetry.AspNetCore, 1.2.0"
// Install Azure.Monitor.OpenTelemetry.AspNetCore as a Cake Addin #addin nuget:?package=Azure.Monitor.OpenTelemetry.AspNetCore&version=1.2.0 // Install Azure.Monitor.OpenTelemetry.AspNetCore as a Cake Tool #tool nuget:?package=Azure.Monitor.OpenTelemetry.AspNetCore&version=1.2.0
Azure Monitor Distro client library for .NET
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 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 System.Net.Http.HttpClient.
- SQL Client Instrumentation Provides automatic tracing for SQL queries executed using the Microsoft.Data.SqlClient and System.Data.SqlClient packages. (While the OpenTelemetry SqlClient instrumentation remains in its beta phase, we have taken the step to vendor it and include it in our Distro)
Metrics
- Application Insights Standard Metrics: Provides automatic collection of Application Insights Standard metrics.
- ASP.NET Core and HTTP Client Metrics Instrumentation: Our distro will selectively enable metrics collection based on the .NET runtime version.
- .NET 8.0 and above: Utilizes built-in Metrics
Microsoft.AspNetCore.Hosting
andSystem.Net.Http
from .NET. For a detailed list of metrics produced, refer to the Microsoft.AspNetCore.Hosting and System.Net.Http metrics documentation. - .NET 7.0 and below: Falls back to ASP.NET Core Instrumentation and HTTP Client Instrumentation. For a detailed list of metrics produced, refer to the ASP.NET Core Instrumentation and HTTP Client Instrumentation documentation.
- .NET 8.0 and above: Utilizes built-in Metrics
-
- Logs created with
Microsoft.Extensions.Logging
. See Logging in .NET Core and ASP.NET Core for more details on how to create and configure logging. - Azure SDK logs are recorded as a subset of
Microsoft.Extensions.Logging
- Logs created with
Resource Detectors
- AppServiceResourceDetector: Adds resource attributes for the applications running in Azure App Service.
- AzureVMResourceDetector: Adds resource attributes for the applications running in an Azure Virtual Machine.
- AzureContainerAppsResourceDetector: Adds resource attributes for the applications running in Azure Container Apps.
Note: The detectors are part of the OpenTelemetry.ResourceDetectors.Azure package. While this package is currently in its beta phase, we have chosen to vendor in the code for these detectors to include them in our Distro. Please be aware that resource attributes are only used to set the cloud role and role instance. All other resource attributes are ignored.
-
- Integrated support for live metrics enabling real-time monitoring of application performance.
Azure Monitor Exporter allows sending traces, metrics, and logs data to Azure Monitor.
Install the package
Latest Version:
Install the Azure Monitor Distro for .NET from NuGet:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Nightly builds
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 singleTracerProvider
,MeterProvider
andLoggerProvider
will be created in the targetIServiceCollection
. To establish multiple providers use theSdk.CreateTracerProviderBuilder()
and/orSdk.CreateMeterProviderBuilder()
and/orLoggerFactory.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:
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
o.SamplingRatio = 0.5F;
});
Adding Custom ActivitySource to Traces
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("MyCompany.MyProduct.MyLibrary"));
Adding Custom Meter to Metrics
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("MyCompany.MyProduct.MyLibrary"));
Adding Additional Instrumentation
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:
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddGrpcClientInstrumentation());
Enable Azure SDK Instrumentation
Azure SDK instrumentation is supported under the experimental feature flag which can be enabled using one of the following ways:
Set the
AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE
environment variable totrue
.Set the Azure.Experimental.EnableActivitySource context switch to true in your app’s code:
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
Add the RuntimeHostConfigurationOption setting to your project file:
<ItemGroup> <RuntimeHostConfigurationOption Include="Azure.Experimental.EnableActivitySource" Value="true" /> </ItemGroup>
Adding Another Exporter
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:
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddConsoleExporter());
Adding Custom Resource
To modify the resource, use the following code.
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.ConfigureResource(resourceBuilder => resourceBuilder.AddService("service-name")));
It is also possible to configure the Resource
by using following
environmental variables:
Environment variable | Description |
---|---|
OTEL_RESOURCE_ATTRIBUTES |
Key-value pairs to be used as resource attributes. See the Resource SDK specification for more details. |
OTEL_SERVICE_NAME |
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. |
Customizing Instrumentation Libraries
The Azure Monitor Distro includes .NET OpenTelemetry instrumentation for ASP.NET Core, HttpClient, and SQLClient. You can customize these included instrumentations or manually add additional instrumentation on your own using the OpenTelemetry API.
Here are some examples of how to customize the instrumentation:
Customizing AspNetCoreTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>
{
options.RecordException = true;
options.Filter = (httpContext) =>
{
// only collect telemetry about HTTP GET requests
return HttpMethods.IsGet(httpContext.Request.Method);
};
});
Customizing HttpClientTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<HttpClientTraceInstrumentationOptions>(options =>
{
options.RecordException = true;
options.FilterHttpRequestMessage = (httpRequestMessage) =>
{
// only collect telemetry about HTTP GET requests
return HttpMethods.IsGet(httpRequestMessage.Method.Method);
};
});
Customizing SqlClientInstrumentationOptions
While the SQLClient instrumentation is still in beta, we have vendored it within our package. Once it reaches a stable release, it will be included as a standard package reference. Until then, for customization of the SQLClient instrumentation, manually add the OpenTelemetry.Instrumentation.SqlClient package reference to your project and utilize its public API.
dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient
builder.Services.AddOpenTelemetry().UseAzureMonitor().WithTracing(builder =>
{
builder.AddSqlClientInstrumentation(options =>
{
options.SetDbStatementForStoredProcedure = false;
});
});
Disable Live Metrics
By default, the Live Metrics feature is enabled in the Azure Monitor Distro. This feature allows for real-time monitoring of application performance, providing immediate insights into your application's operations. However, there may be scenarios where you prefer to disable this feature, such as to optimize resource usage or in environments where real-time monitoring is not a requirement.
To disable Live Metrics, you can set the EnableLiveMetrics
property to false
in the AzureMonitorOptions
. Here's an example of how to disable Live Metrics:
// Disable Live Metrics by setting EnableLiveMetrics to false in the UseAzureMonitor configuration.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
o.EnableLiveMetrics = false;
});
Drop a Metrics Instrument
The Azure Monitor Distro enables metric collection and collects several metrics by default. If you want to exclude specific instruments from being collected in your application's telemetry use the following code snippet:
builder.Services.ConfigureOpenTelemetryMeterProvider(metrics =>
metrics.AddView(instrumentName: "http.server.active_requests", MetricStreamConfiguration.Drop)
);
Refer to Drop an instrument for more examples.
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 instrumentation libraries for ASP.NET Core, HttpClient, and SQLClient, ensuring seamless integration and data collection.
Examples
Refer to Program.cs
for a complete demo.
Troubleshooting
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.
Missing Request Telemetry
If an app has a reference to the OpenTelemetry.Instrumentation.AspNetCore package, it could be missing request telemetry. To resolve this issue:
- Either remove the reference to the
OpenTelemetry.Instrumentation.AspNetCore
package (or) - Add
AddAspNetCoreInstrumentation
to the OpenTelemetry TracerProvider configuration as per the OpenTelemetry documentation.
Few or all Dependency Telemetries are missing
If an app references the OpenTelemetry.Instrumentation.Http or OpenTelemetry.Instrumentation.SqlClient packages, it might be missing dependency telemetry. To resolve:
- Remove the respective package references (or)
- Add
AddHttpClientInstrumentation
orAddSqlClientInstrumentation
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
Contributing
See CONTRIBUTING.md for details on contribution process.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Core (>= 1.40.0)
- Azure.Monitor.OpenTelemetry.Exporter (>= 1.3.0)
- OpenTelemetry.Extensions.Hosting (>= 1.8.1)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.8.1)
- OpenTelemetry.Instrumentation.Http (>= 1.8.1)
-
net6.0
- Azure.Core (>= 1.40.0)
- Azure.Monitor.OpenTelemetry.Exporter (>= 1.3.0)
- OpenTelemetry.Extensions.Hosting (>= 1.8.1)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.8.1)
- OpenTelemetry.Instrumentation.Http (>= 1.8.1)
NuGet packages (15)
Showing the top 5 NuGet packages that depend on Azure.Monitor.OpenTelemetry.AspNetCore:
Package | Downloads |
---|---|
OakPeak.Core
Provides a default set of APIs for building Brighten .NET Core microservices and web server applications |
|
Wemogy.AspNet
ASP.NET Helpers |
|
Hexalith.Infrastructure.AspireService.Defaults
Hexalith is a set of libraries to build a micro-service architecture. |
|
DotNetBrightener.Core.Logging.OpenTelemetryEnabled.ApplicationInsights
Package Description |
|
Storm.Infrastructure.Loggings.OpenTelemetry
Storm supports OpenTelemetry. |
GitHub repositories (10)
Showing the top 5 popular GitHub repositories that depend on Azure.Monitor.OpenTelemetry.AspNetCore:
Repository | Stars |
---|---|
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
|
|
Azure/azure-functions-host
The host/runtime that powers Azure Functions
|
|
collinbarrett/FilterLists
:shield: The independent, comprehensive directory of filter and host lists for advertisements, trackers, malware, and annoyances.
|
|
GZTimeWalker/GZCTF
The GZ::CTF project, an open source CTF platform.
|
|
Azure/apiops
APIOps applies the concepts of GitOps and DevOps to API deployment. By using practices from these two methodologies, APIOps can enable everyone involved in the lifecycle of API design, development, and deployment with self-service and automated tools to ensure the quality of the specifications and APIs that they’re building.
|
Version | Downloads | Last updated |
---|---|---|
1.3.0-beta.2 | 14,776 | 10/15/2024 |
1.3.0-beta.1 | 42,260 | 7/16/2024 |
1.2.0 | 1,658,657 | 6/11/2024 |
1.2.0-beta.4 | 36,745 | 5/20/2024 |
1.2.0-beta.3 | 28,380 | 4/19/2024 |
1.2.0-beta.2 | 53,487 | 3/13/2024 |
1.2.0-beta.1 | 14,232 | 2/10/2024 |
1.1.1 | 334,092 | 4/26/2024 |
1.1.0 | 884,173 | 1/29/2024 |
1.0.0 | 325,362 | 11/29/2023 |
1.0.0-beta.8 | 188,529 | 10/6/2023 |
1.0.0-beta.7 | 38,914 | 9/20/2023 |
1.0.0-beta.6 | 72,622 | 8/9/2023 |
1.0.0-beta.5 | 25,462 | 7/14/2023 |
1.0.0-beta.4 | 111,049 | 5/10/2023 |
1.0.0-beta.3 | 11,937 | 4/11/2023 |
1.0.0-beta.2 | 1,382 | 3/14/2023 |
1.0.0-beta.1 | 198 | 3/7/2023 |