Application Insights JavaScript SDK 故障排除

项目
04/13/2024

本文讨论如何排查涉及 Application Insights JavaScript SDK 的各种问题。本文的主题包括 JavaScript Web 应用的 SDK 加载失败和 JavaScript 应用的源映射支持。

排查 JavaScript Web 应用的 SDK 加载失败问题

以下部分讨论 JavaScript Web 应用的特定 SDK 加载失败方案的症状、原因和解决方案。

症状

在 <要监视的网页的头> 元素中， (版本 3 或更高版本的 JavaScript 代码片段) 创建，并在检测到 SDK 脚本未下载或初始化时报告以下异常：

SDK 加载失败：无法加载 Application Insights SDK 脚本 (请参阅堆栈了解详细信息)

此消息指示用户的客户端 (浏览器) 无法从标识的托管页下载 Application Insights SDK 或初始化。因此，看不到任何遥测或事件。

注意

支持 API 或 XMLHttpRequest的所有主要浏览器都支持此fetch()异常。这些浏览器版本不包括 Microsoft Internet Explorer 8 及更早版本。因此，除非你的环境包含提取 polyfill，否则这些浏览器不会报告这种类型的异常。

堆栈详细信息包括有关用户正在使用的 URL 的基本信息。

名称	说明
<CDN 终结点>	(使用的 URL，) 下载 SDK 失败。
<帮助链接>	指向此页面) (故障排除文档的链接的 URL。
<主机 URL>	用户正在使用的页面的完整 URL。
<端点 URL>	用于报告异常的 URL。此值可能有助于确定公共 Internet 或私有云是否访问了托管页。

以下列表包含发生此异常的最常见原因：

间歇性网络连接故障
Application Insights 内容分发网络 (CDN) 中断
加载脚本后 SDK 初始化失败
Application Insights JavaScript CDN 的阻塞

间歇性网络连接故障是导致此异常的最常见原因，尤其是在移动漫游方案中。

以下部分讨论如何排查此错误的每个潜在根本原因。

注意

其中一些步骤假定应用程序可以直接控制代码段 <脚本/> 标记及其作为托管 HTML 页的一部分返回的配置。如果这些条件不适用于你的方案，则这些步骤也不适用。

原因 1：间歇性网络连接失败

如果用户遇到间歇性的网络连接故障，则可能的解决方案比其他原因要少。但是，此故障通常会很快自行解决。例如，如果用户刷新页面以重新加载站点，文件最终会下载并缓存在本地，直到发布更新的版本。

解决方案 1a：下载 SDK 的更新版本

为了尽量减少间歇性网络连接故障，我们在所有 CDN 文件上实现了 Cache-Control 标头。用户的浏览器下载当前版本的 SDK 后，无需再次下载它，因为它会重复使用以前获取的副本。 (查看缓存的工作原理。) 如果缓存检查失败或有新版本可用，则用户的浏览器必须下载更新的版本。因此，你可能会在检查故障方案中看到“干扰”的背景级别。或者，当新版本发生并正式发布时，你可能会看到临时高峰， (部署到 CDN) 。

解决方案 1b：使用 npm 包将 SDK 与应用程序一起嵌入到单个捆绑包中

SDK 加载失败异常是否持续存在，是否对许多用户发生，同时减少了正常的客户端遥测数据？在这种情况下，间歇性网络连接问题可能不是问题的真正原因，你应该探索其他可能的原因。

注意

针对多个用户发生此故障的一个常见指示是，异常以快速且持续的速度报告。

在这种情况下，在自己的 CDN 上托管 SDK 不太可能提供或减少此异常的发生。相同的问题会影响你自己的 CDN，如果通过 npm 包解决方案使用 SDK，也会发生这种情况。如果 Application Insights 包含在与受监视的应用程序捆绑包不同的捆绑包中，则会出现后一种情况的故障，因为保证故障至少发生在其中一个捆绑包中。从用户的角度来看，发生此异常时，整个应用程序无法加载或初始化，而不仅仅是用户看不到) 的遥测 SDK (。因此，用户可能会继续刷新你的站点，直到它完全加载。

可以尝试使用 npm 包将 Application Insights SDK 与受监视的应用程序一起嵌入到单个捆绑包中。尽管这种情况可能仍会发生间歇性故障，但组合捆绑包确实提供了解决问题的真正机会。

原因 2：Application Insights CDN 中断

若要验证是否存在 Application Insights CDN 中断，请尝试直接从浏览器（而不是用户的位置）访问 CDN 终结点。例如，可以尝试从自己的开发计算机进行访问 https://js.monitor.azure.com/scripts/b/ai.2.min.js 。 (这假定组织未阻止此域。)

解决方案 2：创建支持票证

如果验证是否存在中断，则可以创建新的支持票证。

原因 3：加载脚本后 SDK 未初始化

如果 SDK 未初始化，脚本 </> 仍会从 CDN 成功下载，但在初始化期间失败。发生此失败的原因是缺少或无效的依赖项，或者由于某种形式的 JavaScript 异常。

解决方案 3：检查 SDK 下载成功或 JavaScript 异常，或启用浏览器调试

步骤 1：检查 SDK 下载是否成功

检查 SDK 是否已成功下载。如果未发生脚本下载，则此方案不是 SDK 加载失败异常的原因。使用支持开发人员工具的浏览器。选择 F12 以查看开发人员工具，然后选择“ 网络 ”选项卡。验证是否已下载 src 代码片段配置中定义的脚本。为此，检查响应代码 200 (成功) 或 304 (未更改) 。若要查看网络流量，还可以使用 Fiddler 等 Web 调试工具。

如果 SDK 未成功下载，请查看下表以了解不同的报告选项。

应用场景	原因	操作
此问题仅影响少数用户和特定浏览器版本或浏览器版本的子集。 (检查报告异常的详细信息。)	仅当特定用户或环境要求应用程序提供额外的 `polyfill` 实现时，问题才有可能。	在 GitHub 上提交问题。
此问题会影响整个应用程序和所有用户。	这是与发布相关的问题。	创建新的支持票证。

如果 SDK 下载成功，请查看以下部分以帮助解决 SDK 初始化问题。

步骤 2：检查 JavaScript 异常

检查 JavaScript 异常。使用支持开发人员工具的浏览器。选择 F12 以查看开发人员工具，加载页面，然后检查是否发生任何异常。 SDK 脚本是否 (例如， ai.2.min.js) 会导致异常？在这种情况下，会发生以下情况之一：

传递给 SDK 的配置包含意外的配置。
传递给 SDK 的配置缺少所需的配置。
已将错误的版本部署到 CDN。

若要检查错误的配置，请更改传递到代码片段 (的配置（如果尚未执行此操作) 以便它仅包含检测密钥作为字符串值）。以下代码显示了一个示例代码片段配置更改。

注意

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

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "<instrumentation-key-guid>"
}});
</script>

