Thanks to visit codestin.com
Credit goes to github.com

Skip to content

NETCORE

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

NETCORE

Readme.md

Application Insights for ASP.NET Core

The Microsoft Application Insights for ASP.NET Core SDK 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.

Note: For Worker Services, background services, and console applications, see Worker Service documentation.

NuGet Packages

Getting Started

Prerequisites

  • Azure Subscription: To use Azure services, including Azure Monitor, 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 a 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 Application Insights. 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

The Microsoft.ApplicationInsights.AspNetCore package is built on top of OpenTelemetry and includes:

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.

Metrics

  • Application Insights Standard Metrics: Provides automatic collection of Application Insights Standard metrics.
  • ASP.NET Core and HTTP Client Metrics Instrumentation: Metrics collection is selective based on the .NET runtime version:

Logs

Resource Detectors

  • Azure App Service Resource Detector: Adds resource attributes for applications running in Azure App Service.
  • Azure VM Resource Detector: Adds resource attributes for applications running in an Azure Virtual Machine.
  • ASP.NET Core Environment Resource Detector: Adds resource attributes from the ASP.NET Core environment configuration.

Note: Resource attributes are used to set the cloud role and role instance. Most other resource attributes are currently ignored.

Live Metrics

  • Integrated support for Live Metrics enabling real-time monitoring of application performance.

Azure Monitor Exporter

Migrating from Application Insights SDK 2.x?

If you are currently using the Application Insights SDK 2.x and want to migrate to the OpenTelemetry-based 3.x version, please see the Migration Guidance.

Install the Package

Install the Microsoft.ApplicationInsights.AspNetCore package from NuGet:

dotnet add package Microsoft.ApplicationInsights.AspNetCore

Enabling Application Insights in Your Application

The following examples demonstrate how to integrate Application Insights into your ASP.NET Core application.

Example 1: Using Environment Variable for Connection String

To enable Application Insights, add AddApplicationInsightsTelemetry() to your Program.cs file and set the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable to the connection string from your Application Insights resource.

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights telemetry
builder.Services.AddApplicationInsightsTelemetry();

// Add other services for your application
builder.Services.AddMvc();

var app = builder.Build();

Example 2: Using Connection String in Code

To enable Application Insights with a connection string specified in code, add AddApplicationInsightsTelemetry() with the ApplicationInsightsServiceOptions containing the connection string.

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights telemetry with connection string
builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...";
});

// Add other services for your application
builder.Services.AddMvc();

var app = builder.Build();

Example 3: Using Configuration

To enable Application Insights using configuration from appsettings.json, add AddApplicationInsightsTelemetry() with IConfiguration:

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights telemetry from configuration
builder.Services.AddApplicationInsightsTelemetry(builder.Configuration);

// Add other services for your application
builder.Services.AddMvc();

var app = builder.Build();

In your appsettings.json:

{
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://..."
  }
}

Note: Multiple calls to AddApplicationInsightsTelemetry() will not result in multiple providers. Only a single TracerProvider, MeterProvider, and LoggerProvider will be created.

Configuration

ApplicationInsightsServiceOptions

The following options are available when configuring Application Insights in version 3.x:

builder.Services.AddApplicationInsightsTelemetry(options =>
{
    // Connection string for the Application Insights resource
    options.ConnectionString = "InstrumentationKey=...";
    
    // AAD authentication credential (optional)
    // options.Credential = new DefaultAzureCredential();
    
    // Application version reported with telemetry
    // options.ApplicationVersion = "1.0.0";
    
    // Enable or disable Live Metrics (default: true)
    options.EnableQuickPulseMetricStream = true;
    
    // Rate-limited sampling: maximum traces per second (default: 5)
    // Use this for rate-based sampling to limit telemetry volume
    options.TracesPerSecond = 5.0;
    
    // Percentage-based sampling: ratio of telemetry to collect (0.0 to 1.0)
    // Use this instead of TracesPerSecond for percentage-based sampling
    // options.SamplingRatio = 0.5f;  // 50% of telemetry
    
    // Enable or disable Application Insights Standard Metrics (default: true)
    options.AddAutoCollectedMetricExtractor = true;
    
    // Enable or disable performance counter collection (default: true)
    options.EnablePerformanceCounterCollectionModule = true;
    
    // Enable or disable dependency tracking (default: true)
    // When false, outbound HTTP, SQL, and other dependency calls are not tracked
    options.EnableDependencyTrackingTelemetryModule = true;
    
    // Enable or disable request tracking (default: true) - ASP.NET Core only
    // When false, incoming HTTP requests are not tracked
    options.EnableRequestTrackingTelemetryModule = true;
    
    // Enable JavaScript snippet for authenticated user tracking (default: false)
    options.EnableAuthenticationTrackingJavaScript = false;
    
    // Enable or disable trace-based log sampling (default: true)
    // When true, logs are sampled based on the sampling decision of the associated trace
    options.EnableTraceBasedLogsSampler = true;
});

