排查启用 Application Insights Snapshot Debugger 或查看快照时遇到的问题Troubleshoot problems enabling Application Insights Snapshot Debugger or viewing snapshots

如果为应用程序启用了 Application Insights 快照调试器,但未看到出现异常的快照,则可以使用以下说明进行故障排除。If you enabled Application Insights Snapshot Debugger for your application, but are not seeing snapshots for exceptions, you can use these instructions to troubleshoot. 可能有许多不同的原因导致未生成快照。There can be many different reasons why snapshots are not generated. 可以运行快照运行状况检查以确定一些可能的常见原因。You can run the snapshot health check to identify some of the possible common causes.

使用快照运行状况检查Use the snapshot health check

几个常见问题会导致不显示“打开调试快照”。Several common problems result in the Open Debug Snapshot not showing up. 例如,使用过时的快照收集器;达到每日上传限制;或者可能快照只是需要很长时间上传。Using an outdated Snapshot Collector, for example; reaching the daily upload limit; or perhaps the snapshot is just taking a long time to upload. 使用“快照运行状况检查”解决常见问题。Use the Snapshot Health Check to troubleshoot common problems.

端到端跟踪视图的异常窗格中有一个链接,可将你带到“快照运行状况检查”。There's a link in the exception pane of the end-to-end trace view that takes you to the Snapshot Health Check.


这个交互式类似聊天的界面可查找常见问题并指导你解决问题。The interactive, chat-like interface looks for common problems and guides you to fix them.


如果这样不能解决问题,请参阅以下手动故障排除步骤。If that doesn't solve the problem, then refer to the following manual troubleshooting steps.

验证检测密钥Verify the instrumentation key

请确保在发布的应用程序中使用正确的检测密钥。Make sure you're using the correct instrumentation key in your published application. 通常,从 ApplicationInsights.config 文件中读取检测密钥。Usually, the instrumentation key is read from the ApplicationInsights.config file. 请验证该值是否与在门户中看到的 Application Insights 资源的检测密钥相同。Verify the value is the same as the instrumentation key for the Application Insights resource that you see in the portal.

检查 SSL 客户端设置 (ASP.NET)Check SSL client settings (ASP.NET)

如果在虚拟机上的 Azure 应用服务或 IIS 中承载了 ASP.NET 应用程序,则由于缺少 SSL 安全协议,应用程序可能无法连接到 Snapshot Debugger 服务。If you have an ASP.NET application hosted in Azure App Service or in IIS on a virtual machine, your application could fail to connect to the Snapshot Debugger service due to a missing SSL security protocol. Snapshot Debugger 终结点需要 TLS 版本 1.2The Snapshot Debugger endpoint requires TLS version 1.2. SSL 安全协议集是由 web.config 的 system.web 部分中的 httpRuntime targetFramework 值启用的规定之一。如果 httpRuntime targetFramework 为 4.5.2 或更低版本,则默认不包含 TLS 1.2。The set of SSL security protocols is one of the quirks enabled by the httpRuntime targetFramework value in the system.web section of web.config. If the httpRuntime targetFramework is 4.5.2 or lower, then TLS 1.2 isn't included by default.


httpRuntime targetFramework 值与构建应用程序时使用的目标框架无关。The httpRuntime targetFramework value is independent of the target framework used when building your application.

若要检查设置,请打开 web.config 文件,然后找到 system.web 部分。To check the setting, open your web.config file and find the system.web section. 请确保将 httpRuntimetargetFramework 设置为 4.6 或更高版本。Ensure that the targetFramework for httpRuntime is set to 4.6 or above.

   <httpRuntime targetFramework="4.7.2" />


如果修改 httpRuntime targetFramework 值,则会更改应用于应用程序的运行时规定,并可能导致其他细微的行为变化。Modifying the httpRuntime targetFramework value changes the runtime quirks applied to your application and can cause other, subtle behavior changes. 进行此更改后,请务必彻底测试你的应用程序。Be sure to test your application thoroughly after making this change. 有关兼容性更改的完整列表,请参阅 https://docs.microsoft.com/dotnet/framework/migration-guide/application-compatibility#retargeting-changesFor a full list of compatibility changes, please see https://docs.microsoft.com/dotnet/framework/migration-guide/application-compatibility#retargeting-changes


