编辑

通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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:

Environments

The following environments are supported:

Note

Client applications (for example, WPF, Windows Forms, or UWP) aren't supported.

Prerequisites for using Snapshot Debugger

Packages and configurations

Permissions

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:

  1. Your application throws the TrackException.

  2. The Snapshot Debugger monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event.

  3. 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.

  4. The exception event's problem ID is computed and compared against the problem IDs in the collection plan.

  5. 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.

  6. After the FirstChanceException handler returns, the thrown exception is processed as normal.

  7. 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:

  1. Creates a minidump.

  2. 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: