針對啟用 Application Insights 快照偵錯工具或檢視快照集的問題進行疑難排解

2025-04-22

如果您為應用程式啟用 Application Insights 快照偵錯工具，但看不到例外狀況的快照集，您可以使用這些指示進行疑難排解。

快照產生由於許多不同的原因而失敗。您可以從執行快照集健康情況檢查開始，以識別一些可能的常見原因。

不支援的案例

不支援 Snapshot Collector（快照集收集器）的情況：

狀況	副作用	建議
在您的應用程式中直接使用快照集收集器 SDK (.csproj)，並已啟用進階選項 Interop 時。	本機 Application Insights SDK (包括 Snapshot Collector 遙測資料) 會遺失，因此不會提供快照集。您的應用程式可能會在啟動時當機，並顯示 `System.ArgumentException: telemetryProcessorTypedoes not implement ITelemetryProcessor`。如需 Application Insights 功能 Interop 的詳細資訊，請參閱檔。	如果您使用進階選項 Interop，請使用無程式碼 Snapshot Collector 插入 (透過 Azure 入口網站啟用)。

請確定您使用適當的快照調試程式端點

目前，唯一需要端點修改的區域是 Azure Government 和由 21Vianet 運作的 Microsoft Azure。

針對使用 Application Insights SDK 的 App Service 和應用程式，您必須使用快照偵錯工具支援的覆寫來更新連接字串：

連接字串屬性	美國政府雲端	中國雲端
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 App 服務或 IIS 中，您的應用程式可能會因為缺少 SSL 安全性通訊協定而無法連線到快照調試程式服務。

快照偵錯工具端點需要 TLS 版本 1.2。 SSL 安全性通訊協定集是由 httpRuntime targetFramework 的 system.web 區段中的 web.config 值所啟用的巧合之一。

如果 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 App Service 中，可以使用 TLS 1.2。不過，如果您使用自己的虛擬機器，可能需要在 OS 中啟用 TLS 1.2。

快照偵錯工具額外負荷案例

快照偵錯工具是專為在生產環境中使用而設計。預設設定包含速率限制，以將對您應用程式的影響降到最低。

不過，您可能會遇到與快照偵錯工具相關聯的小型 CPU、記憶體和 I/O 額外負荷，例如下列案例。

當您的應用程式拋出例外情況時：

為問題類型建立簽章，而決定是否建立快照集會增加很小的 CPU 和記憶體額外負荷。
如果啟用取消最佳化，重新 JIT 擲回例外狀況的方法會有額外負荷。這是下一次方法執行時所產生的。根據方法的大小，它可以介於 1 毫秒到 100 毫秒的 CPU 時間之間。

如果例外狀況處理常式決定建立快照集：

建立進程快照集大約需要半秒（P50 = 0.3 秒、P90 = 1.2 秒、P95 = 1.9 秒），在此期間，擲回例外狀況的線程會暫停。不會封鎖其他線程。
將程序快照集轉換成小型傾印，並將其上傳至 Application Insights 需要幾分鐘的時間。
- 轉換：P50 = 63 秒、P90 = 187 秒、P95 = 275 秒。
- 上傳：P50 = 31 秒、P90 = 75 秒、P95 = 98 秒。
這會在快照上傳程式中完成，該程式在不同的程序中執行。快照集上傳程式程序會以低於一般 CPU 優先順序執行，並使用低優先順序 I/O。

小型傾印會先寫入磁碟，且磁碟空間量大致與原始程序的工作集相同。寫入小型傾印會在讀取記憶體時引發頁面錯誤。

小型傾印檔案會在上傳期間進行壓縮，這會在快照上傳程式中耗用 CPU 和記憶體。 CPU、記憶體和磁碟額外負荷會與進程快照集的大小成正比。快照集上傳程式會以序列方式處理快照集。

呼叫 TrackException 時：

快照調試程式會檢查例外狀況是否為新的，或是否已為其建立快照集。這會增加少量的CPU額外負荷。

.NET Core 的預覽版本

如果您使用 .NET Core 的預覽版本，或應用程式參考 Application Insights SDK (直接或間接透過相依組件)，請遵循啟用其他環境的快照偵錯工具的指示。

檢查診斷服務網站延伸模組的狀態頁面

如果快照偵錯工具是透過入口網站中的 Application Insights 窗格啟用，就是由診斷服務網站延伸模組啟用。

附註

Application Insights 快照偵錯工具的無程式碼安裝會遵循 .NET Core 支援原則。如需支援執行階段的詳細資訊，請參閱 .NET Core 支援原則。

您可以移至下列 URL 來檢查這個延伸模組的 [狀態頁面]：https://{site-name}.scm.azurewebsites.net/DiagnosticServices

附註

狀態頁面連結的網域會根據雲端而有所不同。

此網域會與 App Service 的 Kudu 管理網站相同。狀態頁面會顯示 .NET Profiler 和快照集收集器代理程式的安裝狀態。如果發生未預期的錯誤，則會示範如何修正錯誤。

您可以使用適用於 App Service 的 Kudu 管理網站來取得此 [狀態頁面] 的基底 URL：

在 Azure 入口網站中開啟您的 App Service 應用程式。
選取 [進階工具]，或搜尋 Kudu。
選取 [執行]。
您進入 Kudu 管理網站後，請在 URL 中附加下列 /DiagnosticServices，然後按 Enter。其結尾如下： https://<kudu-url>/DiagnosticServices

升級至最新版本的 NuGet 套件

