排查启用 Application Insights 快照调试器或查看快照时遇到的问题

如果为应用程序启用了 Application Insights Snapshot Debugger，但看不到异常的快照，请使用以下说明进行故障排除。

快照生成因不同原因而失败。首先运行快照健康检查，以找出一些常见原因。

不支持 Snapshot Collector 的情况

不支持 Snapshot Collector 的情况：

场景	副作用	建议
当您在应用程序中直接使用快照收集器 SDK（`.csproj`）并启用高级选项 Interop 时。	你将失去本地的 Application Insights SDK（包括 Snapshot Collector 遥测）。因此，没有可用的快照。应用程序在启动时可能会崩溃，并出现 `System.ArgumentException: telemetryProcessorType does not implement ITelemetryProcessor`。有关 Application Insights 功能互操作的详细信息，请参阅 Application Insights 集成疑难解答。	如果使用高级选项互操作，请通过 Azure 门户启用无代码快照收集器注入。

请确保使用了适当的 Snapshot Debugger 端点

目前，在由世纪互联运营的 Azure 的区域需要进行终结点修改。

对于 App Service 和使用 Application Insights SDK 的应用程序，请使用 Snapshot Debugger 支持的覆盖设置来更新连接字符串：

连接字符串属性	由世纪互联运营的 Azure
SnapshotEndpoint	`https://snapshot.monitor.azure.cn`

有关详细信息，请参阅具有显式终结点重写的连接字符串。

对于 Function App，请使用支持的替代更新 host.json ：

属性	由世纪互联运营的 Azure
AgentEndpoint	`https://snapshot.monitor.azure.cn`

使用世纪互联运营的 Azure 代理终结点更新的 host.json 的示例：

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingExcludedTypes": "Request",
            "samplingSettings": {
                "isEnabled": true
            },
            "snapshotConfiguration": {
                "isEnabled": true,
                "agentEndpoint": "https://snapshot.monitor.azure.cn"
            }
        }
    }
}

使用快照运行状况检查

几个常见问题会导致“打开调试快照”按钮不显示。例如：

使用过时的快照收集器。
达到每日上传限制。
快照需要很长时间才能上传。

访问快照健康检查，通过端到端追踪视图中的“异常”窗格中的链接来排查常见问题。

显示如何进入“快照运行状况检查”的屏幕截图。

这个交互式类似聊天的界面可查找常见问题并指导你解决问题。

显示交互式“运行状况检查”窗口的屏幕截图，其中列出了问题以及如何解决这些问题的建议。

如果此方法无法解决问题，请参阅以下手动故障排除步骤。

检查 TLS/SSL 客户端设置 (ASP.NET)

如果 ASP.NET 应用程序托管在虚拟机上的 Azure 应用服务或 IIS 中，则应用程序由于缺少 TLS 安全协议而无法连接到 Snapshot Debugger 服务。

Snapshot Debugger 终结点需要 TLS 版本 1.2。这组安全协议是 httpRuntime targetFramework 中 system.web 部分的 web.config 值所启用的特性之一。

如果 httpRuntime targetFramework 为 4.5.2 或更低版本，则默认情况下不包含 TLS 1.2。

注意

httpRuntime targetFramework 值与构建应用程序时使用的目标框架无关。

若要检查设置，请打开 web.config 文件并找到分区 system.web 。请确保将 targetFramework 的 httpRuntime 设置为 4.6 或更高版本。

<system.web>
    ...
    <httpRuntime targetFramework="4.7.2" />
    ...
</system.web>

注意

修改 httpRuntime targetFramework 值会更改适用于你的应用程序的运行时特殊行为，并可能导致其他细微的行为变化。进行此更改后，请彻底测试应用程序。有关兼容性更改，请参阅重定目标更改。

注意

如果 targetFramework 为 4.7 或更高版本，那么 Windows 将确定可用的协议。 Azure 应用程序服务中提供了 TLS 1.2。但是，如果使用自己的虚拟机，可能需要在操作系统中启用 TLS 1.2。

Snapshot Debugger 开销场景

Snapshot Debugger 设计用于生产环境。默认设置包括速率限制，以最大限度地减少对应用程序的影响。

在以下情况下，您可能会遇到与快照调试器相关的少量 CPU、内存和 I/O 开销。

