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 4.5 or later.
- .NET Core and ASP.NET Core applications running .NET Core 2.1 (LTS) or 3.1 (LTS) on Windows.
- .NET 5.0 applications on Windows.
We don't recommend using .NET Core 2.0, 2.2 or 3.0 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
Client applications (for example, WPF, Windows Forms or UWP) are not supported.
If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.
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.
Owners and contributors do not automatically have this role. If they want to view snapshots, they must add themselves to the role.
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.
- Navigate to the Application Insights resource in the Azure portal.
- Click Access control (IAM).
- Click the +Add role assignment button.
- Select Application Insights Snapshot Debugger from the Roles drop-down list.
- Search for and enter a name for the user to add.
- Click the Save button to add the user to the role.
Please note that snapshots may contain personal data or other sensitive information in variable and parameter values. Snapshot data is stored in the same region as your App Insights resource.
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
Click the Download Snapshot button to download a
.diagsessionfile, which can be opened by Visual Studio Enterprise.
To open the
.diagsessionfile, 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.
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.
- A process snapshot is a suspended clone of the running process.
- Creating the snapshot takes about 10 to 20 milliseconds.
- The default value for
ThresholdForSnapshottingis 1. This is also the minimum value. Therefore, your app has to trigger the same exception twice before a snapshot is created.
IsEnabledInDeveloperModeto true if you want to generate snapshots while debugging in Visual Studio.
- The snapshot creation rate is limited by the
SnapshotsPerTenMinutesLimitsetting. By default, the limit is one snapshot every ten minutes.
- No more than 50 snapshots per day may be uploaded.
The default data retention period is 15 days. For each Application Insights instance, a maximum number of 50 snapshots are allowed per day.
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:
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.
For more information on the different symbol options that are available, see the Visual Studio documentation. For best results, we recommend using "Full", "Portable" or "Embedded".
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.
Install the Application Insights Site Extension in your App Service to get deoptimization support.
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: