Azure App Service 和 ASP.NET 的應用程式監視

發行項
06/03/2024

啟用監視在 Azure App Service 上執行的 ASP.NET 型 Web 應用程式現已十分簡單。先前，您需要手動檢測應用程式。現在，最新的延伸模組/代理程式已預設內建在 App Service 映像中。本文將逐步引導您啟用 Azure 監視器 Application Insights 監視功能，並提供自動化大規模部署程序的初步指引。

注意

已棄用透過 [開發工具]>[延伸模組] 手動新增 Application Insights 網站延伸模組。此延伸模組安裝方法相依於每個新版本的手動更新。延伸模組的最新穩定版本現在已預先安裝為 App Service 映像的一部分。這些檔案位於 d:\Program Files (x86)\SiteExtensions\ApplicationInsightsAgent，會隨著每個穩定版本自動更新。如果您遵循自動檢測指示來啟用監視，其會自動移除已取代的延伸模組。

如果同時偵測到自動檢測監視和手動 SDK 型檢測，則只會接受手動檢測設定。這樣的安排可防止傳送重複資料。若要深入了解，請參閱疑難排解一節。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。轉換至連接字串以利用新功能。

啟用自動檢測監視

如需支援自動檢測案例的完整清單，請參閱支援的環境、語言和資源提供者。

注意

不支援 APPINSIGHTS_JAVASCRIPT_ENABLED 和 urlCompression 的組合。如需詳細資訊，請參閱疑難排解一節中的說明。

在 Azure 控制台中，選取您應用程式服務的 [Application Insights]。接著選取 [啟用]。
選擇建立新的資源，或選取此應用程式現有的 Application Insights 資源。

注意

當您選取 [確定] 來建立新資源時，系統會提示您選取 [套用監視設定]。選取 [繼續] 會將新的 Application Insights 資源連結到應用程式服務。這樣做也會觸發重新啟動應用程式服務。

在指定要使用的資源之後，您可以選擇要如何讓 Application Insights 收集每個應用程式平台的資料。預設會在兩個不同的收集層級上開啟 ASP.NET 應用程式監視。

此螢幕快照顯示已選取 [建立新資源] 的 Application Insights 網站延伸模組頁面。

下表摘要說明針對每個路由收集的資料。

資料	ASP.NET 基本收集	ASP.NET 建議收集
新增 CPU、記憶體和 I/O 使用趨勢	No	Yes
收集使用趨勢，並啟用從可用性結果到交易的相互關聯	Yes	Yes
收集主機程序未處理的例外狀況	Yes	Yes
在使用取樣時，改善 APM 計量在負載下的精確度	Yes	Yes
將不同要求/相依性界限間的微服務相互關聯	否 (僅限單一執行個體 APM 功能)	Yes

若要設定取樣 (之前可以透過 applicationinsights.config 檔案控制)，您現在可以透過有對應前置詞 MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor 的應用程式設定與之互動。
- 例如，若要變更初始取樣百分比，您可以建立 MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_InitialSamplingPercentage 的應用程式設定，其值為 100。
- 若要停用取樣，請將 MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MinSamplingPercentage 的值設定為 100。
- 支援的設定包括：
  - MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_InitialSamplingPercentage
  - MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MinSamplingPercentage
  - MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_EvaluationInterval
  - MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MaxTelemetryItemsPerSecond
- 如需支援的調適型取樣遙測處理器設定和定義清單，請參閱程式碼和取樣文件。

啟用用戶端監視

用戶端監視是適用於 ASP.NET 的選用功能。若要啟用用戶端監視：

選取 [設定]>[組態]。
在 [應用程式設定] 下方，建立新的應用程式設定：
- 名稱：輸入 APPINSIGHTS_JAVASCRIPT_ENABLED。
- 值：輸入 true。
儲存設定並重新啟動您的應用程式。

若要停用用戶端監視，請從應用程式設定中移除相關的機碼值組，或將值設定為 false。

自動監視

若要透過 Application Insights 啟用遙測收集，只需要設定下列應用程式設定。

顯示 App Service 應用程式設定與 Application Insights 設定的螢幕快照。

應用程式設定定義

應用程式設定名稱	定義	值
ApplicationInsightsAgent_EXTENSION_VERSION	主要延伸模組，用於控制執行階段監視。	`~2`
XDT_MicrosoftApplicationInsights_Mode	在預設模式中只會啟用基本功能，以確保最佳效能。	`default` 或 `recommended`
InstrumentationEngine_EXTENSION_VERSION	控制是否將開啟二進位重寫引擎 `InstrumentationEngine`。此設定具有效能影響，且會影響冷啟動/啟動時間。	`~1`
XDT_MicrosoftApplicationInsights_BaseExtensions	控制 SQL 和 Azure 資料表文字是否會與相依性呼叫一起擷取。效能警告：應用程式冷啟動時間將受到影響。此設定需要 `InstrumentationEngine`。	`~1`

使用 Azure Resource Manager 的 App Service 應用程式設定

您可以使用 Azure Resource Manager 範本，來管理和設定 Azure App Service 的應用程式設定。當您使用 Resource Manager 自動化部署新的 App Service 資源，或修改現有資源的設定時，可以使用此方法。

App Service 資源的應用程式設定 JSON 基本結構：

      "resources": [
        {
          "name": "appsettings",
          "type": "config",
          "apiVersion": "2015-08-01",
          "dependsOn": [
            "[resourceId('Microsoft.Web/sites', variables('webSiteName'))]"
          ],
          "tags": {
            "displayName": "Application Insights Settings"
          },
          "properties": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      ]

如需已針對 Application Insights 設定應用程式設定的 Resource Manager 範本範例，此範本可能會有所幫助。具體而言，請查看第 238 行開始的區段。

自動建立 Application Insights 資源並連結到您新建立的 App Service 資源

若要使用預設 Application Insights 設定建立 Resource Manager 範本，請開始程式，就像您要建立已啟用 Application Insights 的新 Web 應用程式一樣。

使用您想要的 Web 應用程式資訊建立新的 App Service資源。在 [監視] 索引標籤上啟用 Application Insights。
選取 [檢閱 + 建立]。接著，選取 [下載自動化的範本]。

此選項會產生已設定所有必要設定的最新 Resource Manager 範本。

在下列範例中，將 AppMonitoredSite 的所有執行個體取代為您的網站名稱：

注意

如果使用 Windows，請將設定 ApplicationInsightsAgent_EXTENSION_VERSION 為 ~2。如果使用 Linux，請將設定 ApplicationInsightsAgent_EXTENSION_VERSION 為 ~3。

{
    "resources": [
        {
            "name": "[parameters('name')]",
            "type": "Microsoft.Web/sites",
            "properties": {
                "siteConfig": {
                    "appSettings": [
                        {
                            "name": "APPINSIGHTS_INSTRUMENTATIONKEY",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').InstrumentationKey]"
                        },
                        {
                            "name": "APPLICATIONINSIGHTS_CONNECTION_STRING",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').ConnectionString]"
                        },
                        {
                            "name": "ApplicationInsightsAgent_EXTENSION_VERSION",
                            "value": "~2"
                        }
                    ]
                },
                "name": "[parameters('name')]",
                "serverFarmId": "[concat('/subscriptions/', parameters('subscriptionId'),'/resourcegroups/', parameters('serverFarmResourceGroup'), '/providers/Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "dependsOn": [
                "[concat('Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "microsoft.insights/components/AppMonitoredSite"
            ],
            "apiVersion": "2016-03-01",
            "location": "[parameters('location')]"
        },
        {
            "apiVersion": "2016-09-01",
            "name": "[parameters('hostingPlanName')]",
            "type": "Microsoft.Web/serverfarms",
            "location": "[parameters('location')]",
            "properties": {
                "name": "[parameters('hostingPlanName')]",
                "workerSizeId": "[parameters('workerSize')]",
                "numberOfWorkers": "1",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "sku": {
                "Tier": "[parameters('sku')]",
                "Name": "[parameters('skuCode')]"
            }
        },
        {
            "apiVersion": "2015-05-01",
            "name": "AppMonitoredSite",
            "type": "microsoft.insights/components",
            "location": "West US 2",
            "properties": {
                "ApplicationId": "[parameters('name')]",
                "Request_Source": "IbizaWebAppExtensionCreate"
            }
        }
    ],
    "parameters": {
        "name": {
            "type": "string"
        },
        "hostingPlanName": {
            "type": "string"
        },
        "hostingEnvironment": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "sku": {
            "type": "string"
        },
        "skuCode": {
            "type": "string"
        },
        "workerSize": {
            "type": "string"
        },
        "serverFarmResourceGroup": {
            "type": "string"
        },
        "subscriptionId": {
            "type": "string"
        }
    },
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0"
}

透過 PowerShell 啟用

若要透過 PowerShell 啟用應用程式監視，只需變更底層應用程式設定。下列範例會針對資源群組 AppMonitoredRG 中，名為 AppMonitoredSite 的網站啟用應用程式監視。其會設定要傳送至 012345678-abcd-ef01-2345-6789abcd 檢測金鑰的資料。

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

注意

如果使用 Windows，請將 ApplicationInsightsAgent_EXTENSION_VERSION 設定為 ~2。如果使用 Linux，請將 ApplicationInsightsAgent_EXTENSION_VERSION 設定為 ~3。

$app = Get-AzWebApp -ResourceGroupName "AppMonitoredRG" -Name "AppMonitoredSite" -ErrorAction Stop
$newAppSettings = @{} # case-insensitive hash map
$app.SiteConfig.AppSettings | %{$newAppSettings[$_.Name] = $_.Value} # preserve non Application Insights application settings.
$newAppSettings["APPINSIGHTS_INSTRUMENTATIONKEY"] = "012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights instrumentation key
$newAppSettings["APPLICATIONINSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights connection string
$newAppSettings["ApplicationInsightsAgent_EXTENSION_VERSION"] = "~2"; # enable the ApplicationInsightsAgent
$app = Set-AzWebApp -AppSettings $newAppSettings -ResourceGroupName $app.ResourceGroup -Name $app.Name -ErrorAction Stop

升級監視延伸模組/代理程式：.NET

從 2.8.9 版和更新版本進行升級

從 2.8.9 版的升級會自動進行，無須執行任何其他動作。新的監視位元會在背景傳遞至目標應用程式服務。系統會在應用程式重新啟動時挑選這些監視位元。

若要確認您正在執行的擴充功能版本，請移至 https://yoursitename.scm.azurewebsites.net/ApplicationInsights。

此螢幕快照顯示用來檢查您所執行之延伸模組版本的 URL 路徑。

從 1.0.0 版至 2.6.5 版進行升級

從 2.8.9 版開始，會使用預先安裝的網站延伸模組。如果您是使用舊版，可以透過下列兩種方式之一進行更新：

透過入口網站啟用來升級：即使您已安裝 App Service 的 Application Insights 延伸模組， UI 仍只會顯示 [啟用] 按鈕。在幕後，系統將移除舊的私人網站延伸模組。
透過 PowerShell 升級：
1. 進行應用程式設定，來啟用預先安裝的網站延伸模組 ApplicationInsightsAgent。如需詳細資訊，請參閱透過 PowerShell 啟用。
2. 手動為 App Service 移除名為 Application Insights 延伸模組的私人網站延伸模組。

如果升級是在 2.5.1 之前的版本完成，請檢查 Application Insights DLL 是否已從應用程式 bin 資料夾中移除。如需詳細資訊，請參閱疑難排解一節中的步驟。

疑難排解

注意

當您在 App Service 中使用 ASP.NET 執行階段建立 Web 應用程式時，此項目會將單一靜態 HTML 頁面部署為入門網站。不建議針對預設範本的問題進行疑難排解。針對問題進行疑難排解之前，請先部署應用程式。

以下是延伸模組/代理程式型監視的逐步疑難排解指南，此指南適用於在 App Service 上執行的 ASP.NET 型應用程式。

檢查 ApplicationInsightsAgent_EXTENSION_VERSION 應用程式的設定是否設為 ~2 值。
瀏覽至 https://yoursitename.scm.azurewebsites.net/ApplicationInsights。
- 確認 Application Insights Extension Status 為 Pre-Installed Site Extension, version 2.8.x.xxxx 且正在執行中。
  
  如果未執行，請遵循啟用 Application Insights 監視的指示。
- 確認狀態來源存在並如下所示：Status source D:\home\LogFiles\ApplicationInsights\status\status_RD0003FF0317B6_4248_1.json。
  
  如果不存在類似值，表示應用程式目前未執行或不受支援。若要確保應用程式正在執行，請嘗試手動瀏覽應用程式 URL/應用程式端點，讓執行階段資訊可供使用。
- 確認 IKeyExists 為 true。如果不是，請將含有檢測金鑰 GUID 的 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 新增至應用程式設定。
- 確認 AppAlreadyInstrumented、AppContainsDiagnosticSourceAssembly 和 AppContainsAspNetTelemetryCorrelationAssembly 沒有項目。
  
  如果其中任一個項目存在，請從您的應用程式中移除下列套件：Microsoft.ApplicationInsights、System.Diagnostics.DiagnosticSource 和 Microsoft.AspNet.TelemetryCorrelation。

部署 Web 應用程式的預設網站不支援自動用戶端監視

當您在 App Service 中使用 ASP.NET 執行階段建立 Web 應用程式時，此項目會將單一靜態 HTML 頁面部署為入門網站。靜態網頁也會在 IIS 中載入 ASP.NET 受控網頁組件。此頁面可讓您測試無程式碼伺服器端監視，但不支援自動用戶端監視。

如果您想要在 App Service Web 應用程式中針對 ASP.NET 測試無程式碼伺服器和用戶端監視，建議您遵循官方指南來建立 ASP.NET Framework Web 應用程式。然後使用目前文章中的指示來啟用監視。

不支援 APPINSIGHTS_JAVASCRIPT_ENABLED 和 urlCompression

如果您在內容編碼的情況下使用 APPINSIGHTS_JAVASCRIPT_ENABLED=true，可能會收到如下的錯誤：

500 URL 重寫錯誤。
發生 500.53 URL 重寫模組錯誤，訊息為「當 HTTP 回應的內容已編碼 ('gzip') 時，無法套用輸出重寫規則」。

發生錯誤的原因是 APPINSIGHTS_JAVASCRIPT_ENABLED 應用程式設定設為 true，且同時存在內容編碼。這是尚不支援的案例。因應措施是從應用程式設定中移除 APPINSIGHTS_JAVASCRIPT_ENABLED。可惜的是，如果仍然需要用戶端/瀏覽器端 JavaScript 檢測，則您的網頁需要手動 SDK 參考。請遵循指示，使用 JavaScript SDK 進行手動檢測。

如需 Application Insights 代理程式/延伸模組的最新資訊，請參閱發行備註。

下列兩者間有何差異：Application Insights 標準計量與Azure App Service 計量？

Application Insights 會收集對應用程式提出要求的遙測。如果 WebApps/WebServer 中發生失敗，且要求未到達使用者應用程式，則 Application Insights 不會對其進行任何遙測。

Application Insights 所計算的 serverresponsetime 持續時間不一定符合 Web Apps 觀察到的伺服器回應時間。此行為是因為 Application Insights 僅會計算要求實際到達使用者應用程式的持續時間。如果要求在 WebServer 中停滯或排入佇列，則等候時間將納入 Web Apps 計量中，但不會納入 Application Insights 計量中。

測試應用程式主機與擷取服務之間的連線

應用程式深入剖析 SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。您可以使用來自 PowerShell 或 curl 命令的原始 REST 用戶端，測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線。請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

不支援 PHP 和 WordPress

不支援 PHP 和 WordPress 網站。目前沒有正式支援的 SDK/代理程式可監視上述工作負載的伺服器端。您可以使用 JavaScript SDK 將用戶端 JavaScript 新增至網頁，以在 PHP 或 WordPress 網站上手動檢測用戶端交易。

下表進一步詳細說明這些值代表的意義、其基礎原因和建議修正。

問題值	說明	Fix
`AppAlreadyInstrumented:true`	如果此值為 true，表示延伸模組偵測到 SDK 的某些層面已存在於應用程式中，而且會輪詢。可能是因為對 `System.Diagnostics.DiagnosticSource`、`Microsoft.AspNet.TelemetryCorrelation` 或 `Microsoft.ApplicationInsights` 的參考。	請移除該參考。依預設，特定 Visual Studio 範本會新增某些參考。舊版的 Visual Studio 可能會新增參考至 `Microsoft.ApplicationInsights`。
`AppAlreadyInstrumented:true`	此值也可能是先前部署的應用程式資料夾中有上述的 DLL 所致。	清除應用程式資料夾，以確保已移除這些 DLL。檢查本地應用程式的 bin 目錄，以及 App Service 資源上的 wwwroot 目錄。若要檢查 App Service Web 應用程式的 wwwroot 目錄，請選取 [進階工具 (Kudu)]>[偵錯主控台]>[CMD]>home\site\wwwroot。
`AppContainsAspNetTelemetryCorrelationAssembly: true`	此值指出延伸模組偵測到應用程式中 `Microsoft.AspNet.TelemetryCorrelation` 的參考，而且將會放棄。	移除參考。
`AppContainsDiagnosticSourceAssembly**:true`	此值指出延伸模組偵測到應用程式中 `System.Diagnostics.DiagnosticSource` 的參考，而且將會放棄。	針對 ASP.NET，移除參考。
`IKeyExists:false`	此值表示應用程式設定 `APPINSIGHTS_INSTRUMENTATIONKEY` 中沒有檢測金鑰。可能的原因可能是不小心移除了值，或忘記在自動化指令碼中設定值。	請確定設定存在於 App Service 應用程式設定中。

System.IO.FileNotFoundException after 2.8.44 upgrade

2.8.44 版的自動檢測會將 Application Insights SDK 升級至 2.20.0。 Application Insights SDK 會透過 System.Diagnostics.DiagnosticSource.dll 間接參考 System.Runtime.CompilerServices.Unsafe.dll。如果應用程式有 System.Runtime.CompilerServices.Unsafe.dll 的繫結重新導向，而且如果應用程式資料夾中未顯示此程式庫，則可能會擲回 System.IO.FileNotFoundException。

若要解決此問題，請從 web.config 檔案中移除 System.Runtime.CompilerServices.Unsafe.dll 的繫結重新導向項目。如果應用程式想要使用 System.Runtime.CompilerServices.Unsafe.dll，請設定繫結重新導向，如下所示：

<dependentAssembly>
	<assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
	<bindingRedirect oldVersion="0.0.0.0-4.0.4.1" newVersion="4.0.4.1" />
</dependentAssembly>

暫時的因應措施是您可以將應用程式設定 ApplicationInsightsAgent_EXTENSION_VERSION 設定為 2.8.37 的值。此設定會觸發 App Service 使用舊的 Application Insights 延伸模組。暫時降低風險只是過渡解決辦法。

版本資訊

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

下一步

在即時應用程式上執行分析工具。
使用 Application Insights 監視 Azure Functions。
能夠讓 Azure 診斷傳送至 Application Insights。
監視服務健康狀態計量，確保您的服務可用且回應正常。
每當發生作業事件或計量超過臨界值時，接收警示通知。
使用 JavaScript 應用程式和網頁適用的 Application Insights，以從造訪網頁的瀏覽器取得用戶端遙測。
可用性概觀

共用方式為