当应用程序引发异常时：

为问题类型创建签名，并确定是否创建快照会带来一些 CPU 和内存开销。
如果启用了取消优化，则重新执行引发异常的方法会增加开销。下次运行该方法时，会出现此开销。根据方法的大小，CPU 时间可能介于 1 ms 到 100 ms 之间。

如果异常处理程序决定创建快照：

创建进程快照大约需要半秒（P50 = 0.3 秒、P90 = 1.2 秒、P95 = 1.9 秒）并暂停在该时间引发异常的线程。其他线程不会被阻止。
将进程快照转换为小型转储并将其上传至 Application Insights 需要几分钟时间。
- 转换：P50 = 63 s，P90 = 187 s，P95 = 275 s。
- 上传：P50 = 31 s，P90 = 75 s，P95 = 98 s。
快照上传程序在单独的进程中运行，执行此转换。 Snapshot Uploader 进程以低于正常 CPU 优先级运行并使用低优先级 I/O。

快照上传器首先将小型转储文件写入磁盘。磁盘空间与原始进程的工作集大致相同。写入小型转储文件时，由于需要读取内存，可能会导致缺页错误。

快照上传器会在上传期间压缩迷你转储，这会占用 CPU 和内存。 CPU、内存和磁盘开销与进程快照的大小成正比。 Snapshot Uploader 按顺序处理快照。

应用程序调用 TrackException时：

快照调试器会检查该异常是否为新出现的，或者是否已为其创建快照。此检查会增加轻微的 CPU 开销。

为 .NET Core 预览版启用 Snapshot Debugger

如果使用的是 .NET Core 预览版，或者应用程序通过依赖程序集直接或间接引用 Application Insights SDK，请按照有关为其他环境启用 Snapshot Debugger 的说明进行操作。

查看诊断服务站点扩展的状态页

如果在 Azure 门户中通过 Application Insights 窗格启用了 Snapshot Debugger，则诊断服务站点扩展已启用它。

注意

Application Insights Snapshot Debugger 的无代码安装遵循 .NET Core 支持策略。有关支持的运行时的详细信息，请参阅 .Net Core 支持策略。

在以下 URL 中检查此扩展的状态页： https://<kudu-url>/DiagnosticServices

注意

状态页链接的域因云而异。

此域与应用服务的 Kudu 管理站点相同。状态页将显示 .NET 探查器和 Snapshot Collector 代理的安装状态。如果发生意外错误，页面将演示如何修复此错误。

使用应用服务的 Kudu 管理站点获取此状态页的基本 URL：

在 Azure 门户中，打开应用服务应用程序。
在左侧菜单中，选择 “开发工具>高级工具”。
选择“转到”。
在 Kudu 管理站点上时，请在 URL 中追加 /DiagnosticServices 并按 Enter。结尾如下所示：https://<kudu-url>/DiagnosticServices

升级到最新版本的 NuGet 包

根据启用快照调试器的方式，请参阅以下选项：

如果通过 Azure 门户中的 Application Insights 窗格启用了 Snapshot Debugger，则应用程序已运行最新的 NuGet 包。
如果你通过包含 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包启用了快照调试器，请使用 Visual Studio 的 NuGet 包管理器，确保你使用的是 Microsoft.ApplicationInsights.SnapshotCollector 的最新版本。

有关最新的更新和 bug 修复，请参阅发行说明。

检查上传者日志

创建快照后，单独的上传程序进程会在磁盘上创建一个小型转储文件（.dmp），并将其连同任何关联的 PDB 上传到 Application Insights Snapshot Debugger 存储。上传器成功上传小型转储后，会从磁盘上删除该小型转储文件。上传程序进程将其日志文件保留在磁盘上。在应用服务环境中，可在 D:\Home\LogFiles 中找到这些日志。通过应用服务的 Kudu 管理站点查找这些日志文件。

在 Azure 门户中，打开应用服务应用程序。
在左侧菜单中，选择 “开发工具>高级工具”。
选择“转到”。
在 调试控制台中，选择 CMD。
选择“LogFiles”。

应至少看到一个名称以 Uploader_ 或 SnapshotUploader_ 开头，且扩展名为 .log 的文件。选择相应图标，下载任意日志文件或在浏览器中打开文件。

