Debug exceptions in .NET applications using Snapshot Debugger
When enabled, Snapshot Debugger automatically collects a debug snapshot of the source code and variables when an exception occurs in your live .NET application. The Snapshot Debugger in Application Insights:
- Monitors system-generated logs from your web app.
- Collects snapshots on your top-throwing exceptions.
- Provides information you need to diagnose issues in production.
Learn more about the Snapshot Debugger and Snapshot Uploader processes.
Supported applications and environments
This section lists the applications and environments that are supported.
Applications
Snapshot collection is available for:
- .NET Framework 4.6.2 and newer versions.
- .NET 6.0 or later on Windows.
Environments
The following environments are supported:
- Azure App Service
- Azure Functions
- Azure Cloud Services running OS family 4 or later
- Azure Service Fabric running on Windows Server 2012 R2 or later
- Azure Virtual Machines and Azure 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
Note
Client applications (for example, WPF, Windows Forms, or UWP) aren't supported.
Prerequisites for using Snapshot Debugger
Packages and configurations
- Include the Snapshot Collector NuGet package in your application.
- Configure collection parameters in
ApplicationInsights.config
.
Permissions
- Verify you're added to the Application Insights Snapshot Debugger role for the target Application Insights Snapshot.
How Snapshot Debugger works
The Snapshot Debugger is implemented as an Application Insights telemetry processor. When your application runs, the Snapshot Debugger telemetry processor is added to your application's system-generated logs pipeline.
Important
Snapshots might contain personal data or other sensitive information in variable and parameter values. Snapshot data is stored in the same region as your Application Insights resource.
Snapshot Debugger process
The Snapshot Debugger process starts and ends with the TrackException
method. A process snapshot is a suspended clone of the running process, so that your users experience little to no interruption. In a typical scenario:
Your application throws the
TrackException
.The Snapshot Debugger monitors exceptions as they're thrown by subscribing to the
AppDomain.CurrentDomain.FirstChanceException
event.A counter is incremented for the problem ID.
- When the counter reaches the
ThresholdForSnapshotting
value, the problem ID is added to a collection plan.
Note
The
ThresholdForSnapshotting
default minimum value is 1. With this value, your app has to trigger the same exception twice before a snapshot is created.- When the counter reaches the
The exception event's problem ID is computed and compared against the problem IDs in the collection plan.
If there's a match between problem IDs, a snapshot of the running process is created.
- The snapshot is assigned a unique identifier and the exception is stamped with that identifier.
Note
The snapshot creation rate is limited by the
SnapshotsPerTenMinutesLimit
setting. By default, the limit is one snapshot every 10 minutes.After the
FirstChanceException
handler returns, the thrown exception is processed as normal.The exception reaches the
TrackException
method again and is reported to Application Insights, along with the snapshot identifier.
Note
Set IsEnabledInDeveloperMode
to true
if you want to generate snapshots while you debug in Visual Studio.
Snapshot Uploader process
While the Snapshot Debugger process continues to run and serve traffic to users with little interruption, the snapshot is handed off to the Snapshot Uploader process. In a typical scenario, the Snapshot Uploader:
Creates a minidump.
Uploads the minidump to Application Insights, along with any relevant symbol (.pdb) files.
Note
No more than 50 snapshots per day can be uploaded.
If you enabled the Snapshot Debugger but you aren't seeing snapshots, see the Troubleshooting guide.
Upgrading Snapshot Debugger
Snapshot Debugger auto-upgrades via the built-in, preinstalled Application Insights site extension.
Manually adding an Application Insights site extension to keep Snapshot Debugger up-to-date is deprecated.
Overhead
The Snapshot Debugger is designed for use in production environments. The default settings include rate limits to minimize the impact on your applications.
However, you may experience small CPU, memory, and I/O overhead associated with the Snapshot Debugger, such as:
- When an exception is thrown in your application
- If the exception handler decides to create a snapshot
- When
TrackException
is called
There is no additional cost for storing data captured by Snapshot Debugger.
See example scenarios in which you may experience Snapshot Debugger overhead.
Limitations
This section discusses limitations for the Snapshot Debugger.
Data retention
Debug snapshots are stored for 15 days. The default data 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. 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
- Provide a debugging experience in Visual Studio
By default, Visual Studio 2017 versions 15.2+ publishes symbols for release builds when it publishes to App Service.
In prior versions, you must 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 either:
- In the same folder of the main application
.dll
(typically,wwwroot/bin
), or - 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 that you use Full, Portable, or Embedded.
Optimized builds
In some cases, local variables can't be viewed in release builds because of optimizations applied by the JIT compiler.
However, in App Service, the Snapshot Debugger can deoptimize throwing methods that are part of its collection plan.
Tip
Install the Application Insights Site extension in your instance of App Service to get deoptimization support.
Next steps
Enable the Application Insights Snapshot Debugger for your application:
- Azure App Service
- Azure Functions
- Azure Cloud Services
- Azure Service Fabric
- Azure Virtual Machines and Virtual Machine Scale Sets
- On-premises virtual or physical machines
Release notes for Microsoft.ApplicationInsights.SnapshotCollector
This section contains the release notes for the Microsoft.ApplicationInsights.SnapshotCollector
NuGet package for .NET applications, which is used by the Application Insights Snapshot Debugger.
Learn more about the Application Insights Snapshot Debugger for .NET applications.
For bug reports and feedback, open an issue on GitHub.
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.
1.4.6
A point release to address a regression when using .NET 8 applications.
Bug fixes
- Exceptions thrown from dynamically generated methods (e.g. compiled expression trees) in .NET 8 are not being tracked correctly. Fixed.
1.4.5
A point release to address a user-reported bug.
Bug fixes
- Fixed AccessViolationException when reading some PDBs.
Changes
- Added a ReadMe to the NuGet package.
- Updated msdia140.dll.
1.4.4
A point release to address user-reported bugs.
Bug fixes
Changes
- Lowered PDB scan failure messages from Error to Warning.
- Updated msdia140.dll.
- Avoid making a service connection if the debugger is disabled via site extension settings.
1.4.3
A point release to address user-reported bugs.
Bug fixes
- Fixed Hide the IMDS dependency from dependency tracker..
- Fixed ArgumentException: telemetryProcessorTypedoes not implement ITelemetryProcessor..
Snapshot Collector used via SDK isn't supported when the Interop feature is enabled. See More not supported scenarios.
1.4.2
A point release to address a user-reported bug.
Bug fixes
Fixed ArgumentException: Delegates must be of the same type.
1.4.1
A point release to revert a breaking change introduced in 1.4.0.
Bug fixes
Fixed Method not found in WebJobs.
1.4.0
Addressed multiple improvements and added support for Microsoft Entra authentication for Application Insights ingestion.
Changes
- Reduced Snapshot Collector package size by 60% from 10.34 MB to 4.11 MB.
- Targeted netstandard2.0 only in Snapshot Collector.
- Bumped Application Insights SDK dependency to 2.15.0.
- Added back
MinidumpWithThreadInfo
when writing dumps. - Added
CompatibilityVersion
to improve synchronization between the Snapshot Collector agent and the Snapshot Uploader on breaking changes. - Changed
SnapshotUploader
LogFile naming algorithm to avoid excessive file I/O in App Service. - Added
pid
,role name
, andprocess start time
to uploaded blob metadata. - Used
System.Diagnostics.Process
in Snapshot Collector and Snapshot Uploader.
New features
Added Microsoft Entra authentication to SnapshotCollector
. To learn more about Microsoft Entra authentication in Application Insights, see Microsoft Entra authentication for Application Insights.
1.3.7.5
A point release to backport a fix from 1.4.0-pre.
Bug fixes
Fixed ObjectDisposedException on shutdown.
1.3.7.4
A point release to address a problem discovered in testing the App Service codeless attach scenario.
Changes
The netcoreapp3.0
target now depends on Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (previously >= 2.1.2).
1.3.7.3
A point release to address a couple of high-impact issues.
Bug fixes
- Fixed PDB discovery in the wwwroot/bin folder, which was broken when we changed the symbol search algorithm in 1.3.6.
- Fixed noisy
ExtractWasCalledMultipleTimesException
in telemetry.
1.3.7
Changes
The netcoreapp2.0
target of SnapshotCollector
depends on Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (again). This change reverts behavior to how it was before 1.3.5. We tried to upgrade it in 1.3.6, but it broke some App Service scenarios.
New features
Snapshot Collector reads and parses the ConnectionString
from the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable or from the TelemetryConfiguration
. Primarily, it's used to set the endpoint for connecting to the Snapshot service. For more information, see the Connection strings documentation.
Bug fixes
Switched to using HttpClient
for all targets except net45
because WebRequest
was failing in some environments because of an incompatible SecurityProtocol
(requires TLS 1.2).
1.3.6
Changes
SnapshotCollector
now depends onMicrosoft.ApplicationInsights
>= 2.5.1 for all target frameworks. This requirement might be a breaking change if your application depends on an older version of the Microsoft.ApplicationInsights SDK.- Removed support for TLS 1.0 and 1.1 in Snapshot Uploader.
- Period of PDB scans now defaults 24 hours instead of 15 minutes. Configurable via
PdbRescanInterval
onSnapshotCollectorConfiguration
. - PDB scan searches top-level folders only, instead of recursive. This change might be a breaking change if your symbols are in subfolders of the binary folder.
New features
- Log rotation in
SnapshotUploader
to avoid filling the logs folder with old files. - Deoptimization support (via ReJIT on attach) for .NET Core 3.0 applications.
- Added symbols to NuGet package.
- Set more metadata when you upload minidumps.
- Added an
Initialized
property toSnapshotCollectorTelemetryProcessor
. It's aCancellationToken
, which is canceled when the Snapshot Collector is initialized and connected to the service endpoint. - Snapshots can now be captured for exceptions in dynamically generated methods. An example is the compiled expression trees generated by Entity Framework queries.
Bug fixes
AmbiguousMatchException
loading Snapshot Collector due to Status Monitor.GetSnapshotCollector
extension method now searches allTelemetrySinks
.- Don't start the Snapshot Uploader on unsupported platforms.
- Handle
InvalidOperationException
when you're deoptimizing dynamic methods (for example, Entity Framework).
1.3.5
- Added support for sovereign clouds (older versions don't work in sovereign clouds).
- Adding Snapshot Collector made easier by using
AddSnapshotCollector()
. For more information, see Enable Snapshot Debugger for .NET apps in Azure App Service. - Use the FISMA MD5 setting for verifying blob blocks. This setting avoids the default .NET MD5 crypto algorithm, which is unavailable when the OS is set to FIPS-compliant mode.
- Ignore .NET Framework frames when deoptimizing function calls. Control this behavior with the
DeoptimizeIgnoredModules
configuration setting. - Added the
DeoptimizeMethodCount
configuration setting that allows deoptimization of more than one function call.
1.3.4
- Allowed structured instrumentation keys.
- Increased Snapshot Uploader robustness. Continue startup even if old uploader logs can't be moved.
- Reenabled reporting more telemetry when SnapshotUploader.exe exits immediately (was disabled in 1.3.3).
- Simplified internal telemetry.
- Experimental feature: Snappoint collection plans: Add
snapshotOnFirstOccurence
. For more information, see this GitHub article.
1.3.3
Fixed bug that was causing SnapshotUploader.exe to stop responding and not upload snapshots for .NET Core apps.
1.3.2
- Experimental feature: Snappoint collection plans. For more information, see this GitHub article.
- SnapshotUploader.exe exits when the runtime unloads the
AppDomain
from whichSnapshotCollector
is loaded, instead of waiting for the process to exit. This action improves the collector reliability when hosted in IIS. - Added configuration to allow multiple
SnapshotCollector
instances that are using the same instrumentation key to share the sameSnapshotUploader
process:ShareUploaderProcess
(defaults totrue
). - Reported more telemetry when SnapshotUploader.exe exits immediately.
- Reduced the number of support files SnapshotUploader.exe needs to write to disk.
1.3.1
- Removed support for collecting snapshots with the RtlCloneUserProcess API and only support PssCaptureSnapshots API.
- Increased the default limit on how many snapshots can be captured in 10 minutes from one to three.
- Allow SnapshotUploader.exe to negotiate TLS 1.1 and 1.2.
- Reported more telemetry when
SnapshotUploader
logs a warning or an error. - Stop taking snapshots when the back-end service reports the daily quota was reached (50 snapshots per day).
- Added extra check in SnapshotUploader.exe to not allow two instances to run in the same time.
1.3.0
Changes
- For applications that target .NET Framework, Snapshot Collector now depends on Microsoft.ApplicationInsights version 2.3.0 or later. It used to be 2.2.0 or later. We believe this change won't be an issue for most applications. Let us know if this change prevents you from using the latest Snapshot Collector.
- Use exponential back-off delays in the Snapshot Uploader when retrying failed uploads.
- Use
ServerTelemetryChannel
(if available) for more reliable reporting of telemetry. - Use
SdkInternalOperationsMonitor
on the initial connection to the Snapshot Debugger service so that dependency tracking ignores it. - Improved telemetry around initial connection to Snapshot Debugger.
- Report more telemetry for the:
- App Service version.
- Azure compute instances.
- Containers.
- Azure Functions app.
Bug fixes
- When the problem counter reset interval is set to 24 days, interpret that as 24 hours.
- Fixed a bug where the Snapshot Uploader would stop processing new snapshots if there was an exception while disposing a snapshot.
1.2.3
Fixed strong-name signing with Snapshot Uploader binaries.
1.2.2
Changes
- The files needed for SnapshotUploader(64).exe are now embedded as resources in the main DLL. That means the
SnapshotCollectorFiles
folder is no longer created, which simplifies build and deployment and reduces clutter in Solution Explorer. Take care when you upgrade to review the changes in your.csproj
file. TheMicrosoft.ApplicationInsights.SnapshotCollector.targets
file is no longer needed. - Telemetry is logged to your Application Insights resource even if
ProvideAnonymousTelemetry
is set to false. This change is so that we can implement a health check feature in the Azure portal.ProvideAnonymousTelemetry
affects only the telemetry sent to Microsoft for product support and improvement. - When
TempFolder
orShadowCopyFolder
are redirected to environment variables, keep the collector idle until those environment variables are set. - For applications that connect to the internet via a proxy server, Snapshot Collector now autodetects any proxy settings and passes them on to SnapshotUploader.exe.
- Lower the priority of the
SnapshotUploader
process (where possible). This priority can be overridden via theIsLowPrioirtySnapshotUploader
option. - Added a
GetSnapshotCollector
extension method onTelemetryConfiguration
for scenarios where you want to configure the Snapshot Collector programmatically. - Set the Application Insights SDK version (instead of the application version) in customer-facing telemetry.
- Send the first heartbeat event after two minutes.
Bug fixes
- Fixed
NullReferenceException
when exceptions have null or immutable Data dictionaries. - In the uploader, retry PDB matching a few times if we get a sharing violation.
- Fix duplicate telemetry when more than one thread calls into the telemetry pipeline at startup.
1.2.1
Changes
- XML Doc comment files are now included in the NuGet package.
- Added an
ExcludeFromSnapshotting
extension method onSystem.Exception
for scenarios where you know you have a noisy exception and want to avoid creating snapshots for it. - Added an
IsEnabledWhenProfiling
configuration property that defaults to true. This is a change from previous versions where snapshot creation was temporarily disabled if the Application Insights Profiler was performing a detailed collection. The old behavior can be recovered by setting this property tofalse
.
Bug fixes
- Sign SnapshotUploader64.exe properly.
- Protect against double-initialization of the telemetry processor.
- Prevent double logging of telemetry in apps with multiple pipelines.
- Fixed a bug with the expiration time of a collection plan, which could prevent snapshots after 24 hours.
1.2.0
The biggest change in this version (hence the move to a new minor version number) is a rewrite of the snapshot creation and handling pipeline. In previous versions, this functionality was implemented in native code (ProductionBreakpoints.dll* and SnapshotHolder.exe*). The new implementation is all managed code with P/Invokes.
For this first version using the new pipeline, we haven't strayed far from the original behavior. The new implementation allows for better error reporting and sets us up for future improvements.
Other changes in this version
- MinidumpUploader.exe has been renamed to SnapshotUploader.exe (or SnapshotUploader64.exe).
- Added timing telemetry to DeOptimize/ReOptimize requests.
- Added gzip compression for minidump uploads.
- Fixed a problem where PDBs were locked preventing site upgrade.
- Log the original folder name (SnapshotCollectorFiles) when shadow-copying.
- Adjusted memory limits for 64-bit processes to prevent site restarts due to OOM.
- Fixed an issue where snapshots were still collected even after disabling.
- Log heartbeat events to customer's AI resource.
- Improved snapshot speed by removing "Source" from the problem ID.
1.1.2
Changes
- Augmented usage telemetry.
- Detect and report .NET version and OS.
- Detect and report more Azure environments (Azure Cloud Services, Azure Service Fabric).
- Record and report exception metrics (number of first-chance exceptions and the number of
TrackException
calls) in Heartbeat telemetry.
Bug fixes
- Correct handling of
SqlException
where the inner exception (Win32Exception) isn't thrown. - Trimmed trailing spaces on symbol folders, which caused an incorrect parse of command-line arguments to the
MinidumpUploader
. - Prevented infinite retry of failed connections to the Snapshot Debugger agent's endpoint.
1.1.0
Changes
- Added host memory protection. This feature reduces the impact on the host machine's memory.
- Improved the Azure portal snapshot viewing experience.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for