使用此最小配置时，如果在 SDK 脚本中仍看到 JavaScript 异常，请创建新的支持票证。若要解决此问题，必须回滚错误的生成。这是因为新部署的版本可能是问题的原因。

如果异常消失，则类型不匹配或意外值可能会导致问题。通过逐个还原配置选项开始故障排除，并在每次更改后进行测试，直到再次出现异常。接下来，检查导致问题的项的文档。如果文档不明确或需要帮助，请在 GitHub 上提出问题。

你的配置以前是否已部署并正常工作，但现在是否报告了此异常？在这种情况下，可能存在影响新部署版本的问题。检查异常是否仅影响一小部分用户或浏览器。在 GitHub 上提交问题或创建新的支持票证。

步骤 3：启用浏览器控制台调试

如果未引发异常，则应通过将 loggingLevelConsole 设置添加到配置来启用控制台调试，如以下代码片段配置示例所示。此更改会将所有初始化错误和警告发送到浏览器的控制台。 (若要查看浏览器控制台，请选择 F12 打开开发人员工具，然后选择“ 控制台 ”选项卡。) 任何报告的错误都应是一目了然的。如果需要进一步的帮助，请在 GitHub 上提出问题。

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "<instrumentation-key-guid>",
    loggingLevelConsole: 2
}});
</script>