文件名包括可标识应用程序服务实例的唯一后缀。如果多个计算机托管应用服务实例，则每台计算机都有单独的日志文件。当上传器检测到新的 minidump 文件时，它会在日志中记录该文件。下面是成功的快照和上传的示例：

SnapshotUploader.exe Information: 0 : Received Fork request ID <request-ID> from process <ID> (Low pri)
    DateTime=2018-03-09T01:42:41.8571711Z
SnapshotUploader.exe Information: 0 : Creating minidump from Fork request ID <request-ID> from process 6368 (Low pri)
    DateTime=2018-03-09T01:42:41.8571711Z
SnapshotUploader.exe Information: 0 : Dump placeholder file created: <request-ID>.dm_
    DateTime=2018-03-09T01:42:41.8728496Z
SnapshotUploader.exe Information: 0 : Dump available <request-ID>.dmp
    DateTime=2018-03-09T01:42:45.7525022Z
SnapshotUploader.exe Information: 0 : Successfully wrote minidump to D:\local\Temp\Dumps\<connection-string>\<request-ID>.dmp
    DateTime=2018-03-09T01:42:45.7681360Z
SnapshotUploader.exe Information: 0 : Uploading D:\local\Temp\Dumps\<connection-string>\<request-ID>.dmp, 214.42 MB (uncompressed)
    DateTime=2018-03-09T01:42:45.7681360Z
SnapshotUploader.exe Information: 0 : Upload successful. Compressed size 86.56 MB
    DateTime=2018-03-09T01:42:59.6184651Z
SnapshotUploader.exe Information: 0 : Extracting PDB info from D:\local\Temp\Dumps\<connection-string>\<request-ID>.dmp.
    DateTime=2018-03-09T01:42:59.6184651Z
SnapshotUploader.exe Information: 0 : Matched 2 PDB(s) with local files.
    DateTime=2018-03-09T01:42:59.6809606Z
SnapshotUploader.exe Information: 0 : Stamp does not want any of our matched PDBs.
    DateTime=2018-03-09T01:42:59.8059929Z
SnapshotUploader.exe Information: 0 : Deleted D:\local\Temp\Dumps\<connection-string>\<request-ID>.dmp
    DateTime=2018-03-09T01:42:59.8530649Z

注意

前面的示例来自 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包的 1.2.0 版。在更早的版本中，上传程序进程名为 MinidumpUploader.exe，且日志不太详细。

在前面的示例中，连接字符串应与应用程序的连接字符串匹配。

请求 ID 将小型转储与快照关联起来。稍后可以使用此 ID 在 Application Insights Analytics 中找到关联的异常记录。

上传程序大约每 15 分钟扫描一次新 PDB。下面是一个示例：

SnapshotUploader.exe Information: 0 : PDB rescan requested.
    DateTime=2018-03-09T01:47:19.4457768Z
SnapshotUploader.exe Information: 0 : Scanning D:\home\site\wwwroot for local PDBs.
    DateTime=2018-03-09T01:47:19.4457768Z
SnapshotUploader.exe Information: 0 : Local PDB scan complete. Found 2 PDB(s).
    DateTime=2018-03-09T01:47:19.4614027Z
SnapshotUploader.exe Information: 0 : Deleted PDB scan marker : D:\local\Temp\Dumps\<connection-string>\<process-ID>.pdbscan
    DateTime=2018-03-09T01:47:19.4614027Z

未托管在应用服务中的应用程序，其上传程序日志与 minidumps 位于相同的文件夹中：，其中 %TEMP%\Dumps\<string> 是您的连接字符串。

云服务疑难解答

在云服务中，默认临时文件夹可能太小，无法保存小型转储文件，这可能会导致快照丢失。你需要的空间取决于应用程序的总工作集和并发快照的数量。

32 位 ASP.NET Web 角色的工作集通常介于 200 MB 和 500 MB 之间。预留至少两个并发快照的容量。例如，如果应用程序使用 1 GB 的总工作集，请确保至少有 2 GB 的磁盘空间来存储快照。

为云服务角色配置专用于快照的本地资源：

通过编辑云服务定义（.csdef）文件，将新的本地资源添加到云服务。以下示例使用 5 GB 大小定义名为 SnapshotStore 的资源。
```
<LocalResources>
    <LocalStorage name="SnapshotStore" cleanOnRoleRecycle="false" sizeInMB="5120" />
</LocalResources>
```