根據快照偵錯工具啟用的方式，請參閱下列選項：

如果快照偵錯工具是透過入口網站中的 Application Insights 窗格啟用，則您的應用程式應該已執行最新的 NuGet 套件。
如果是透過包含 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件來啟用快照偵錯工具，請使用 Visual Studio 的 NuGet 套件管理員，以確定您使用的是最新版本的 Microsoft.ApplicationInsights.SnapshotCollector。

如需最新的更新和錯誤修正，請參閱版本資訊。

請檢查上傳器記錄

建立快照集之後，磁碟上會建立小型傾印檔案 (.dmp)。獨立的上傳程式會建立該迷你轉儲檔案，並將其連同任何相關聯的 PDB 一同上傳至 Application Insights 快照偵錯工具儲存體。成功上傳小型傾印之後，它就會從磁碟中刪除。上傳程式處理序的記錄檔會保留在磁碟上。在 App Service 環境中，您可以在 D:\Home\LogFiles 中找到這些記錄。使用 App Service 的 Kudu 管理網站來尋找這些記錄檔。

在 Azure 入口網站中開啟您的 App Service 應用程式。
選取 [進階工具]，或搜尋 Kudu。
選取 [執行]。
在 [偵錯主控台] 下拉式清單中，選取 [CMD]。
選取 記錄檔。

您應會看到至少有一個檔案的名稱開頭為 Uploader_ 或 SnapshotUploader_ 且副檔名為 .log。選取適當的圖示，以下載任何記錄檔，或在瀏覽器中開啟它們。檔案名稱包含可識別 App Service 執行個體的唯一尾碼。如果 App Service 執行個體裝載於一部以上的電腦，每部電腦會有個別的記錄檔。當上傳程式偵測到新的小型傾印檔案時，該檔案會記錄在記錄檔中。這是一個成功快照和上傳的範例︰

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

附註

上述範例來自 NuGet 套件 1.2.0 版 Microsoft.ApplicationInsights.SnapshotCollector 。在較舊的版本中，上傳程式程序稱為 MinidumpUploader.exe，且記錄較不詳細。

在上一個範例中，連接字串應該符合應用程式的連接字串。小型傾印會與具有要求識別碼的快照集相關聯。您稍後可以使用這個識別碼，在 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

對於未載入於 App Service 中的應用程式，上傳程式記錄檔位於與minidumps 相同的資料夾中： %TEMP%\Dumps\<string> （其中 <string> 是您的連接字串）。

針對雲端服務進行疑難排解

在雲端服務中，預設暫存資料夾可能太小，無法保存小型傾印檔案，進而導致遺失快照集。所需的空間取決於您應用程式的總工作集以及並行快照集數目。

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": {
        "ConnectionString": "<your connection string>"
    },
    "SnapshotCollectorConfiguration": {
        "ShadowCopyFolder": "D:\\SnapshotUploader"
    }
}

使用 Application Insights 搜尋來尋找含有快照的例外狀況

建立快照集後，擲回中的例外狀況會以快照集識別碼標記。向 Application Insights 回報例外狀況後，該快照集識別碼就會包含為自訂屬性。在 Application Insights 中使用搜尋，您可以找到具有 ai.snapshot.id 自訂屬性的所有記錄。

在 Azure 入口網站中瀏覽至您的 Application Insights 資源。
選取搜尋。
在 [搜尋] 文字方塊中輸入 ai.snapshot.id，然後按 Enter 鍵。

如果此搜尋未傳回任何結果，就不會在選取的時間範圍內向 Application Insights 報告快照。

若要搜尋從上傳程式記錄中的特定快照集識別碼，請在 [搜尋] 方塊中輸入該識別碼。如果您找不到已上傳快照集的記錄，請遵循下列步驟：

請驗證連接字串，仔細檢查您查看的是正確的 Application Insights 資源。
使用上傳程式記錄中的時間戳記，調整搜尋的時間範圍篩選條件以涵蓋該時間範圍。

如果仍未看到具有該快照集識別碼的例外狀況，則未向 Application Insights 回報此例外狀況記錄。如果您的應用程式在採用快照集之後，但回報例外狀況記錄之前損毀，可能會發生這種情況。在此情況下，檢查 Diagnose and solve problems 之下的 App Service 記錄，查看是否發生非預期的重新啟動或未處理的例外狀況。

編輯網路 Proxy 或防火牆規則

如果應用程式透過 Proxy 或防火牆連線至網際網路，您可能需要更新規則，以與快照集偵錯工具服務進行通訊。

Application Insights 快照偵錯工具所使用的 IP 包含在 Azure 監視器服務標籤中。如需詳細資訊，請參閱服務標籤文件。

使用快照集時是否有任何計費成本?

快照偵錯工具專屬的訂用帳戶不會有任何費用。所收集的快照集檔案會與 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 快照偵錯工具或檢視快照集的問題進行疑難排解

不支援的案例

請確定您使用適當的快照調試程式端點

使用快照集健康情況檢查

檢查 TLS/SSL 用戶端設定 (ASP.NET)

快照偵錯工具額外負荷案例

.NET Core 的預覽版本

檢查診斷服務網站延伸模組的狀態頁面

升級至最新版本的 NuGet 套件

請檢查上傳器記錄

針對雲端服務進行疑難排解

覆寫陰影複製資料夾

使用 Application Insights 搜尋來尋找含有快照的例外狀況

編輯網路 Proxy 或防火牆規則

使用快照集時是否有任何計費成本?

針對「自備儲存體 (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`