通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure 应用程序服务中为 .NET、Node.js、Python 和 Java 应用程序启用应用程序监视

  • 项目

自动检测（也称为运行时监视）是启用适用于 Azure 应用程序服务的 Application Insights 的最简单方法，无需任何代码更改或高级配置。 根据具体的应用场景，通过手动检测评估是否需要更高级的监视。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。 转换为连接字符串，以利用新功能。

启用 Application Insights

重要

如果同时检测到自动检测监视和手动基于 SDK 的检测，则只会采用手动检测设置。 这样安排可防止发送重复数据。 若要了解详细信息，请参阅故障排除。

注意

在 Azure 门户中进行自动检测

  1. 在应用程序服务的左侧导航菜单中选择“Application Insights”，然后选择“启用”。

    显示“Application Insights”选项卡的屏幕截图，其中选择了“启用”。

  2. 创建新资源，或为此应用程序选择现有 Application Insights 资源。

    注意

    选择“确定”以创建新资源时，系统将提示你“应用监视设置”。 选择“继续”会将新的 Application Insights 资源链接到应用程序服务。 然后，应用程序服务将重启。

    显示“更改资源”下拉列表的屏幕截图。

  3. 指定要使用哪些资源后，可以选择 Application Insights 根据平台为应用程序收集数据的方式。 ASP.NET Core 集合选项为“建议”或“禁用”。

    显示“检测应用程序”部分的屏幕截图。

手动升级监视扩展/代理

从版本 2.8.9 及更高版本升级

从版本 2.8.9 自动升级，无需其他操作。 新的监视位将在后台传送到目标应用程序服务，应用程序重启时会拾取这些位。

若要查看正在运行的扩展的版本，请转到 https://yoursitename.scm.azurewebsites.net/ApplicationInsights。

显示用于查看正在运行的扩展版本的 URL 路径的屏幕截图。

从版本 1.0.0 - 2.6.5 升级

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

  • 通过 Azure 门户启用升级：即使安装了应用程序服务的 Application Insights 扩展，UI 也仅显示“启用”按钮。 在幕后，会移除旧的专用站点扩展。

  • 通过 PowerShell 升级：

    1. 设置应用程序设置以启用预装的站点扩展 ApplicationInsightsAgent。 有关详细信息，请参阅通过 PowerShell 启用。
    2. 手动删除名为 Azure 应用程序服务的 Application Insights 扩展的专用站点扩展。

如果已从低于 2.5.1 的版本完成升级，请检查是否已从应用程序 bin 文件夹中移除了 ApplicationInsights DLL。 有关详细信息，请参阅疑难解答。

配置监视扩展/代理

我们目前不提供用于为 ASP.NET Core 配置监视扩展的选项。

启用客户端监视

对于使用“建议”集合的 ASP.NET Core 应用，默认已启用客户端监视，无论是否存在应用设置 APPINSIGHTS_JAVASCRIPT_ENABLED。

如果要启用客户端监视：

  1. 选择“设置”>“配置”。

  2. 在“应用程序设置”下，创建包含以下信息的“新应用程序设置”：

    • 名称：APPINSIGHTS_JAVASCRIPT_ENABLED
    • 值：false

  3. 保存 设置。 重启应用。

自动监视

若要为 Application Insights 启用遥测数据收集，只需设置以下应用程序设置：

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

应用程序设置定义

应用设置名称 定义 Value
ApplicationInsightsAgent_EXTENSION_VERSION 用于控制运行时监视的主扩展。 ~2 (Windows) 或 ~3 (Linux)
XDT_MicrosoftApplicationInsights_Mode 默认模式下，仅启用基本功能以确保最佳性能。 disabled 或 recommended。
XDT_MicrosoftApplicationInsights_PreemptSdk 仅适用于 ASP.NET Core 应用。 启用与 Application Insights SDK 的互操作。 将扩展与 SDK 并排加载，并使用它来发送遥测数据。 （禁用 Application Insights SDK。） 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 的新 Web 应用程序一样开始该过程。

  1. 使用所需的 Web 应用信息创建新的应用程序服务资源。 在“监视”选项卡上启用 Application Insights。

  2. 选择“查看 + 创建”。 然后，选择“下载自动化模板”。

    显示应用程序服务 Web 应用创建菜单的屏幕截图。

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

    显示应用程序服务 Web 应用模板的屏幕截图。

在以下示例中，将 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

常见问题解答

本部分提供常见问题的解答。

Application Insights 在我的项目中修改哪些内容？

