Application Insights JavaScript SDK 疑難解答

發行項
04/13/2024

本文討論如何針對涉及 Application Insights JavaScript SDK 的各種問題進行疑難解答。本文的主題包括 JavaScript Web 應用程式的 SDK 載入失敗和 JavaScript 應用程式的來源對應支援。

針對 JavaScript Web 應用程式的 SDK 載入失敗進行疑難解答

下列各節討論 JavaScript Web 應用程式特定 SDK 載入失敗案例的徵兆、原因和解決方案。

徵狀

<在您要監視的網頁前端>元素中，JavaScript 代碼段 (第 3 版或更新版本) 會在偵測到 SDK 腳本未下載或初始化時建立並報告下列例外狀況：

SDK 載入失敗：無法載入 Application Insights SDK 腳本 (如需詳細資訊，請參閱堆疊)

此訊息表示使用者的用戶端 (瀏覽器) 無法下載 Application Insights SDK 或從識別的主機頁面初始化。因此，您看不到任何遙測或事件。

注意事項

支援 API 或XMLHttpRequest的所有主要瀏覽器都支援fetch()此例外狀況。這些瀏覽器版本不包括 Microsoft Internet Explorer 8 和舊版。因此，除非您的環境包含擷取聚合填滿，否則這些瀏覽器不會報告這種類型的例外狀況。

堆疊詳細數據包含使用者正在使用之 URL 的基本資訊。

名稱	描述
<CDN 端點>	(和失敗的 URL) 下載 SDK。
<說明連結>	連結至此頁面 (疑難解答檔的 URL) 。
<主機 URL>	使用者正在使用之頁面的完整 URL。
<端點 URL>	用來報告例外狀況的 URL。此值有助於識別公用因特網或私人雲端是否已存取主控頁面。

下列清單包含發生此例外狀況的最常見原因：

間歇性網路連線失敗
Application Insights 內容傳遞網路 (CDN) 中斷
載入腳本之後的SDK初始化失敗
Application Insights JavaScript CDN 的封鎖

間歇性網路連線失敗是此例外狀況最常見的原因，特別是在行動漫遊案例中。

下列各節討論如何針對此錯誤的每個潛在根本原因進行疑難解答。

注意事項

其中一些步驟假設您的應用程式可以直接控制 Snippet <腳本/> 標籤及其在裝載 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 (未變更) 。若要檢閱網路流量，您也可以使用 Web 偵錯工具，例如 Fiddler。

如果 SDK 未成功下載，請檢閱下表以瞭解不同的報告選項。

案例	原因	動作
此問題只會影響少數使用者和特定瀏覽器版本或瀏覽器版本的子集。 (檢查所報告例外狀況的詳細數據。)	只有在特定使用者或環境要求您的應用程式提供額外的 `polyfill` 實作時，才會發生此問題。	在 GitHub 上提出問題。
此問題會影響整個應用程式和所有使用者。	這是與發行相關的問題。	建立新的支援票證。

如果 SDK 下載成功，請檢閱下列各節以協助修正 SDK 初始化問題。

步驟 2：檢查 JavaScript 例外狀況

檢查 JavaScript 例外狀況。使用支援開發人員工具的瀏覽器。選取 F12 以檢視開發人員工具、載入頁面，然後檢查是否發生任何例外狀況。例如，ai.2.min.js) 中的 SDK 腳本 (造成例外狀況嗎？在此情況下，會發生下列其中一個案例：

傳遞至 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 端點的擁有者應該使用將端點標示為不安全的封鎖清單實體。然後，封鎖清單實體可以從相關清單中移除端點。

請檢查下列因特網安全性網站，以瞭解其是否將CDN端點識別為不安全：

解決此問題可能需要很長的時間。使用者或公司 IT 部門可能必須強制更新或明確允許 CDN 端點。解決此問題所需的總時間取決於應用程式、防火牆或環境更新其清單本機複本所需的頻率。

如果 CDN 端點識別為不安全，請建立支援票證以儘快解決問題。

下列各節更明確地概述如何發生封鎖，以及如何修正封鎖。

原因 4a：使用者封鎖 (瀏覽器、已安裝的封鎖程式或個人防火牆)

檢查您的使用者是否已採取下列任何設定動作：

已安裝瀏覽器外掛程式 (通常以廣告、惡意代碼或快顯封鎖程式的形式)
封鎖或不允許其瀏覽器或 Proxy 中的 Application Insights CDN 端點
設定防火牆規則，以造成 SDK (CDN 網域的封鎖，或無法解析 DNS 專案)

解決方案 4a：新增 CDN 端點的封鎖清單例外狀況

如果您的使用者採取任何列出的設定動作，請與他們 (，或提供檔) 以允許CDN端點。

使用者可能已安裝使用公用封鎖清單的外掛程式。如果不是，則可能使用另一個手動設定的解決方案，或外掛程式使用私人網域封鎖清單。

告知使用者允許從 Application Insights CDN 端點下載腳本，方法是將端點包含在其瀏覽器的外掛程式或防火牆規則例外清單中。這些清單會根據用戶環境而有所不同。

以下是這種情況的範例，示範如何設定 Google Chrome 以允許或封鎖網站的存取。

原因 4b：公司防火牆封鎖

如果您的使用者是在公司網路上，則公司防火牆可能是CDN封鎖的來源。公司 IT 部門可能已實作某種形式的因特網篩選系統。

解決方案4b1：新增公司CDN端點的例外狀況

重要事項

您的使用者是否使用私人雲端，而且他們無法存取公用因特網？在此情況下，您必須使用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) ，讓您可以使用任何可用的錯誤修正和新功能。

解決方案 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 自動收集外掛程式時，下列遙測警告可能會出現在 Application Insights 活頁簿中：「按兩下沒有 parentId 值的事件數據列」。

原因

如果父系 HTML 元素中未指定父標識碼，就會發生此問題。此條件會導致在其所有父元素上觸發事件。

解決方案

若要修正此問題，請將或 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 community 支援。您也可以將產品意見反應提交給 Azure 意應見反社群。

Application Insights JavaScript SDK 疑難解答

針對 JavaScript Web 應用程式的 SDK 載入失敗進行疑難解答

徵狀

原因 1：間歇性網路連線失敗

解決方案 1a：下載 SDK 的更新版本

解決方案 1b：使用 npm 套件將 SDK 與應用程式一起內嵌在單一套件組合中

原因 2：Application Insights CDN 中斷

解決方案2：建立支援票證

原因 3：SDK 在載入腳本之後未初始化

解決方案 3：檢查 SDK 下載成功或 JavaScript 例外狀況，或啟用瀏覽器偵錯

步驟 1：檢查 SDK 下載是否成功

步驟 2：檢查 JavaScript 例外狀況

步驟 3：啟用瀏覽器控制台偵錯

原因 4：封鎖 Application Insights JavaScript CDN

原因 4a：使用者封鎖 (瀏覽器、已安裝的封鎖程式或個人防火牆)

解決方案 4a：新增 CDN 端點的封鎖清單例外狀況

原因 4b：公司防火牆封鎖

解決方案4b1：新增公司CDN端點的例外狀況

解決方案 4b2：在您自己的 CDN 上裝載 SDK

解決方案 4b3：使用 npm 套件內嵌 Application Insights SDK

針對 JavaScript 應用程式的來源對應支援進行疑難解答

修正「按兩下沒有parentId值的事件數據列」警告

原因

解決方案

後續步驟

與我們連絡，以取得說明

意見反應

意見反應

其他資源