Debug snapshots on exceptions in .NET apps

When an exception occurs, you can automatically collect a debug snapshot from your live web application. The snapshot shows the state of source code and variables at the moment the exception was thrown. The Snapshot Debugger in Azure Application Insights monitors exception telemetry from your web app. It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. Include the Snapshot collector NuGet package in your application, and optionally configure collection parameters in ApplicationInsights.config. Snapshots appear on exceptions in the Application Insights portal.

You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

Debug snapshots are stored for 15 days. This retention policy is set on a per-application basis. If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Enable Application Insights Snapshot Debugger for your application

Snapshot collection is available for:

• .NET Framework and ASP.NET applications running .NET Framework LTS or later.
• .NET Core and ASP.NET Core applications running .NET Core LTS on Windows.
• .NET LTS applications on Windows.

We don't recommend using .NET Core versions prior to LTS since they're out of support.

The following environments are supported:

• Azure App Service
• Azure Function
• Azure Cloud Services running OS family 4 or later
• Azure Service Fabric services running on Windows Server 2012 R2 or later
• Azure Virtual Machines and virtual machine scale sets running Windows Server 2012 R2 or later
• On-premises virtual or physical machines running Windows Server 2012 R2 or later or Windows 8.1 or later

If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

Grant permissions

Access to snapshots is protected by Azure role-based access control (Azure RBAC). To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. This role can be assigned to individual users or groups by subscription owners for the target Application Insights resource or its resource group or subscription.

1. Assign the Debugger role to the Application Insights Snapshot.

   For detailed steps, see Assign Azure roles using the Azure portal.

View Snapshots in the Portal

After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. To view snapshots, in the Failure pane, select the Operations button when viewing the Operations tab, or select the Exceptions button when viewing the Exceptions tab:

Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

In the Debug Snapshot view, you see a call stack and a variables pane. When you select frames of the call stack in the call stack pane, you can view local variables and parameters for that function call in the variables pane.

Snapshots might include sensitive information, and by default they aren't viewable. To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

View Snapshots in Visual Studio 2017 Enterprise or above

1. Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

2. To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. The Snapshot Debugger component is a required component of the ASP.NET workload in Visual Studio and can be selected from the Individual Component list in the Visual Studio installer. If you're using a version of Visual Studio before Visual Studio 2017 version 15.5, you'll need to install the extension from the Visual Studio Marketplace.

3. After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Click Debug Managed Code to start debugging the snapshot. The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

   

The downloaded snapshot includes any symbol files that were found on your web application server. These symbol files are required to associate snapshot data with source code. For App Service apps, make sure to enable symbol deployment when you publish your web apps.

How snapshots work

The Snapshot Collector is implemented as an Application Insights Telemetry Processor. When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. If there's a match, then a snapshot of the running process is created. The snapshot is assigned a unique identifier and the exception is stamped with that identifier. After the FirstChanceException handler returns, the thrown exception is processed as normal. Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

The main process continues to run and serve traffic to users with little interruption. Meanwhile, the snapshot is handed off to the Snapshot Uploader process. The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

Limitations

The default data retention period is 15 days. For each Application Insights instance, a maximum number of 50 snapshots are allowed per day.

Publish symbols

The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. In prior versions, you need to add the following line to your publish profile .pubxml file so that symbols are published in release mode:

    <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

For Azure Compute and other types, make sure that the symbol files are in the same folder of the main application .dll (typically, wwwroot/bin) or are available on the current path.

Optimized builds

In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Next steps

Enable Application Insights Snapshot Debugger for your application:

• Azure App Service
• Azure Function
• Azure Cloud Services
• Azure Service Fabric services
• Azure Virtual Machines and virtual machine scale sets
• On-premises virtual or physical machines

Beyond Application Insights Snapshot Debugger:

• Set snappoints in your code to get snapshots without waiting for an exception.
• Diagnose exceptions in your web apps explains how to make more exceptions visible to Application Insights.
• Smart Detection automatically discovers performance anomalies.