Application Insights .NET SDK Documentation

The Microsoft.ApplicationInsights.AspNetCore package is built on OpenTelemetry and provides the following automatic instrumentation:

Traces

• ASP.NET Core Instrumentation: Automatic tracing for incoming HTTP requests.
• HTTP Client Instrumentation: Automatic tracing for outgoing System.Net.Http.HttpClient requests.
• SQL Client Instrumentation: Automatic tracing for Microsoft.Data.SqlClient and System.Data.SqlClient queries.

Metrics

• Application Insights Standard Metrics: Automatic collection of standard metrics.
• Runtime-specific Metrics:
  • .NET 8.0+: Uses built-in Microsoft.AspNetCore.Hosting and System.Net.Http metrics.
  • .NET 7.0 and below: Uses OpenTelemetry instrumentation for ASP.NET Core and HTTP Client.

Logs

• Automatically collects logs created via Microsoft.Extensions.Logging.

Resource Detectors

• Azure App Service Resource Detector: Adds attributes for Azure App Service.
• Azure VM Resource Detector: Adds attributes for Azure Virtual Machines.
• ASP.NET Core Environment Resource Detector: Adds attributes from the ASP.NET Core environment configuration.

Other Features

• Live Metrics: Integrated support for real-time monitoring.
• Azure Monitor Exporter: Uses Azure.Monitor.OpenTelemetry.Exporter to send data to Azure Monitor.

To log custom telemetry, use the TelemetryClient API.

CRITICAL: Single Instance Pattern Required In version 3.x, you must create a TelemetryConfiguration using TelemetryConfiguration.CreateDefault() (which loads from ApplicationInsights.config), then pass it to the TelemetryClient constructor.

You must create exactly ONE TelemetryClient instance at application startup and reuse it throughout the application's lifetime.

Creating multiple instances causes:

• Memory leaks: Internal buffers and timers are never released.
• Performance degradation: Each instance spawns background threads for batching.
• Duplicate telemetry: Multiple instances may send the same data.
• Configuration inconsistencies.

// Recommended initialization in Global.asax.cs
protected void Application_Start()
{
    var configuration = TelemetryConfiguration.CreateDefault();
    TelemetryClient = new TelemetryClient(configuration);
}

Activities automatically form a parent-child hierarchy based on the execution flow. When an activity is started within the scope of another, it becomes a child, linked via TraceId and ParentId. This creates a trace tree in Application Insights, allowing you to visualize the flow of a single operation through multiple sub-tasks and external calls.

public async Task ProcessOrderAsync(string orderId)
{
    using var orderActivity = MyAppTracing.Source.StartActivity("ProcessOrder", ActivityKind.Internal);
    orderActivity?.SetTag("order.id", orderId);

    // This activity becomes a child of ProcessOrder
    await ValidateOrderAsync(orderId);

    // This activity also becomes a child of ProcessOrder
    await ChargePaymentAsync(orderId);

    orderActivity?.SetStatus(ActivityStatusCode.Ok);
}

private async Task ValidateOrderAsync(string orderId)
{
    using var activity = MyAppTracing.Source.StartActivity("ValidateOrder", ActivityKind.Internal);
    // ... validation logic ...
    activity?.SetStatus(ActivityStatusCode.Ok);
}

private async Task ChargePaymentAsync(string orderId)
{
    using var activity = MyAppTracing.Source.StartActivity("ChargePayment", ActivityKind.Client);
    activity?.SetTag("payment.provider", "stripe");
    // ... payment call ...
    activity?.SetStatus(ActivityStatusCode.Ok);
}

In 3.x, Application Insights uses OpenTelemetry internally. All metric identifiers must follow the OpenTelemetry Instrument Name Syntax.

Requirements:

• Must not be null or empty.
• Must be case-insensitive, ASCII strings.
• The first character must be an alphabetic character (A-Z or a-z).
• Subsequent characters must be alphanumeric (A-Z, a-z, 0-9), _, ., -, or /.
• Maximum length of 255 characters.

Affected Methods:

• TrackMetric(string name, double value, ...): The name parameter.
• GetMetric(string metricId, ...): The metricId parameter.
• MetricIdentifier(string metricNamespace, string metricId, ...): Both metricNamespace and metricId parameters.

Note: If your existing metric names contain characters like spaces, $, or #, you must rename them before migrating to 3.x.