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

發行項
06/03/2024

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

注意

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

啟用自動檢測監視

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

Windows
Linux

重要

Windows 上僅支援 .NET Core 長期支援。

不支援修剪獨立式部署。請改為透過程式碼使用手動檢測。

注意

自動檢測在 2021 年 10 月之前稱為「無程式碼附加」。

請參閱下方的啟用監視章節，以開始使用 App Service 資源設定 Application Insights。

啟用監視

在 App Service 的左窗格中選取 [Application Insights]。接著選取 [啟用]。
建立新的資源，或選取此應用程式現有的 Application Insights 資源。

注意

當您選取 [確定] 來建立新資源時，系統會提示您 [套用監視設定]。選取 [繼續] 會將新的 Application Insights 資源連結到應用程式服務。應用程式服務接著會重新啟動。
在指定要使用的資源之後，您可以選擇要如何讓 Application Insights 收集每個應用程式平台的資料。 ASP.NET Core 集合選項為建議或停用。

啟用用戶端監視

使用 [建議] 收集的 ASP.NET Core 應用程式會依預設啟用用戶端監視，無論應用程式設定 APPINSIGHTS_JAVASCRIPT_ENABLED 是否存在。

如果您想要停用用戶端監視：

選取 [設定]>[組態]。
在 [應用程式設定] 底下，使用下列資訊建立 [新增應用程式設定]：
- 名稱：APPINSIGHTS_JAVASCRIPT_ENABLED
- 值：false
儲存設定。重新啟動您的應用程式。

自動監視

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

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

應用程式設定定義

應用程式設定名稱	定義	值
ApplicationInsightsAgent_EXTENSION_VERSION	主要延伸模組，用於控制執行階段監視。	`~2` 適用於 Windows 或 `~3` Linux
XDT_MicrosoftApplicationInsights_Mode	在預設模式中只會啟用基本功能，以確保最佳效能。	`disabled` 或 `recommended`。
XDT_MicrosoftApplicationInsights_PreemptSdk	僅適用於 ASP.NET Core 應用程式。透過 Application Insights SDK 啟用 Interop (交換操作)。將延伸模組與 SDK 並排載入，並使用其來傳送遙測。 (停用 Application Insights SDK。)	`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. 手動為 Azure App Service 移除名為 Application Insights 延伸模組的私人網站延伸模組。

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

疑難排解

注意

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

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

Windows
Linux

檢查 ApplicationInsightsAgent_EXTENSION_VERSION 應用程式的設定是否設為 ~2 值。
瀏覽至 https://yoursitename.scm.azurewebsites.net/ApplicationInsights。
- 確認 Application Insights 延伸模組狀態 為 Pre-Installed Site Extension, version 2.8.x.xxxx, is running.
  
  如果未執行，請遵循啟用 Application Insights 監視一節中的指示。
- 確認狀態來源存在並如下所示：Status source D:\home\LogFiles\ApplicationInsights\status\status_RD0003FF0317B6_4248_1.json。
  
  如果不存在類似值，表示應用程式目前未執行或不受支援。若要確保應用程式正在執行，請嘗試手動瀏覽應用程式 URL/應用程式端點，讓執行階段資訊可供使用。
- 確認 IKeyExists 為 True。若為 False，請透過 ikey GUID 將 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 新增至應用程式設定。
- 若應用程式參考了任何 Application Insights 套件，啟用 App Service 整合時便可能無效，Application Insights 也可能不會顯示資料。例如：若您先前已使用 ASP.NET Core SDK 檢測 (或嘗試檢測) 應用程式。若要修正此問題，請在入口網站中，開啟與 Application Insights SDK 的 Interop。您將開始在 Application Insights 中看到資料。
  
  重要
  
  這項功能為預覽狀態。
  
  即使最初使用或嘗試使用的是 Application Insights SDK，現在仍會使用無程式碼的方法傳送資料。
  
  重要
  
  如果應用程式使用 Application Insights SDK 傳送任何遙測，則會停用遙測。換句話說，自訂遙測 (例如，任何 Track*() 方法) 和自訂設定 (例如取樣) 都會停用。

檢查 ApplicationInsightsAgent_EXTENSION_VERSION 應用程式的設定是否設為 ~3 值。
瀏覽至 https://your site name.scm.azurewebsites.net/ApplicationInsights。
在此網站中，確認：
- 狀態來源存在並如下所示：Status source /var/log/applicationinsights/status_abcde1234567_89_0.json。
- 值 Auto-Instrumentation enabled successfully 隨即顯示。若不存在類似值，則表示應用程式未執行或不受支援。若要確保應用程式正在執行，請嘗試手動瀏覽應用程式 URL/應用程式端點，讓執行階段資訊可供使用。
- IKeyExists 是 True。若為 False，請透過 ikey GUID 將 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 新增至應用程式設定。

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

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

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

下列兩者間有何差異：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 新增至網頁，在 PHP 或 WordPress 網站上手動檢測用戶端的交易，請使用 JavaScript SDK。

下表提供這些值代表的意義、其基礎原因和建議修正的說明。

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

版本資訊

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

下一步

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

共用方式為