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

项目
06/24/2024

如果为应用程序启用了 Application Insights Snapshot Debugger，但看不到异常快照，则可以按照这些说明进行故障排除。

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

不支持的方案

可在下面找到不支持快照收集器的方案：

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

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

目前，唯一需要终结点修改的区域是Azure 政府和 Azure 中国。

对于使用 Application Insights SDK 的App 服务和应用程序，必须使用快照调试器支持的替代来更新连接字符串，定义如下：

连接字符串属性	美国政府云	中国云
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"
      }
    }
  }
}

使用快照运行状况检查

一些常见问题导致未显示“打开调试快照”。例如，使用过时的快照收集器;达到每日上传限制;或者上传快照可能需要很长时间。使用快照运行状况检查来排查常见问题。

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

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

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

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

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

验证检测密钥

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

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

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

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

Snapshot Debugger 终结点需要 TLS 版本 1.2。 SSL 安全协议集是由节中的值启用httpRuntime targetFramework的怪癖之一web.config。system.web 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 可用。但是，如果使用自己的虚拟机，可能需要在 OS 中启用 TLS 1.2。

.NET Core 的预览版本

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

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

如果快照调试器是通过门户中的 Application Insights 窗格启用的，则诊断服务站点扩展已启用该调试器。

注意

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

可以通过转到以下 URL 来检查此扩展的“状态”页：https://{site-name}.scm.azurewebsites.net/DiagnosticServices

注意

状态页链接的域因云而异。此域将与App 服务的 Kudu 管理站点相同。

此状态页显示探查器和快照收集器代理的安装状态。如果出现意外错误，将显示错误并显示如何修复此错误。

可以使用 kudu 管理站点App 服务获取此状态页的基 URL：

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

升级到 NuGet 包的最新版本

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

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

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

检查上传程序日志

创建快照后，在磁盘上创建一个小型转储文件 (.dmp) 。单独的上传程序进程创建该小型转储文件，并将其以及任何关联的 PDB 上传到 Application Insights Snapshot Debugger 存储。成功上传小型转储后，将从磁盘中删除。上传程序进程的日志文件保存在磁盘上。在App 服务环境中，可以在中找到D:\Home\LogFiles这些日志。使用 kudu 管理站点App 服务查找这些日志文件。

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

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

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

注意

上面的示例来自 NuGet 包的 Microsoft.ApplicationInsights.SnapshotCollector 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

对于未托管在 App 服务中的应用程序，上传程序日志与 minidumps 位于同一文件夹中： %TEMP%\Dumps\<ikey> (<ikey> 检测密钥) 。

排查云服务问题

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

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

32 位 ASP.NET Web 角色的工作集通常介于 200 MB 到 500 MB 之间。至少允许两个并发快照。

例如，如果应用程序使用 1 GB 的总工作集，则应确保至少有 2 GB 的磁盘空间来存储快照。

按照以下步骤使用快照的专用本地资源配置云服务角色。

通过编辑云服务定义 (.csdef) 文件，将新的本地资源添加到云服务。以下示例定义名为 SnapshotStore 的资源，其大小为 5 GB。
```
<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

如果找不到合适的文件夹，快照收集器将报告错误，指出“找不到合适的卷影副本文件夹”。

如果复制失败，快照收集器将报告错误 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 problemsApp 服务日志，以查看是否存在意外重启或未经处理的异常。

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

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

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

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。还可以向 Azure 反馈社区提交产品反馈。

通过