为 Azure 应用服务和 ASP.NET 进行应用程序监视

项目
11/21/2024

现在，可以比过去更轻松地针对 Azure 应用服务中运行的基于 ASP.NET 的 Web 应用程序启用监视。以前，需要手动检测应用。现在，默认情况下应用服务映像中已内置最新的扩展/代理。本文将逐步讲解如何启用 Azure Monitor Application Insights 监视，并提供有关如何自动完成大规模部署过程的初步指导。

注意

通过“开发工具”>“扩展”手动添加 Application Insights 站点扩展的功能已弃用。此扩展安装方法依赖于每个新版本的手动更新。扩展的最新稳定版现在会预装在应用服务映像中。这些文件位于 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 使用情况趋势	否	是
收集使用情况趋势，并启用从可用性结果到事务的关联	是	是
收集未经主机进程处理的异常	是	是
提高使用采样时，负载下的 APM 指标准确性	是	是
跨请求/依赖项边界关联微服务	否（仅单实例 APM 功能）	是

若要配置采样，以前可以通过 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 中启用遥测数据收集，只需设置应用程序设置。

显示应用服务应用程序设置的屏幕截图，其中包含 Application Insights 设置。

应用程序设置定义

应用设置名称	定义	Value
ApplicationInsightsAgent_EXTENSION_VERSION	用于控制运行时监视的主扩展。	`~2`
XDT_MicrosoftApplicationInsights_Mode	默认模式下，仅启用基本功能以确保最佳性能。	`default` 或 `recommended`
InstrumentationEngine_EXTENSION_VERSION	控制是否要启用二进制重写引擎 `InstrumentationEngine`。此设置会对性能以及冷启动/启动时间造成影响。	`~1`
XDT_MicrosoftApplicationInsights_BaseExtensions	控制是否要随依赖项调用一起捕获 SQL 和 Azure 表文本。性能警告：应用程序冷启动时间将会受影响。此设置需要 `InstrumentationEngine`。	`~1`

使用 Azure 资源管理器配置应用服务应用程序设置

可以使用 Azure 资源管理器模板来管理和配置 Azure 应用程序服务的应用程序设置。在使用资源管理器自动化部署新的应用程序服务资源或修改现有资源的设置时，可以使用此方法。

下面是应用程序服务资源的应用程序设置 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 配置了应用程序设置的资源管理器模板的示例，可参阅此模板。具体请参阅从第 238 行开始的部分。

自动创建 Application Insights 资源并链接到新建的应用程序服务资源

若要创建使用默认 Application Insights 设置的资源管理器模板，请像创建启用了 Application Insights 的新 Web 应用程序一样开始该过程。

使用所需的 Web 应用信息创建新的应用程序服务资源。在“监视”选项卡上启用 Application Insights。
选择“查看 + 创建”。然后，选择“下载自动化模板”。

此选项将生成配置了全部所需设置的最新资源管理器模板。

在以下示例中，将 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": "China North 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.chinacloudsites.cn/ApplicationInsights。

从版本 1.0.0 - 2.6.5 升级

从版本 2.8.9 开始，将使用预装的站点扩展。如果使用更低的版本，可通过以下两种方法之一进行更新：

通过门户启用升级：即使安装了应用服务的 Application Insights 扩展。 UI 仅显示“启用”按钮。在幕后，旧的专用站点扩展将被删除。
通过 PowerShell 升级：
1. 设置应用程序设置以启用预装的站点扩展 ApplicationInsightsAgent。有关详细信息，请参阅通过 PowerShell 启用。
2. 手动删除名为“应用服务的 Application Insights 扩展”的专用站点扩展。

如果已从低于 2.5.1 的版本完成升级，请检查是否已从应用程序 bin 文件夹中删除了 Application Insights DLL。有关详细信息，请参阅故障排除部分中的步骤。

疑难解答

注意

使用 ASP.NET 运行时在应用程序服务中创建 Web 应用时，该应用会部署单个静态 HTML 页面作为入门网站。建议不要排查默认模板的问题。在排查问题之前部署应用程序。

下面是我们针对应用服务中运行的基于 ASP.NET 的应用程序的基于扩展/代理的监视提供的分步故障排除指南。