Advanced Configuration

Using TelemetryClient for Custom Telemetry

You can inject TelemetryClient to send custom telemetry:

public class MyController : Controller
{
    private readonly TelemetryClient _telemetryClient;
    
    public MyController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
    
    public IActionResult Index()
    {
        // Track custom event
        _telemetryClient.TrackEvent("MyCustomEvent");
        
        // Track custom metric
        _telemetryClient.TrackMetric("MyMetric", 42);
        
        // Track custom trace
        _telemetryClient.TrackTrace("My trace message");
        
        return View();
    }
}

Note: In version 3.x, TelemetryClient is a shim layer that translates Application Insights API calls to OpenTelemetry signals. For new code, consider using OpenTelemetry APIs directly.

OpenTelemetry Extensibility

The 3.x SDK is built on OpenTelemetry, allowing you to extend and customize telemetry collection using OpenTelemetry APIs.

Adding Custom ActivitySource to Traces

using System.Diagnostics;

// Create an ActivitySource
private static readonly ActivitySource MyActivitySource = 
    new ActivitySource("MyCompany.MyProduct.MyLibrary");

// Use it to create activities
using var activity = MyActivitySource.StartActivity("OperationName");
activity?.SetTag("key", "value");

// Register it with OpenTelemetry
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
{
    builder.AddSource("MyCompany.MyProduct.MyLibrary");
});

Adding Custom Meter to Metrics

using System.Diagnostics.Metrics;

// Create a Meter and instruments
private static readonly Meter MyMeter = new Meter("MyCompany.MyProduct.MyLibrary");
private static readonly Counter<int> MyCounter = MyMeter.CreateCounter<int>("my_counter");

// Use it to record metrics
MyCounter.Add(1, new KeyValuePair<string, object?>("key", "value"));

// Register it with OpenTelemetry
builder.Services.AddApplicationInsightsTelemetry();
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 by default, you can add additional instrumentation using OpenTelemetry Instrumentation packages. For example, to add instrumentation for gRPC clients:

// Install: dotnet add package OpenTelemetry.Instrumentation.GrpcNetClient

builder.Services.AddApplicationInsightsTelemetry();

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
{
    builder.AddGrpcClientInstrumentation();
});

Customizing ASP.NET Core Instrumentation

using OpenTelemetry.Instrumentation.AspNetCore;

builder.Services.AddApplicationInsightsTelemetry();

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 HTTP Client Instrumentation

using OpenTelemetry.Instrumentation.Http;

builder.Services.AddApplicationInsightsTelemetry();

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 SQL Client Instrumentation

// Install: dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

using OpenTelemetry.Instrumentation.SqlClient;

builder.Services.AddApplicationInsightsTelemetry();

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
{
    builder.AddSqlClientInstrumentation(options =>
    {
        options.RecordException = true;
    });
});

Adding Custom Resource

To modify the resource attributes:

using OpenTelemetry.Resources;

builder.Services.AddApplicationInsightsTelemetry();

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
{
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddService("my-service-name", "my-service-namespace", "1.0.0")
    );
});

You can also configure the Resource using environment 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.

Adding Another Exporter

Application Insights uses the Azure Monitor exporter to send data to Application Insights. However, if you need to send data to other services, you can add another exporter:

// Install: dotnet add package OpenTelemetry.Exporter.Console

builder.Services.AddApplicationInsightsTelemetry();

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
{
    builder.AddConsoleExporter();
});

Dropping Specific Metrics Instruments

To exclude specific instruments from being collected:

using OpenTelemetry.Metrics;

builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) =>
{
    builder.AddView(
        instrumentName: "http.server.active_requests", 
        MetricStreamConfiguration.Drop
    );
});

Refer to Drop an instrument for more examples.

Log Scopes

Log scopes allow you to add additional properties to the logs generated by your application. Although Application Insights supports scopes, this feature is off by default in OpenTelemetry. To leverage log scopes, you must explicitly enable them.

To include scopes with your logs:

using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;

builder.Services.Configure<OpenTelemetryLoggerOptions>(loggingOptions =>
{
    loggingOptions.IncludeScopes = true;
});

When using ILogger scopes, use a List<KeyValuePair<string, object?>> or IReadOnlyList<KeyValuePair<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.");
}

Custom OpenTelemetry Processor Registration

Register any custom processors with:

builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) =>
{
    builder.AddProcessor<MyActivityProcessor>();
});
---