Edit

Share via

Enable Snapshot Debugger for .NET apps in Azure Service Fabric, Cloud Services, and Virtual Machines

  • Article

If your ASP.NET or ASP.NET Core application runs in Azure App Service and requires a customized Snapshot Debugger configuration, or a preview version of .NET Core, start with Enable Snapshot Debugger for .NET apps in Azure App Service.

If your application runs in Azure Service Fabric, Azure Cloud Services, Azure Virtual Machines, or on-premises machines, you can skip enabling Snapshot Debugger on App Service and follow the guidance in this article.

Prerequisites

Configure snapshot collection for ASP.NET applications

When you add the Microsoft.ApplicationInsights.SnapshotCollector NuGet package to your application, the SnapshotCollectorTelemetryProcessor is added automatically to the TelemetryProcessors section of ApplicationInsights.config.

If you don't see SnapshotCollectorTelemetryProcessor in ApplicationInsights.config, or if you want to customize the Snapshot Debugger configuration, you can edit it manually.

Note

Any manual configurations may get overwritten when upgrading to a newer version of the Microsoft.ApplicationInsights.SnapshotCollector NuGet package.

Snapshot Collector's default configuration looks similar to the following example:

<TelemetryProcessors>
  <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
    <!-- Snapshot Debugging is usually disabled in developer mode, but you can enable it by setting this to true. -->
    <!-- DeveloperMode is a property on the active TelemetryChannel. -->
    <IsEnabledInDeveloperMode>false</IsEnabledInDeveloperMode>
    <!-- How many times we need to see an exception before we ask for snapshots. -->
    <ThresholdForSnapshotting>1</ThresholdForSnapshotting>
    <!-- The maximum number of examples we create for a single problem. -->
    <MaximumSnapshotsRequired>3</MaximumSnapshotsRequired>
    <!-- The maximum number of problems that we can be tracking at any time. -->
    <MaximumCollectionPlanSize>50</MaximumCollectionPlanSize>
    <!-- How often we reconnect to the stamp. The default value is 15 minutes.-->
    <ReconnectInterval>00:15:00</ReconnectInterval>
    <!-- How often to reset problem counters. -->
    <ProblemCounterResetInterval>1.00:00:00</ProblemCounterResetInterval>
    <!-- The maximum number of snapshots allowed in ten minutes.The default value is 1. -->
    <SnapshotsPerTenMinutesLimit>3</SnapshotsPerTenMinutesLimit>
    <!-- The maximum number of snapshots allowed per day. -->
    <SnapshotsPerDayLimit>30</SnapshotsPerDayLimit>
    <!-- Whether or not to collect snapshot in low IO priority thread. The default value is true. -->
    <SnapshotInLowPriorityThread>true</SnapshotInLowPriorityThread>
    <!-- Agree to send anonymous data to Microsoft to make this product better. -->
    <ProvideAnonymousTelemetry>true</ProvideAnonymousTelemetry>
    <!-- The limit on the number of failed requests to request snapshots before the telemetry processor is disabled. -->
    <FailedRequestLimit>3</FailedRequestLimit>
  </Add>
</TelemetryProcessors>

Snapshots are collected only on exceptions reported to Application Insights. In some cases (like on older versions of the .NET platform), you might need to configure exception collection to see exceptions with snapshots in the portal.

Configure snapshot collection for ASP.NET Core applications or Worker Services

Prerequisites

Your application should already reference one of the following Application Insights NuGet packages:

Add the NuGet package

Add the Microsoft.ApplicationInsights.SnapshotCollector NuGet package to your app.

Update the services collection

In your application's startup code, where services are configured, add a call to the AddSnapshotCollector extension method. We suggest adding this line immediately after the call to AddApplicationInsightsTelemetry. For example:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddSnapshotCollector();

Customize the Snapshot Collector

For most scenarios, Snapshot Collector's default settings are sufficient. However, you can customize the settings by adding the following code before the call to AddSnapshotCollector():

using Microsoft.ApplicationInsights.SnapshotCollector;
...
builder.Services.Configure<SnapshotCollectorConfiguration>(builder.Configuration.GetSection("SnapshotCollector"));

Next, add a SnapshotCollector section to appsettings.json where you can override the defaults.

Snapshot Collector's default appsettings.json configuration looks similar to the following example:

{
  "SnapshotCollector": {
    "IsEnabledInDeveloperMode": false,
    "ThresholdForSnapshotting": 1,
    "MaximumSnapshotsRequired": 3,
    "MaximumCollectionPlanSize": 50,
    "ReconnectInterval": "00:15:00",
    "ProblemCounterResetInterval":"1.00:00:00",
    "SnapshotsPerTenMinutesLimit": 1,
    "SnapshotsPerDayLimit": 30,
    "SnapshotInLowPriorityThread": true,
    "ProvideAnonymousTelemetry": true,
    "FailedRequestLimit": 3
  }
}

If you need to customize the Snapshot Collector's behavior manually, without using appsettings.json, use the overload of AddSnapshotCollector that takes a delegate. For example:

builder.Services.AddSnapshotCollector(config => config.IsEnabledInDeveloperMode = true);

Configure snapshot collection for other .NET applications

Snapshots are collected only on exceptions that are reported to Application Insights.

For ASP.NET and ASP.NET Core applications, the Application Insights SDK automatically reports unhandled exceptions that escape a controller method or endpoint route handler.

For other applications, you might need to modify your code to report them. The exception handling code depends on the structure of your application. For example:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

internal class ExampleService
{
  private readonly TelemetryClient _telemetryClient;

  public ExampleService(TelemetryClient telemetryClient)
  {
    // Obtain the TelemetryClient via dependency injection.
    _telemetryClient = telemetryClient;
  }

  public void HandleExampleRequest()
  {
    using IOperationHolder<RequestTelemetry> operation = 
        _telemetryClient.StartOperation<RequestTelemetry>("Example");
    try
    {
      // TODO: Handle the request.
      operation.Telemetry.Success = true;
    }
    catch (Exception ex)
    {
      // Report the exception to Application Insights.
      operation.Telemetry.Success = false;
      _telemetryClient.TrackException(ex);
      // TODO: Rethrow the exception if desired.
    }
  }
}

The following example uses ILogger instead of TelemetryClient. This example assumes you're using the Application Insights Logger Provider. As the example shows, when handling an exception, be sure to pass the exception as the first parameter to LogError.

using Microsoft.Extensions.Logging;

internal class LoggerExample
{
  private readonly ILogger _logger;

  public LoggerExample(ILogger<LoggerExample> logger)
  {
    _logger = logger;
  }

  public void HandleExampleRequest()
  {
    using IDisposable scope = _logger.BeginScope("Example");
    try
    {
      // TODO: Handle the request
    }
    catch (Exception ex)
    {
      // Use the LogError overload with an Exception as the first parameter.
      _logger.LogError(ex, "An error occurred.");
    }
  }
}

By default, the Application Insights Logger (ApplicationInsightsLoggerProvider) forwards exceptions to the Snapshot Debugger via TelemetryClient.TrackException. This behavior is controlled via the TrackExceptionsAsExceptionTelemetry property on the ApplicationInsightsLoggerOptions class.

If you set TrackExceptionsAsExceptionTelemetry to false when configuring the Application Insights Logger, the preceding example will not trigger the Snapshot Debugger. In this case, modify your code to call TrackException manually.

Note

On March 31, 2025, support for instrumentation key ingestion will end. Instrumentation key ingestion will continue to work, but we'll no longer provide updates or support for the feature. Transition to connection strings to take advantage of new capabilities.

Next steps