修改角色的启动代码以添加指向 SnapshotStore 本地资源的环境变量。对于辅助角色，请将代码添加到你的角色的 OnStart 方法中：

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

对于 Web 角色 (ASP.NET)，请将代码添加到您的 Web 应用程序的 Application_Start 方法中：

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
        }
    }
}

更新角色的 ApplicationInsights.config 文件，以覆盖 SnapshotCollector 使用的临时文件夹位置。

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

覆盖卷影副本文件夹

快照收集器启动时，它会尝试在磁盘上查找适合运行快照上传程序进程的文件夹。所选文件夹称为 卷影复制文件夹。

快照收集器会检查多个已知位置，并确保它有权复制快照上传程序二进制文件。它使用以下环境变量：

Fabric_Folder_App_Temp
LOCALAPPDATA
APPDATA
TEMP

如果快照收集器找不到合适的文件夹， 则会报告一条错误，指出 “找不到合适的卷影复制文件夹”。

如果复制失败，则 Snapshot Collector 会报告错误ShadowCopyFailed。

如果快照收集器无法启动上传程序， 则会报告错误 UploaderCannotStartFromShadowCopy 。消息的正文通常包含 System.UnauthorizedAccessException。发生此错误通常是因为应用程序正在权限降低的帐户下运行。该帐户有权写入影子复制文件夹，但无权运行代码。

由于这些错误通常发生在启动期间，因此随后通常还会出现一个 ExceptionDuringConnect 错误，显示 Uploader failed to start。

若要解决这些错误，请使用 ShadowCopyFolder 配置选项手动指定卷影复制文件夹。例如，使用 ApplicationInsights.config：

<TelemetryProcessors>
    <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
        <!-- Override the default shadow copy folder. -->
        <ShadowCopyFolder>D:\SnapshotUploader</ShadowCopyFolder>
        <!-- Other SnapshotCollector configuration options -->
    </Add>
</TelemetryProcessors>

或者，如果将 appsettings.json 用于 .NET Core 应用程序，则：

{
    "ApplicationInsights": {
        "ConnectionString": "<your connection string>"
    },
    "SnapshotCollectorConfiguration": {
        "ShadowCopyFolder": "D:\\SnapshotUploader"
    }
}

使用 Application Insights 搜索查找附带快照的异常

当快照调试器创建快照时，它会为所引发的异常加上快照 ID 标记。应用程序向 Application Insights 报告异常时，快照 ID 显示为自定义属性。通过使用 Application Insights 中的搜索，可以使用自定义属性查找所有记录 ai.snapshot.id 。

在 Azure 门户中浏览到 Application Insights 资源。
选择“ 调查>搜索”。
键入 ai.snapshot.id 搜索文本框，然后按 Enter。

如果此搜索未返回任何结果，则应用程序未在所选时间范围内向 Application Insights 报告任何快照。

若要从上传程序日志中搜索特定快照 ID，请在搜索框中键入该 ID。如果快照已上传但找不到该快照的记录，请按照以下步骤操作：

通过验证连接字符串，仔细检查正在查看的 Application Insights 资源是否正确。
通过使用上传程序日志中的时间戳，调整搜索的时间范围筛选器以涵盖该时间范围。

如果仍然看不到具有该快照 ID 的异常，则应用程序未将异常记录报告给 Application Insights。如果应用程序在拍摄快照后，但在报告异常记录之前就崩溃，则会发生这种情况。在这种情况下，请检查 Diagnose and solve problems 下的应用服务日志，查看是否发生了意外重启或未处理的异常。

编辑网络代理或防火墙规则

如果应用程序通过代理或防火墙连接到 Internet，则可能需要更新规则以与 Snapshot Debugger 服务通信。

Azure Monitor服务标记包括 Application Insights Snapshot Debugger 使用的 IP。有关详细信息，请参阅 Azure 服务标记虚拟网络安全概述。

使用快照时是否会产生费用？

快照调试器不会从你的订阅中扣除任何费用。它将收集的快照文件与 Application Insights SDK 收集的遥测分开存储，并且不收取快照引入或存储费用。

Last updated on 2026-09-11