👁 Image
Azure.Monitor.OpenTelemetry.Exporter 1.8.1

Azure Monitor Exporter client library for .NET

The OpenTelemetry .NET exporters which send telemetry data to Azure Monitor following the OpenTelemetry Specification.

Getting started

Prerequisites

• Azure Subscription: To use Azure services, including Azure Monitor Exporter for OpenTelemetry .NET, 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.

Migrating from Application Insights SDK

If you are currently using the Application Insights SDK and want to migrate to OpenTelemetry, please follow our migration guide.

Already using OpenTelemetry?

If you are currently using OpenTelemetry and want to send telemetry data to Azure Monitor, please follow our getting started guide.

Install the package

Latest Version: 👁 Nuget

Install the Azure Monitor Exporter for OpenTelemetry .NET with NuGet:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Nightly builds

Nightly builds are available from this repo's dev feed. These are provided without support and are not intended for production workloads.

Add the Exporter (per signal)

The following examples demonstrate how to add the AzureMonitorExporter to your OpenTelemetry configuration.

It's important to keep the TracerProvider, MeterProvider, and LoggerFactory instances active throughout the process lifetime. These must be properly disposed when your application is shutting down to flush any remaining telemetry items.

• Traces

  var tracerProvider = Sdk.CreateTracerProviderBuilder()
   .AddAzureMonitorTraceExporter(options => options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
   .Build();
  

  For a complete example see TraceDemo.cs.

• Metrics

  var meterProvider = Sdk.CreateMeterProviderBuilder()
   .AddAzureMonitorMetricExporter(options => options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
   .Build();
  

  For a complete example see MetricDemo.cs.

• Logs

  var loggerFactory = LoggerFactory.Create(builder =>
  {
   builder.AddOpenTelemetry(logging =>
   {
   logging.AddAzureMonitorLogExporter(options => options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000");
   });
  });
  

  For a complete example see LogDemo.cs.

Add the Exporter for all signals

Starting with the 1.4.0-beta.3 version you can use the cross-cutting UseAzureMonitorExporter extension to simplify registration of the OTLP exporter for all signals (traces, metrics, and logs).

The following example demonstrates how to add the AzureMonitorExporter to your OpenTelemetry configuration by using a single API. To use this API, you need to add OpenTelemetry to a ServiceCollection. This approach will also enable LiveMetrics. LiveMetrics can be disabled by setting options.EnableLiveMetrics = false.

appBuilder.Services.AddOpenTelemetry()
 .UseAzureMonitorExporter(options => {
 options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
 });

Authenticate the client

Azure Active Directory (AAD) authentication is an optional feature that can be used with the Azure Monitor Exporter. This is made easy with the Azure Identity library, which provides support for authenticating Azure SDK clients with their corresponding Azure services.

There are two options to enable AAD authentication. Note that if both have been set AzureMonitorExporterOptions will take precedence.

1. Set your Credential to the AzureMonitorExporterOptions.

   var credential = new DefaultAzureCredential();
   
   var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options =>
    {
    options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    options.Credential = credential;
    })
    .Build();
   

2. Provide your Credential to the AddAzureMonitorExporter method.

   var credential = new DefaultAzureCredential();
   
   var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000", credential)
    .Build();
   

Key concepts

Some key concepts for .NET include:

• Overview of .NET distributed tracing: Distributed tracing is a diagnostic technique that helps engineers localize failures and performance issues within applications, especially those that may be distributed across multiple machines or processes.

• Overview of Logging in .NET: .NET supports a logging API that works with a variety of built-in and third-party logging providers.

Some key concepts for Azure Monitor include:

• IP Addresses used by Azure Monitor: This exporter sends traces to the configured Azure Monitor Resource using HTTPS. You might need to know IP addresses if the app or infrastructure that you're monitoring is hosted behind a firewall.

Some key concepts for OpenTelemetry include:

• OpenTelemetry: OpenTelemetry is a set of libraries used to collect and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.

• Instrumentation: The ability to call the OpenTelemetry API directly by any application is facilitated by instrumentation. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.

• Tracing Signal: Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.

• Sampling: Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend. Default Sampling: By default, the Azure Monitor Exporter uses RateLimitedSampler with a rate of 5.0 traces per second. This provides cost-effective telemetry collection for most applications. To change the sampling behavior:

  • For rate-limited sampling: Set TracesPerSecond in AzureMonitorExporterOptions:

    .AddAzureMonitorTraceExporter(options => {
     options.TracesPerSecond = 10.0; // Sample 10 traces per second
    })
    

  • For percentage-based sampling: Set SamplingRatio and clear TracesPerSecond:

    .AddAzureMonitorTraceExporter(options => {
     options.SamplingRatio = 0.5f; // Sample 50% of traces
     options.TracesPerSecond = null;
    })
    

  • Via environment variables:

    OTEL_TRACES_SAMPLER=microsoft.rate_limited
    OTEL_TRACES_SAMPLER_ARG=10
    

    or

    OTEL_TRACES_SAMPLER=microsoft.fixed_percentage
    OTEL_TRACES_SAMPLER_ARG=0.5
    

• Metric Signal: OpenTelemetry allows to record raw measurements or metrics with predefined aggregation and a set of attributes (dimensions).

• Log Signal: A recording of an event. Typically the record includes a timestamp indicating when the event happened as well as other data that describes what happened, where it happened, etc.

For more information on the OpenTelemetry project, please review the OpenTelemetry Specifications.

Examples

Refer to Program.cs for a complete demo.

Log Scopes

Log scopes allow you to add additional properties to the logs generated by your application. Although the Azure Monitor Exporter does support scopes, this feature is off by default in OpenTelemetry. To leverage log scopes, you must explicitly enable them.

To include the scope with your logs, set OpenTelemetryLoggerOptions.IncludeScopes to true in your application's configuration:

var loggerFactory = LoggerFactory.Create(builder =>
{
 builder.AddOpenTelemetry(logging =>
 {
 logging.AddAzureMonitorLogExporter(options => options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000");
 logging.IncludeScopes = true;
 });
});

When using ILogger scopes, use a List<KeyValuePair<string, object?>> or IReadOnlyList<KeyValue<string, object?>> as the state for best performance. All logs written within the context of the scope will include the specified information. Azure Monitor will add these scope values to the Log's CustomProperties.

List<KeyValuePair<string, object?>> scope =
[
 new("scopeKey", "scopeValue")
];

using (logger.BeginScope(scope))
{
 logger.LogInformation("Example message.");
}

In scenarios involving multiple scopes or a single scope with multiple key-value pairs, if duplicate keys are present, only the first occurrence of the key-value pair from the outermost scope will be recorded. However, when the same key is utilized both within a logging scope and directly in the log statement, the value specified in the log message template will take precedence.

CustomEvents

Azure Monitor relies on OpenTelemetry's Log Signal to create CustomEvents. For .NET, users will use ILogger and place an attribute named "microsoft.custom_event.name" in the message template. Severity and CategoryName are not recorded in the CustomEvent.

via ILogger.Log methods

To send a CustomEvent via ILogger, include the "microsoft.custom_event.name" attribute in the message template.

Note: This example shows LogInformation, but any Log method can be used. Severity is not recorded, but depending on your configuration it may be filtered out. Users should take care to select a severity for CustomEvents that is not filtered out by their configuration.

var loggerFactory = LoggerFactory.Create(builder =>
{
 builder.AddOpenTelemetry(logging =>
 {
 logging.AddAzureMonitorLogExporter();
 });
});

var logger = loggerFactory.CreateLogger(logCategoryName);
logger.LogInformation("{microsoft.custom_event.name} {key1} {key2}", "MyCustomEventName", "value1", "value2");

This example generates a CustomEvent structured like this:

{
 "name": "Event",
 "data": {
 "baseType": "EventData",
 "baseData": {
 "name": "MyCustomEventName",
 "properties": {
 "key1": "value1",
 "key2": "value2"
 }
 }
 }
}

Troubleshooting

The Azure Monitor exporter uses EventSource for its own internal logging. The exporter 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.

Next steps

For more information on Azure SDK, please refer to this website

Contributing

See CONTRIBUTING.md for details on contribution process.

AOT (Ahead-of-Time) Support

This library supports usage in .NET applications compiled with AOT (Ahead-of-Time) compilation. All core features of the Azure Monitor Exporter are compatible with AOT, including telemetry export for traces, metrics, and logs.

Important:
While AOT is supported, automatic configuration binding from appsettings.json or other IConfiguration sources is not supported in AOT-compiled applications. This is due to .NET limitations on reflection-based binding APIs (such as ConfigurationBinder.Bind and Get<T>()) in AOT scenarios.

Workaround:
In AOT scenarios, you can configure the Azure Monitor Exporter using one of the following approaches:

• Environment Variable: Set the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable to configure the connection string.

• Programmatic Configuration: Set the AzureMonitorExporterOptions directly in your application code:

  builder.Services.AddOpenTelemetry()
   .UseAzureMonitorExporter(options =>
   {
   options.ConnectionString = "<your-connection-string>";
   // Set other options as needed
   });