如果 targetFramework 为 4.7 或更高版本,则 Windows 将确定可用的协议。If the targetFramework is 4.7 or above then Windows determines the available protocols. Azure 应用服务中提供了 TLS 1.2。In Azure App Service, TLS 1.2 is available. 但是,如果使用的是自己的虚拟机,则可能需要在操作系统中启用 TLS 1.2。However, if you are using your own virtual machine, you may need to enable TLS 1.2 in the OS.

.NET Core 预览版Preview Versions of .NET Core

如果应用程序使用 .NET Core 预览版,并已通过门户中的 Application Insights 窗格启用了 Snapshot Debugger,则 Snapshot Debugger 可能无法启动。If the application uses a preview version of .NET Core, and Snapshot Debugger was enabled through the Application Insights pane in the portal, then Snapshot Debugger may not start. 除了通过 Application Insights 窗格进行启用外,请按照为其他环境启用 Snapshot Debugger 中的说明首先将 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包包含在应用程序中。Follow the instructions at Enable Snapshot Debugger for other environments first to include the Microsoft.ApplicationInsights.SnapshotCollector NuGet package with the application * in addition _ to enabling through the Application Insights pane.

升级到最新版本的 NuGet 包Upgrade to the latest version of the NuGet package

如果已通过门户中的 Application Insights 窗格启用了快照调试器,那么应用程序应该已经在运行最新的 NuGet 包。If Snapshot Debugger was enabled through the Application Insights pane in the portal, then your application should already be running the latest NuGet package. 如果通过包含 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包启用了快照调试器,请使用 Visual Studio 的 NuGet 包管理器确保使用的是最新版本的 Microsoft.ApplicationInsights.SnapshotCollector。If Snapshot Debugger was enabled by including the Microsoft.ApplicationInsights.SnapshotCollector NuGet package, use Visual Studio's NuGet Package Manager to make sure you're using the latest version of Microsoft.ApplicationInsights.SnapshotCollector.

检查上传程序日志Check the uploader logs

创建快照后,将在磁盘上创建一个小型转储文件 (.dmp)。After a snapshot is created, a minidump file (.dmp) is created on disk. 一个单独的上传程序进程会创建该小型转储文件,并将其连同所有关联的 PDB 一起上传到 Application Insights Snapshot Debugger 存储。A separate uploader process creates that minidump file and uploads it, along with any associated PDBs, to Application Insights Snapshot Debugger storage. 成功上传小型转储后,会将其从磁盘中删除。After the minidump has uploaded successfully, it's deleted from disk. 上传程序进程的日志文件会保留在磁盘上。The log files for the uploader process are kept on disk. 在应用服务环境中,可在 D:\Home\LogFiles 中找到这些日志。In an App Service environment, you can find these logs in D:\Home\LogFiles. 通过应用服务的 Kudu 管理站点查找这些日志文件。Use the Kudu management site for App Service to find these log files.

  1. 在 Azure 门户中,打开应用服务应用程序。Open your App Service application in the Azure portal.
  2. 单击“高级工具”或搜索“Kudu”。Click _*Advanced Tools**, or search for Kudu.
  3. 单击“转到”。Click Go.
  4. 在“调试控制台”下拉列表框中,选择“CMD”。In the Debug console drop-down list box, select CMD.
  5. 单击“日志文件”。Click LogFiles.

应至少看到一个名称以 Uploader_SnapshotUploader_ 开头,且扩展名为 .log 的文件。You should see at least one file with a name that begins with Uploader_ or SnapshotUploader_ and a .log extension. 单击相应图标,下载任意日志文件或在浏览器中打开文件。Click the appropriate icon to download any log files or open them in a browser. 文件名包括可标识应用服务实例的唯一后缀。The file name includes a unique suffix that identifies the App Service instance. 如果应用服务实例托管于多台计算机上,则每台计算机都有单独的日志文件。If your App Service instance is hosted on more than one machine, there are separate log files for each machine. 当上传程序检测到新的小型转储文件时,会将其记录在日志文件中。When the uploader detects a new minidump file, it's recorded in the log file. 下面是成功的快照和上传的示例:Here's an example of a successful snapshot and upload:

SnapshotUploader.exe Information: 0 : Received Fork request ID 139e411a23934dc0b9ea08a626db16c5 from process 6368 (Low pri)
SnapshotUploader.exe Information: 0 : Creating minidump from Fork request ID 139e411a23934dc0b9ea08a626db16c5 from process 6368 (Low pri)
SnapshotUploader.exe Information: 0 : Dump placeholder file created: 139e411a23934dc0b9ea08a626db16c5.dm_
SnapshotUploader.exe Information: 0 : Dump available 139e411a23934dc0b9ea08a626db16c5.dmp
SnapshotUploader.exe Information: 0 : Successfully wrote minidump to D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp
SnapshotUploader.exe Information: 0 : Uploading D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp, 214.42 MB (uncompressed)
SnapshotUploader.exe Information: 0 : Upload successful. Compressed size 86.56 MB
SnapshotUploader.exe Information: 0 : Extracting PDB info from D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp.
SnapshotUploader.exe Information: 0 : Matched 2 PDB(s) with local files.
SnapshotUploader.exe Information: 0 : Stamp does not want any of our matched PDBs.
SnapshotUploader.exe Information: 0 : Deleted D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp


上面的示例来自 1.2.0 版的 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包。The example above is from version 1.2.0 of the Microsoft.ApplicationInsights.SnapshotCollector NuGet package. 在更早的版本中,上传程序进程名为 MinidumpUploader.exe,且日志不太详细。In earlier versions, the uploader process is called MinidumpUploader.exe and the log is less detailed.

在之前的示例中,检测密钥是 c12a605e73c44346a984e00000000000In the previous example, the instrumentation key is c12a605e73c44346a984e00000000000. 此值应与应用程序的检测密钥相匹配。This value should match the instrumentation key for your application. 小型转储与 ID 为 139e411a23934dc0b9ea08a626db16c5 的快照相关联。The minidump is associated with a snapshot with the ID 139e411a23934dc0b9ea08a626db16c5. 稍后可以使用此 ID 在 Application Insights Analytics 中找到关联的异常遥测。You can use this ID later to locate the associated exception telemetry in Application Insights Analytics.

上传程序大约每 15 分钟扫描一次新 PDB。The uploader scans for new PDBs about once every 15 minutes. 下面是一个示例:Here's an example:

SnapshotUploader.exe Information: 0 : PDB rescan requested.
SnapshotUploader.exe Information: 0 : Scanning D:\home\site\wwwroot for local PDBs.
SnapshotUploader.exe Information: 0 : Local PDB scan complete. Found 2 PDB(s).
SnapshotUploader.exe Information: 0 : Deleted PDB scan marker : D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\6368.pdbscan

对于未托管于应用服务中的应用程序,上传程序日志与小型转储位于同一文件夹:%TEMP%\Dumps\<ikey>(其中 <ikey> 是检测密钥)。For applications that aren't hosted in App Service, the uploader logs are in the same folder as the minidumps: %TEMP%\Dumps\<ikey> (where <ikey> is your instrumentation key).

云服务故障排除Troubleshooting Cloud Services