注意

在初始化期间，SDK 对已知的主要依赖项执行一些基本检查。如果当前运行时未提供这些检查，则运行时会将失败作为警告消息报告给控制台 (但仅当 loggingLevelConsole 设置值大于零) 时。

如果 SDK 仍无法初始化，请尝试启用 enableDebug 配置设置。进行此更改后，所有内部错误都将作为异常引发。这会导致遥测丢失。由于此设置仅适用于开发人员，因此它可能会导致由于内部检查而引发更多异常。查看每个异常以确定哪个问题导致 SDK 失败。通过将文件扩展名从 . min.js更改为仅 .js) ，使用脚本 (的未缩小版本。否则，异常不可读。以下代码显示了示例代码片段配置更改。

警告

不应在完整的生产环境中启用此仅限开发人员的设置，因为这样做会导致丢失遥测数据。

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
    instrumentationKey: "<instrumentation-key-guid>",
    enableDebug: true
}});
</script>

如果此操作仍不提供任何见解，则应通过提供详细信息和示例网站（如果使用）在 GitHub 上提交问题。包括浏览器版本、操作系统和 JavaScript 框架详细信息，以帮助识别问题。

原因 4：Application Insights JavaScript CDN 阻塞

如果 Application Insights JavaScript SDK CDN 终结点报告或标识为不安全，则可能是 CDN 阻塞。在这种情况下，终结点已公开阻止列表，这些列表的使用者开始阻止所有访问。

若要解决此问题，CDN 终结点的所有者应使用将终结点标记为不安全的阻止列表实体。然后，阻止列表实体可以从相关列表中删除终结点。

检查以下 Internet 安全网站，了解它们是否将 CDN 终结点标识为不安全：

解决此问题可能需要很长时间。用户或公司 IT 部门可能必须强制更新或显式允许 CDN 终结点。解决此问题所需的总时间量取决于应用程序、防火墙或环境更新其本地列表副本所需的频率。

如果 CDN 终结点被标识为不安全，请创建支持票证以尽快解决问题。

以下部分更具体地概述了如何发生阻塞以及如何修复阻塞。

原因 4a：用户阻塞 (浏览器、已安装的阻止程序或个人防火墙)

检查用户是否已执行以下任何配置操作：

通常以广告、恶意软件或弹出窗口阻止程序的形式安装浏览器插件 ()
在其浏览器或代理中阻止或禁止 Application Insights CDN 终结点
配置了一个防火墙规则，该规则会导致 SDK (的 CDN 域阻塞或无法解析 DNS 条目)

解决方案 4a：为 CDN 终结点添加阻止列表异常

如果用户执行了列出的任何配置操作，请 (或提供文档) 以允许 CDN 终结点。

用户可能安装了使用公共阻止列表的插件。否则，它们可能使用的是另一个手动配置的解决方案，或者插件使用的是专用域阻止列表。

告知用户允许从 Application Insights CDN 终结点下载脚本，方法是将终结点包含在浏览器的插件或防火墙规则例外列表中。这些列表因用户环境而异。

下面是这种情况的示例，演示如何将 Google Chrome 配置为允许或阻止访问网站。

原因 4b：企业防火墙阻塞

如果用户位于公司网络上，则公司防火墙可能是 CDN 阻塞的来源。企业 IT 部门可能已实施某种形式的 Internet 筛选系统。

解决方案 4b1：为公司添加 CDN 终结点例外

重要

用户是否使用私有云，以及他们是否无法访问公共 Internet？在这种情况下，必须使用 Application Insights npm 包嵌入 SDK，或者在自己的 CDN 上托管 Application Insights SDK。

请与公司的 IT 部门协作，为用户提供必要的规则。此解决方案类似于为用户添加例外。让 IT 部门配置 Application Insights CDN 终结点以供下载，方法是在任何域阻止列表或允许列表服务中包含 (或删除这些终结点) 。

