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

项目
2025-04-21

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

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

不支持的方案

不支持 Snapshot Collector 的场景：

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

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

目前唯一需要修改终结点的区域是 Azure 政府和由世纪互联运行的 Microsoft Azure。

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

连接字符串属性	美国政府云	中国云
SnapshotEndpoint	`https://snapshot.monitor.azure.us`	`https://snapshot.monitor.azure.cn`

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

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

属性	美国政府云	中国云
AgentEndpoint	`https://snapshot.monitor.azure.us`	`https://snapshot.monitor.azure.cn`

使用美国政府云代理终结点更新的 host.json 示例：

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

使用快照运行状况检查

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

使用过期的 Snapshot Collector
达到每日上传限制
快照上传花了很长时间。

通过端到端跟踪视图的“异常”窗格中的链接，访问“快照运行状况检查”以排查常见问题。

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

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

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

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

检查 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.azurewebsites.net/DiagnosticServices

注意

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

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

你可以使用应用服务的 Kudu 管理站点获取此状态页面的基础 URL。

在 Azure 门户中，打开应用服务应用程序。
选择“高级工具”或搜索 Kudu。
选择Go。
进入 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 <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

对于未托管在应用服务中的应用程序，上传器日志与小型转储文件位于同一文件夹中：%TEMP%\Dumps\<string>（其中 <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 会报告错误，指出“找不到合适的影子副本文件夹。”

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

如果无法启动上传程序，则 Snapshot Collector 会报告错误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": {
        "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 服务进行通信。

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

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

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

排查“自带存储空间”(BYOS) 问题

排查配置 BYOS 时遇到的常见问题。

应用场景：`Template schema '{schema_uri}' isn't supported`

收到类似于以下示例的错误：

New-AzResourceGroupDeployment : 11:53:49 AM - Error: Code=InvalidTemplate; Message=Deployment template validation failed: 'Template schema
'https://schema.management.azure.com/schemas/2020-01-01/deploymentTemplate.json#' is not supported. Supported versions are
'2014-04-01-preview,2015-01-01,2018-05-01,2019-04-01,2019-08-01'. Please see https://aka.ms/arm-template for usage details.'.

解决方案

确保模板的 $schema 属性有效。它必须遵循此模式：

https://schema.management.azure.com/schemas/{schema_version}/deploymentTemplate.json#

确保模板的 schema_version 在有效值的范围内：2014-04-01-preview, 2015-01-01, 2018-05-01, 2019-04-01, 2019-08-01。

应用场景：`No registered resource provider found for _location '{_location}'`

收到类似于以下示例的错误：

New-AzResourceGroupDeployment : 6:18:03 PM - Resource microsoft.insights/components 'byos-test-westus2-ai' failed with message '{
  "error": {
    "code": "NoRegisteredProviderFound",
    "message": "No registered resource provider found for ___location 'westus2' and API version '2020-03-01-preview' for type 'components'. The supported api-versions are '2014-04-01,
2014-08-01, 2014-12-01-preview, 2015-05-01, 2018-05-01-preview'. The supported locations are ', eastus, southcentralus, northeurope, westeurope, southeastasia, westus2, uksouth,
canadacentral, centralindia, japaneast, australiaeast, koreacentral, francecentral, centralus, eastus2, eastasia, westus, southafricanorth, northcentralus, brazilsouth, switzerlandnorth,
australiasoutheast'."
  }
}'

解决方案

确保资源 apiVersion 的 microsoft.insights/components 为 2015-05-01。
确保资源 apiVersion 的 linkedStorageAccount 为 2020-03-01-preview。

场景：`Storage account _location should match Application Insights component _location`

收到类似于以下示例的错误：

New-AzResourceGroupDeployment : 1:01:12 PM - Resource microsoft.insights/components/linkedStorageAccounts 'byos-test-centralus-ai/serviceprofiler' failed with message '{
  "error": {
    "code": "BadRequest",
    "message": "Storage account ___location should match AI component ___location",
    "innererror": {
      "trace": [
        "System.ArgumentException"
      ]
    }
  }
}'

解决方案

确保 Application Insights 资源的位置与存储帐户的位置相同。

通过

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

不支持的方案

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

使用快照运行状况检查

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

Snapshot Debugger 开销方案

.NET Core 预览版

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

升级到最新版本的 NuGet 包

检查上传器日志

云服务疑难解答

重写影子副本文件夹

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

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

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

排查“自带存储空间”(BYOS) 问题

应用场景：Template schema '{schema_uri}' isn't supported

解决方案

应用场景：No registered resource provider found for ___location '{___location}'

解决方案

场景：Storage account ___location should match Application Insights component ___location

解决方案

反馈

其他资源

应用场景：`Template schema '{schema_uri}' isn't supported`

应用场景：`No registered resource provider found for _location '{_location}'`

场景：`Storage account _location should match Application Insights component _location`