详细信息取决于项目类型。 以下列表是 Web 应用程序的示例。

  • 将文件添加到项目：

    • ApplicationInsights.config
    • ai.js

  • 安装 NuGet 包：

    • Application Insights API：核心 API
    • 适用于 Web 应用程序的 Application Insights API：用于从服务器发送遥测
    • 适用于 JavaScript 应用程序的 Application Insights API：用于从客户端发送遥测

  • 包括包中的程序集：

    • Microsoft.ApplicationInsights
    • Microsoft.ApplicationInsights.Platform

  • 将项目插入：

    • Web.config
    • packages.config

  • 在客户端和服务器代码中插入代码片段，以使用 Application Insights 资源 ID 初始化它们。 例如，在 MVC 应用中，代码插入到主页 Views/Shared/_Layout.cshtml 中。 仅对于新项目，可手动将 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 中缺失应用程序遥测的问题。

注意

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

缺少遥测

Windows

  1. 检查 ApplicationInsightsAgent_EXTENSION_VERSION 应用设置是否设置为值 ~2。

  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，则将 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 以及 ikey GUID 添加到应用程序设置中。

    • 如果应用程序引用任何 Application Insights 包，则启用应用程序服务集成可能不会生效，并且数据可能不会出现在 Application Insights 中。 例如，如果以前使用 ASP.NET Core SDK 检测或尝试检测应用。 若要解决此问题，请在 Azure 门户中启用“与 Application Insights SDK 互操作”。

      重要

      此功能处于预览状态。

      显示已启用互操作设置的屏幕截图。

      即使最初使用或尝试使用 Application Insights SDK，也将使用无代码方法发送数据。

      重要

      如果应用程序使用 Application Insights SDK 发送任何遥测数据，则会禁用遥测。 换句话说，将禁用自定义遥测（例如，任何 Track*() 方法）和自定义设置（如采样）。

Linux

  1. 检查 ApplicationInsightsAgent_EXTENSION_VERSION 应用设置是否设置为值 ~3。

  2. 浏览到 https://your site name.scm.azurewebsites.net/ApplicationInsights。

  3. 在此网站中，确认：

    • 状态源存在并类似于 Status source /var/log/applicationinsights/status_abcde1234567_89_0.json。
    • 将显示值 Auto-Instrumentation enabled successfully。 如果不存在类似的值，则表示应用程序当前未运行或不受支持。 为确保应用程序运行，请尝试手动访问应用程序 URL/应用程序终结点，以提供运行时信息。
    • IKeyExists 为 True。 如果为 False，则将 APPINSIGHTS_INSTRUMENTATIONKEY 和 APPLICATIONINSIGHTS_CONNECTION_STRING 以及 ikey GUID 添加到应用程序设置中。

    显示自动检测状态网页的屏幕截图。

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

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

如果希望在应用程序服务 Web 应用中测试 ASP.NET Core 的无代码服务器和客户端监视，建议遵循有关创建 ASP.NET Core Web 应用的官方指南。 之后，按照当前文章中的说明启用监视。

不支持 PHP 和 WordPress

不支持 PHP 和 WordPress 站点。 目前没有官方支持的可用于在服务器端监视这些工作负荷的 SDK/代理。 若要在 PHP 或 WordPress 站点上跟踪客户端事务，请使用 JavaScript SDK 将客户端 JavaScript 添加到网页。

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

问题值 说明 Fix
AppAlreadyInstrumented:true 此值表示扩展已检测到 SDK 的某个功能已在应用程序中存在，因此将会回退。 Microsoft.ApplicationInsights.AspNetCore 或 Microsoft.ApplicationInsights 的引用可能会产生此值。 删除引用。 其中某些引用是从特定的 Visual Studio 模板默认添加的。 较旧版本的 Visual Studio 引用 Microsoft.ApplicationInsights。
AppAlreadyInstrumented:true 前一部署的应用文件夹中存在 Microsoft.ApplicationsInsights DLL 也可能会产生此值。 清除应用文件夹，以确保删除这些 DLL。 检查本地应用的 bin 目录和应用程序服务的 wwwroot 目录。 （若要检查应用程序服务 Web 应用的 wwwroot 目录，请选择高级工具 (Kudu)>调试控制台>CMD>home\site\wwwroot）。
IKeyExists:false 此值表示应用设置 APPINSIGHTS_INSTRUMENTATIONKEY 中不存在检测密钥。 可能的原因包括意外删除值或忘记在自动化脚本中设置值。 确保该设置在应用程序服务的应用程序设置中存在。

发行说明

本部分包含用于使用 Application Insights 进行运行时检测的基于 ANT 版本的 Azure 应用程序服务的发行说明。

若要查找当前使用的扩展版本，请转到 https://<yoursitename>.scm.azurewebsites.net/ApplicationInsights。