检查 ApplicationInsightsAgent_EXTENSION_VERSION 应用设置是否设置为值 ~2。
浏览到 https://yoursitename.scm.chinacloudsites.cn/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。否则，请将 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 与检测密钥 GUID 添加到应用程序设置中。
- 确认 AppAlreadyInstrumented、AppContainsDiagnosticSourceAssembly 和 AppContainsAspNetTelemetryCorrelationAssembly 没有任何对应的条目。
  
  如果存在其中的任何条目，请从应用程序中删除以下包：Microsoft.ApplicationInsights、System.Diagnostics.DiagnosticSource 和 Microsoft.AspNet.TelemetryCorrelation。

用 Web 应用部署的默认网站不支持自动客户端监视

使用 ASP.NET 运行时在应用服务中创建 Web 应用时，该应用会部署单个静态 HTML 页面作为入门网站。该静态网页还会在 IIS 中加载 ASP.NET 托管 Web 部件。此页允许测试无代码服务器端监视，但不支持自动客户端监视。

如果你希望在应用服务 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 应用服务指标之间有何区别？

Application Insights 为向应用程序发出的请求收集遥测数据。如果在 WebApps/WebServer 中发生故障，并且请求未到达用户应用程序，则 Application Insights 不会有任何有关它的遥测数据。

Application Insights 算出的 serverresponsetime 持续时间不一定与 Web 应用观察到的服务器响应时间匹配。此行为是因为 Application Insights 仅计算实际到达用户应用程序的持续时间。如果请求在 WebServer 中停滞或排队，则该等待时间将包含在 Web 应用指标中，但不会包含在 Application Insights 指标中。

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测，将其作为 REST 调用引入到引入终结点。可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令，测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

不支持 PHP 和 WordPress

不支持 PHP 和 WordPress 站点。目前没有官方支持的可用于在服务器端监视这些工作负荷的 SDK/代理。通过使用 JavaScript SDK 将客户端 JavaScript 添加到网页，你可以手动检测 PHP 或 WordPress 站点上的客户端事务。

下表更详细地解释了这些值的含义、其根本原因和建议的修复方法。

问题值	说明	Fix
`AppAlreadyInstrumented:true`	此值表示扩展已检测到 SDK 的某个功能已在应用程序中存在，因此将会回退。原因可能是引用了 `System.Diagnostics.DiagnosticSource`、`Microsoft.AspNet.TelemetryCorrelation` 或 `Microsoft.ApplicationInsights`。	删除引用。其中某些引用是从特定的 Visual Studio 模板默认添加的。较旧版本的 Visual Studio 可能会添加对 `Microsoft.ApplicationInsights` 的引用。
`AppAlreadyInstrumented:true`	出现此值的原因还可能是前面的某个部署的应用文件夹中存在前述 DLL。	清除应用文件夹，以确保删除这些 DLL。检查本地应用的 bin 目录和应用程序服务资源上的 wwwroot 目录。若要检查应用服务 Web 应用的 wwwroot 目录，请选择“高级工具(Kudu)”>“调试控制台”>“CMD”>“home\site\wwwroot”。
`AppContainsAspNetTelemetryCorrelationAssembly: true`	此值表示扩展已检测到对应用程序中的 `Microsoft.AspNet.TelemetryCorrelation` 的引用，因此将会回退。	删除引用。
`AppContainsDiagnosticSourceAssembly**:true`	此值表示扩展已检测到对应用程序中的 `System.Diagnostics.DiagnosticSource` 的引用，因此将会回退。	对于 ASP.NET，请删除引用。
`IKeyExists:false`	此值表示应用设置 `APPINSIGHTS_INSTRUMENTATIONKEY` 中不存在检测密钥。原因可能是这些值被意外删除，或者你忘记在自动化脚本中设置这些值。	确保该设置在应用程序服务的应用程序设置中存在。

升级 2.8.44 后出现 System.IO.FileNotFoundException

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”，这是一种暂时性解决方法。此设置会触发应用服务使用旧的 Application Insights 扩展。临时缓解措施只能用于应对临时状况。

发行说明

有关最新的更新和 bug 修补程序，请参阅发行说明。

后续步骤

在实时应用上运行探查器。
使用 Application Insights 监视 Azure Functions。
将 Azure 诊断配置为向 Application Insights 发送数据。
监视服务运行状况指标以确保服务可用且做出快速响应。
接收警报通知。
若要从访问网页的浏览器获取客户端遥测数据，请使用适用于 JavaScript 应用和网页的 Application Insights。
可用性概述

通过