对于云服务中的角色而言,默认临时文件夹可能太小,无法容纳小型转储文件,从而导致丢失快照。For roles in Cloud Services, the default temporary folder may be too small to hold the minidump files, leading to lost snapshots. 所需的空间取决于应用程序的总工作集量和并发快照数。The space needed depends on the total working set of your application and the number of concurrent snapshots. 32 位 ASP.NET Web 角色的工作集通常在 200 MB 到 500 MB 之间。The working set of a 32-bit ASP.NET web role is typically between 200 MB and 500 MB. 允许存在至少两个并发快照。Allow for at least two concurrent snapshots. 例如,如果应用程序使用 1 GB 的总工作集,则应确保是否至少有 2 GB 的磁盘空间可用来存储快照。For example, if your application uses 1 GB of total working set, you should make sure that there is at least 2 GB of disk space to store snapshots. 按照这些步骤为云服务角色配置快照的专用本地资源。Follow these steps to configure your Cloud Service role with a dedicated local resource for snapshots.

  1. 通过编辑云服务定义 (.csdef) 文件将新的本地资源添加到云服务中。Add a new local resource to your Cloud Service by editing the Cloud Service definition (.csdef) file. 以下示例使用 5 GB 大小定义名为 SnapshotStore 的资源。The following example defines a resource called SnapshotStore with a size of 5 GB.

      <LocalStorage name="SnapshotStore" cleanOnRoleRecycle="false" sizeInMB="5120" />
  2. 修改角色的启动代码以添加指向 SnapshotStore 本地资源的环境变量。Modify your role's startup code to add an environment variable that points to the SnapshotStore local resource. 对于辅助角色,应将代码添加到角色的 OnStart 方法:For Worker Roles, the code should be added to your role's OnStart method:

    public override bool OnStart()
        Environment.SetEnvironmentVariable("SNAPSHOTSTORE", RoleEnvironment.GetLocalResource("SnapshotStore").RootPath);
        return base.OnStart();

    对于 Web 角色 (ASP.NET),应将代码添加到 Web 应用程序的 Application_Start 方 法:For Web Roles (ASP.NET), the code should be added to your web application's Application_Start method:

    using Microsoft.WindowsAzure.ServiceRuntime;
    using System;
    namespace MyWebRoleApp
        public class MyMvcApplication : System.Web.HttpApplication
           protected void Application_Start()
              Environment.SetEnvironmentVariable("SNAPSHOTSTORE", RoleEnvironment.GetLocalResource("SnapshotStore").RootPath);
              // TODO: The rest of your application startup code
  3. 更新角色的 ApplicationInsights.config 文件以重写 SnapshotCollector 使用的临时文件夹位置Update your role's ApplicationInsights.config file to override the temporary folder location used by SnapshotCollector

     <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
       <!-- Use the SnapshotStore local resource for snapshots -->
       <!-- Other SnapshotCollector configuration options -->

重写影子副本文件夹Overriding the Shadow Copy folder

当快照收集器启动时,它会尝试在磁盘上查找适合用于运行快照上传程序进程的文件夹。When the Snapshot Collector starts up, it tries to find a folder on disk that is suitable for running the Snapshot Uploader process. 所选的文件夹称为影子副本文件夹。The chosen folder is known as the Shadow Copy folder.

快照收集器检查几个已知位置,并确保它有权复制快照上传程序二进制文件。The Snapshot Collector checks a few well-known locations, making sure it has permissions to copy the Snapshot Uploader binaries. 使用了以下环境变量:The following environment variables are used:

  • Fabric_Folder_App_TempFabric_Folder_App_Temp

如果找不到合适的文件夹,则快照收集器将报告一个错误,指出“找不到合适的影子副本文件夹。”If a suitable folder can't be found, Snapshot Collector reports an error saying "Could not find a suitable shadow copy folder."

如果复制失败,则快照收集器会报告一个 ShadowCopyFailed 错误。If the copy fails, Snapshot Collector reports a ShadowCopyFailed error.

如果无法启动上传程序,则快照收集器会报告一个 UploaderCannotStartFromShadowCopy 错误。If the uploader can't be launched, Snapshot Collector reports an UploaderCannotStartFromShadowCopy error. 消息的正文通常包含 System.UnauthorizedAccessExceptionThe body of the message often contains System.UnauthorizedAccessException. 发生此错误通常是因为应用程序正在权限降低的帐户下运行。This error usually occurs because the application is running under an account with reduced permissions. 此帐户有权向影子副本文件夹进行写入,但无权执行代码。The account has permission to write to the shadow copy folder, but it doesn't have permission to execute code.

