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

项目
10/30/2024

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

可能有许多不同的原因导致未生成快照。可以先运行快照运行状况检查，确定一些可能的常见原因。

不支持的方案

不支持 Snapshot Collector 的方案：

场景	副作用	建议
在应用程序 (.csproj) 中直接使用 Snapshot Collector SDK 并且已启用高级选项“互操作”时。	本地 Application Insights SDK（包括 Snapshot Collector 遥测）会丢失，因此没有快照可用。应用程序在启动 `System.ArgumentException: telemetryProcessorTypedoes not implement ITelemetryProcessor` 时可能会崩溃。有关 Application Insights 功能“互操作”的详细信息，请参阅文档。	如果使用高级选项“互操作”，请使用通过 Azure 门户启用的无代码 Snapshot Collector 注入。

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

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

对于使用 Application Insights SDK 的应用程序服务和应用程序，必须使用 Snapshot Debugger 支持的替代来更新连接字符串：

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

若要详细了解其他连接替代，请参阅 Application Insights 文档。

对于函数应用，必须使用支持的替代来更新 host.json：

properties	由世纪互联运营的 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"
      }
    }
  }
}

使用快照运行状况检查

几个常见问题会导致不显示“打开调试快照”。例如，使用过时的快照收集器；达到每日上传限制；或者可能快照只是需要很长时间上传。使用“快照运行状况检查”解决常见问题。

端到端跟踪视图的异常窗格中有一个链接，可将你带到“快照运行状况检查”。

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

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

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

如果这样不能解决问题，请参阅以下手动故障排除步骤。

验证检测密钥

请确保在发布的应用程序中使用正确的检测密钥。通常，从 ApplicationInsights.config 文件中读取检测密钥。请验证该值是否与在门户中看到的 Application Insights 资源的检测密钥相同。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。转换为连接字符串，以利用新功能。

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

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

Snapshot Debugger 终结点需要 TLS 版本 1.2。 SSL 安全协议集是由 web.config 的 system.web 部分中的 httpRuntime targetFramework 值启用的规定之一。如果 httpRuntime targetFramework 为 4.5.2 或更低版本，则默认情况下不包含 TLS 1.2。

注意

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

若要检查设置，请打开 web.config 文件，然后找到 system.web 节。确保将 httpRuntime 的 targetFramework 设置为 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 设计用于生产环境。默认设置包括速率限制，以最大限度地减少对应用程序的影响。

但是，你可能会遇到与 Snapshot Debugger 关联的小型 CPU、内存和 I/O 开销，如以下方案所示。

在应用程序中引发异常时：

为问题类型创建签名，并确定是否创建快照只会增加较小的 CPU 和内存开销。
如果启用了取消优化，则对引发异常的方法重新启用 JIT 会产生开销。下次执行该方法时就会发生这种情况。根据方法的大小，CPU 时间可能介于 1 ms 到 100 ms 之间。

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

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

小型转储首先写入磁盘，磁盘空间量与原始进程的工作集大致相同。写入小型转储可能会导致读取内存时出现页面错误。

小型转储在上传过程中被压缩，这会消耗 Snapshot Uploader 进程的 CPU 和内存。 CPU、内存和磁盘开销与进程快照的大小成正比。 Snapshot Uploader 按顺序处理快照。

调用 TrackException 时：

Snapshot Debugger 会检查该异常是新异常，或者是否已为其创建快照。此过程只会增加较小的 CPU 开销。

.NET Core 预览版

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

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

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

注意

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

可以转到以下 url 来查看此扩展的“状态”页：https://{site-name}.scm.chinacloudsites.cn/DiagnosticServices

注意

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

此域与应用服务的 Kudu 管理站点相同。状态页将显示探查器和 Snapshot Collector 代理的安装状态。如果出现意外错误，它会显示如何进行修复。

你可以使用应用服务的 Kudu 管理站点获取此“状态”页的基 url：

在 Azure 门户中，打开应用服务应用程序。
选择“高级工具”或搜索 Kudu。
选择“转到”。
进入 Kudu 管理站点后，在 URL 中追加以下 /DiagnosticServices 并按 Enter。结尾如下所示：https://<kudu-url>/DiagnosticServices

升级到最新版本的 NuGet 包

根据 Snapshot Debugger 的启用方式，参阅以下选项：

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

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

检查上传程序日志

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

在 Azure 门户中，打开应用服务应用程序。
选择“高级工具”或搜索 Kudu。
选择“转到”。
在“调试控制台”下拉列表中，选择“CMD”。
选择“LogFiles”。

应至少看到一个名称以 Uploader_ 或 SnapshotUploader_ 开头，且扩展名为 .log 的文件。选择相应图标，下载任意日志文件或在浏览器中打开文件。文件名包括可标识应用程序服务实例的唯一后缀。如果应用程序服务实例托管于多台计算机上，则每台计算机都有单独的日志文件。当上传程序检测到新的小型转储文件时，会将其记录在日志文件中。下面是成功的快照和上传的示例：

SnapshotUploader.exe Information: 0 : Received Fork request ID 139e411a23934dc0b9ea08a626db16c5 from process 6368 (Low pri)
    DateTime=2018-03-09T01:42:41.8571711Z
SnapshotUploader.exe Information: 0 : Creating minidump from Fork request ID 139e411a23934dc0b9ea08a626db16c5 from process 6368 (Low pri)
    DateTime=2018-03-09T01:42:41.8571711Z
SnapshotUploader.exe Information: 0 : Dump placeholder file created: 139e411a23934dc0b9ea08a626db16c5.dm_
    DateTime=2018-03-09T01:42:41.8728496Z
SnapshotUploader.exe Information: 0 : Dump available 139e411a23934dc0b9ea08a626db16c5.dmp
    DateTime=2018-03-09T01:42:45.7525022Z
SnapshotUploader.exe Information: 0 : Successfully wrote minidump to D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp
    DateTime=2018-03-09T01:42:45.7681360Z
SnapshotUploader.exe Information: 0 : Uploading D:\local\Temp\Dumps\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.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\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.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\c12a605e73c44346a984e00000000000\139e411a23934dc0b9ea08a626db16c5.dmp
    DateTime=2018-03-09T01:42:59.8530649Z

注意

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

在之前的示例中，检测密钥是 c12a605e73c44346a984e00000000000。此值应与应用程序的检测密钥相匹配。小型转储与 ID 为 139e411a23934dc0b9ea08a626db16c5 的快照相关联。稍后可以使用此 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\c12a605e73c44346a984e00000000000\6368.pdbscan
    DateTime=2018-03-09T01:47:19.4614027Z

对于未托管于应用服务中的应用程序，上传程序日志与小型转储位于同一文件夹：%TEMP%\Dumps\<ikey>（其中 <ikey> 是检测密钥）。

云服务故障排除

在云服务中，默认临时文件夹可能太小，无法容纳小型转储文件，从而导致丢失快照。

所需的空间取决于应用程序的总工作集量和并发快照数。

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 错误，指出“上传程序无法启动”。

若要解决这些错误，可以通过 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": {
        "InstrumentationKey": "<your instrumentation key>"
    },
    "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 服务进行通信。

Application Insights Snapshot Debugger 使用的 IP 包含在 Azure Monitor 服务标记中。有关详细信息，请参阅服务标记文档。

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

特定于 Snapshot Debugger 的订阅不收取任何费用。所收集的快照文件与 Application Insights SDK 收集的遥测数据分开存储，并且快照引入或存储不收取任何费用。

通过