2.8.44

2.8.43

  • 将 .NET/.NET Core、Java 和 Node.js 包分离到不同的应用程序服务 Windows 站点扩展中。

2.8.42

2.8.41

  • 移除了不受支持的版本 (2.1)。 支持的版本为 3.1 和 5.0。

2.8.39

  • 增加了 .NET Core 5.0 支持。

2.8.38

  • 移除了不受支持的版本（2.0、2.2、3.0）。 支持的版本为 2.1 和 3.1。

2.8.37

  • AppSvc Windows 扩展：让 .NET Core 可以与任何版本的 System.Diagnostics.DiagnosticSource.dll 一起使用。

2.8.36

  • AppSvc Windows 扩展：在 .NET Core 中启用了与 AI SDK 的互操作。

2.8.35

  • AppSvc Windows 扩展：添加了 .NET Core 3.1 支持。

2.8.33

  • .NET、.NET Core、Java 和 Node.js 代理以及 Windows 扩展：支持主权云。 可使用连接字符串向主权云发送数据。

2.8.31

  • ASP.NET Core 代理修复了 Application Insights SDK 的问题。 如果运行时加载的 System.Diagnostics.DiagnosticSource.dll 版本不正确，则无代码扩展不会使应用程序崩溃，它会退出。 若要解决此问题，客户应从 bin 文件夹中删除 System.Diagnostics.DiagnosticSource.dll，或者通过设置 ApplicationInsightsAgent_EXTENSIONVERSION=2.8.24 来使用较早版本的扩展。 如果未启用，则不会启用应用程序监视。

2.8.26

  • 修复了与更新后的 Application Insights SDK 相关的问题。 如果 ApplicationInsights.dll 已存在于 bin 文件夹中，则代理不会尝试加载 AiHostingStartup。 它通过 Assembly<AiHostingStartup>.GetTypes() 解决了与反射相关的问题。

  • 已知问题：如果加载了 DiagnosticSource dll 的另一个版本，则可能会引发异常“System.IO.FileLoadException: Could not load file or assembly 'System.Diagnostics.DiagnosticSource, Version=4.0.4.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'”。 例如，如果发布文件夹中存在 System.Diagnostics.DiagnosticSource.dll，则可能会发生这种情况。 作为缓解措施，请在应用程序服务中设置应用设置以使用以前版本的扩展：ApplicationInsightsAgent_EXTENSIONVERSION=2.8.24。

2.8.24

  • 2\.8.21 的重新打包版本。

2.8.23

  • 添加了 ASP.NET Core 3.0 无代码监视支持。

  • 对于运行时版本 2.1、2.2 和 3.0，已将 ASP.NET Core SDK 更新为 2.8.0。 面向 .NET Core 2.0 的应用继续使用 2.1.1 版的 SDK。

2.8.14

  • 对于面向 .NET Core 2.1、2.2 的应用，已将 ASP.NET Core SDK 版本从 2.3.0 更新为最新版 (2.6.1)。 面向 .NET Core 2.0 的应用继续使用 2.1.1 版的 SDK。

2.8.12

  • 支持 ASP.NET Core 2.2 应用。

  • 修复了 ASP.NET Core 扩展中的一个 bug，该 bug 会引发 SDK 的注入，即使已通过 SDK 检测了应用程序。 对于 2.1 和 2.2 版应用，application 文件夹中存在 ApplicationInsights.dll 现在会导致扩展退出。 对于 2.0 版应用，仅当通过 UseApplicationInsights() 调用启用了 ApplicationInsights 时，扩展才会退出。

  • 永久修复了 ASP.NET Core 应用的不完整 HTML 响应。 此修补程序现已扩展为适用于 .NET Core 2.2 应用。

  • 添加了以下支持：为 ASP.NET Core 应用关闭 JavaScript 注入 (APPINSIGHTS_JAVASCRIPT_ENABLED=false appsetting)。 对于 ASP.NET Core，默认情况下，JavaScript 注入处于“选择退出”模式，除非显式关闭。 （进行此默认设置是为了保持当前行为。）

  • 修复了即使 ikey 不存在也会导致注入的 ASP.NET Core 扩展 bug。

  • 修复了 SDK 版本前缀逻辑中导致遥测中的 SDK 版本不正确的 bug。

  • 为 ASP.NET Core 应用添加了 SDK 版本前缀，以识别遥测数据的收集方式。

  • 修复了 SCM- ApplicationInsights 页面，以正确显示预安装的扩展的版本。

2.8.10

  • 修复了 ASP.NET Core 应用的不完整 HTML 响应。

后续步骤