解决方案 4b2：在自己的 CDN 上托管 SDK

可以在自己的 CDN 终结点上托管 Application Insights SDK，而不是让用户从公共 CDN 下载 Application Insights SDK。建议使用特定版本 (ai.2.#.#.min.js sdk) ，以便更轻松地识别你正在使用的版本。此外，请定期将 SDK 更新到当前版本 (ai.2.min.js) ，以便可以使用任何可用的 bug 修复和新功能。

解决方案 4b3：使用 npm 包嵌入 Application Insights SDK

可以使用 npm 包将 SDK 作为自己的 JavaScript 文件的一部分包含，而不是使用代码片段和添加公共 CDN 终结点。 SDK 只是你自己的脚本中的另一个包。有关详细信息，请参阅 Application Insights JavaScript SDK GitHub 页的基于 npm 的设置部分。

注意

建议在使用 npm 包时，还应使用某种形式的 JavaScript 捆绑程序来帮助执行代码拆分和缩小。

与代码片段一样，此处显示的相同阻塞性问题可能会影响自己的脚本， (是否使用 SDK npm 包) 。根据应用程序、用户和框架，可以考虑实现类似于代码片段中的逻辑的内容来检测和报告这些问题。

对 JavaScript 应用程序的源映射支持进行故障排除

下表说明了某些涉及 JavaScript 应用程序的源映射支持的问题，并提供了帮助解决这些问题的策略。

问题	说明
在 Blob 容器上) 设置 (Azure RBAC 所需的 Azure 基于角色的访问控制	必须至少为门户中使用此功能的任何用户分配 Blob 容器的存储 Blob 数据读取者角色。必须将此角色分配给想要通过此功能使用源映射的任何人。根据容器的创建方式，此角色可能尚未自动分配给你或你的团队。
找不到源映射	若要解决此问题，请执行下列操作：验证相应的源映射是否已上传到正确的 Blob 容器。验证源映射文件是否从映射到的 JavaScript 文件中获取其名称，以及它的文件扩展名是否为 .map 。例如， /static/js/main.4e2ca5fa.chunk.js 搜索名为 main.4e2ca5fa.chunk.js.map 的 blob。检查浏览器的控制台，了解它是否记录了任何错误。将此输出包含在任何支持票证中。

问题

说明

在 Blob 容器上) 设置 (Azure RBAC 所需的 Azure 基于角色的访问控制

必须至少为门户中使用此功能的任何用户分配 Blob 容器的存储 Blob 数据读取者角色。必须将此角色分配给想要通过此功能使用源映射的任何人。根据容器的创建方式，此角色可能尚未自动分配给你或你的团队。

找不到源映射

若要解决此问题，请执行下列操作：

验证相应的源映射是否已上传到正确的 Blob 容器。
验证源映射文件是否从映射到的 JavaScript 文件中获取其名称，以及它的文件扩展名是否为 .map 。例如， /static/js/main.4e2ca5fa.chunk.js 搜索名为 main.4e2ca5fa.chunk.js.map 的 blob。
检查浏览器的控制台，了解它是否记录了任何错误。将此输出包含在任何支持票证中。

修复了“单击没有 parentId 值的事件行”警告

在应用程序中使用 Application Insights 和 Click Analytics 自动收集插件时，应用程序见解工作簿中可能会出现以下遥测警告：“单击没有 parentId 值的事件行。

原因

如果未在父 HTML 元素中指定父 ID，则可能会出现此问题。此条件会导致在其所有父元素上触发事件。

解决方案

若要解决此问题，请将或 data-<customPrefix>-parentid 属性添加到data-parentid父 HTML 元素。下面是 HTML 代码的示例：

<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">

后续步骤

第三方信息免责声明

本文中提到的第三方产品由 Microsoft 以外的其他公司提供。 Microsoft 不对这些产品的性能或可靠性提供任何明示或暗示性担保。

联系我们寻求帮助

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