因为这些错误通常发生在启动期间,所以它们后面通常会跟有一个 ExceptionDuringConnect 错误,指出“上传程序无法启动。”Since these errors usually happen during startup, they'll usually be followed by an ExceptionDuringConnect error saying "Uploader failed to start."

若要解决这些错误,可以通过 ShadowCopyFolder 配置选项手动指定影子副本文件夹。To work around these errors, you can specify the shadow copy folder manually via the ShadowCopyFolder configuration option. 例如,使用 ApplicationInsights.config:For example, using ApplicationInsights.config:

 <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
   <!-- Override the default shadow copy folder. -->
   <!-- Other SnapshotCollector configuration options -->

或者,如果将 appsettings.json 用于 .NET Core 应用程序,则使用:Or, if you're using appsettings.json with a .NET Core application:

  "ApplicationInsights": {
    "InstrumentationKey": "<your instrumentation key>"
  "SnapshotCollectorConfiguration": {
    "ShadowCopyFolder": "D:\\SnapshotUploader"

使用 Application Insights 搜索查找附带快照的异常Use Application Insights search to find exceptions with snapshots

创建快照后,出现的异常标记有快照 ID。When a snapshot is created, the throwing exception is tagged with a snapshot ID. 向 Application Insights 报告异常遥测时,该快照 ID 作为自定义属性包含在内。That snapshot ID is included as a custom property when the exception telemetry is reported to Application Insights. 通过 Application Insights 中的“搜索”,可借助 ai.snapshot.id 自定义属性找到所有遥测。Using Search in Application Insights, you can find all telemetry with the ai.snapshot.id custom property.

  1. 在 Azure 门户中浏览到 Application Insights 资源。Browse to your Application Insights resource in the Azure portal.
  2. 单击“搜索”。 Click Search.
  3. 在“搜索”文本框中输入 ai.snapshot.id,然后按 Enter。Type ai.snapshot.id in the Search text box and press Enter.

在门户中使用快照 ID 搜索遥测

如果此搜索未返回任何结果,则表示在选定的时间范围内,未向 Application Insights 报告任何有关你的应用程序的快照。If this search returns no results, then no snapshots were reported to Application Insights for your application in the selected time range.

若要从上传程序日志中搜索特定快照 ID,请在“搜索”框中键入该 ID。To search for a specific snapshot ID from the Uploader logs, type that ID in the Search box. 如果快照已上传但找不到该快照的遥测,请按照以下步骤操作:If you can't find telemetry for a snapshot that you know was uploaded, follow these steps:

  1. 请验证检测密钥,仔细检查正在查看的 Application Insights 资源是否正确。Double-check that you're looking at the right Application Insights resource by verifying the instrumentation key.

  2. 使用上传程序日志中的时间戳调整搜索的“时间范围”筛选器,以包含该时间范围。Using the timestamp from the Uploader log, adjust the Time Range filter of the search to cover that time range.

如果仍然看不到任何带快照 ID 的异常,则表示未向 Application Insights 报告该异常遥测。If you still don't see an exception with that snapshot ID, then the exception telemetry wasn't reported to Application Insights. 如果应用程序在拍摄快照后,但还未报告异常遥测就崩溃,则会发生这种情况。This situation can happen if your application crashed after it took the snapshot but before it reported the exception telemetry. 在这种情况下,请查看 Diagnose and solve problems 下的应用服务日志,了解是否存在意外重启或未处理的异常。In this case, check the App Service logs under Diagnose and solve problems to see if there were unexpected restarts or unhandled exceptions.

编辑网络代理或防火墙规则Edit network proxy or firewall rules

如果应用程序通过代理或防火墙连接到 Internet,则可能需要编辑规则以允许应用程序与 Snapshot Debugger 服务进行通信。If your application connects to the Internet via a proxy or a firewall, you may need to edit the rules to allow your application to communicate with the Snapshot Debugger service. Snapshot Debugger 使用的 IP 包含在 Azure Monitor 服务标记中。The IPs used by Snapshot Debugger are included in the Azure Monitor service tag.