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

启用适用于 ASP.NET Core 应用程序的 Application Insights

本文介绍如何启用作为 Azure Web 应用的适用于 ASP.NET Core 应用程序的 Application Insights。 此实现使用基于 SDK 的方法,也可以使用自动检测方法

Application Insights 可以从你的 ASP.NET Core 应用程序收集以下遥测数据:

  • 请求
  • 依赖项
  • 异常
  • 性能计数器
  • 检测信号
  • 日志

我们将使用一个面向 net6.0ASP.NET Core MVC 应用程序示例。 这些说明适用于所有 ASP.NET Core 应用程序。 如果你使用的是辅助角色服务,请使用此处的说明。

注意

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

支持的方案

无论在何处以何种方式运行你的应用程序,适用于 ASP.NET Core 的 Application Insights SDK 都可对其进行监视。 如果应用程序正在运行并与 Azure 建立了网络连接,则可以收集遥测数据。 只要支持 .NET Core,就能支持 Application Insights 监视。 支持涵盖以下方案:

  • 操作系统:Windows、Linux 或 Mac
  • 托管方法:进程内或进程外
  • 部署方法:框架依赖或自包含
  • Web 服务器:IIS(Internet 信息服务器)或 Kestrel
  • 托管平台:Azure 应用服务的 Web 应用功能、Azure VM、Docker、Azure Kubernetes 服务 (AKS) 等
  • .NET Core 版本:所有正式支持的不在预览中的 .NET Core 版本
  • IDE:Visual Studio、Visual Studio Code 或命令行

先决条件

如果想要按照本文中的指南进行操作,则需要满足某些先决条件。

  • Visual Studio 2022
  • Visual Studio 工作负载:ASP.NET 和 Web 开发、数据存储和处理,以及 Azure 开发
  • .NET 6.0
  • Azure 订阅和用户帐户(能够创建和删除资源)

部署 Azure 资源

请按照指南从其 GitHub 存储库部署示例应用程序。

为了向某些资源提供全局唯一名称,已分配了一个包含 5 个字符的后缀。 请记下此后缀,以供在本文后面使用。

显示部署的 Azure 资源列表,其中突出显示了包含 5 个字符的后缀。

创建 Application Insights 资源

  1. Azure 门户中,找到并选择 application-insights-azure-cafe 资源组。

  2. 从顶部工具栏菜单,选择“+ 创建”。

    显示资源组 application-insights-azure-cafe,其中在工具栏菜单上突出显示了“+ 创建”按钮。

  3. 在“创建资源”屏幕上的市场搜索文本框中,搜索并选择 Application Insights

    显示“创建资源”屏幕,其中突出显示在搜索框中输入的 Application Insights,以及搜索结果中的 Application Insights。

  4. 在 Application Insights 资源概述屏幕上,选择“创建”。

    显示 Application Insights 概述屏幕,其中突出显示了“创建”按钮。

  5. 在 Application Insights 屏幕的“基本信息”选项卡上,按如下方式填写表单,然后选择“查看 + 创建”按钮。 下表中未指定的字段可以保留其默认值。

    字段 Value
    名称 输入 azure-cafe-application-insights-{SUFFIX},将 {SUFFIX} 替换为之前记录的相应后缀值。
    区域 选择在部署项目资源时所选择的相同区域。
    Log Analytics 工作区 选择 azure-cafe-log-analytics-workspace,或者在此处创建新的日志分析工作区。

    Application Insights“基本信息”选项卡显示填充了上述值的窗体。

  6. 验证通过后,选择“创建”以部署资源。

    显示 Application Insights 验证屏幕,指示验证已通过,并突出显示了“创建”按钮。

  7. 部署完成后,返回到 application-insights-azure-cafe 资源组,然后选择已部署的 Application Insights 资源。

    显示 Azure Cafe 资源组,其中突出显示了 Application Insights 资源。

  8. 在 Application Insights 资源的“概述”屏幕上,复制“连接字符串”值,以供在本文的下一部分中使用。

    显示 Application Insights“概述”屏幕,其中突出显示了“连接字符串”值并选择了“复制”按钮。

在 Web 应用服务中配置 Application Insights 连接字符串应用程序设置

  1. 返回到 application-insights-azure-cafe 资源组,找到并打开 azure-cafe-web-{SUFFIX} 应用服务资源。

    显示 Azure Cafe 资源组,其中突出显示了 azure-cafe-web-{SUFFIX} 资源。

  2. 从左侧菜单的“设置”标题下,选择“配置”。 然后,在“应用程序设置”选项卡上的“应用程序设置”标题下,选择“+ 新建应用程序设置”。

    显示应用服务资源屏幕,其中在左侧菜单中选择了“配置”项,并突出显示了“+ 新建应用程序设置”工具栏按钮。

  3. 在“添加/编辑应用程序设置”边栏选项卡中,按如下所示填写窗体并选择“确定”。

    字段 Value
    名称 APPLICATIONINSIGHTS_CONNECTION_STRING
    粘贴在上一部分中获取的 Application Insights 连接字符串。

    “添加/编辑应用程序设置”边栏选项卡显示填充了前面的值。

  4. 在“应用服务配置”屏幕上的工具栏菜单中,选择“保存”按钮。 当系统提示保存更改时,选择“继续”。

    显示“应用服务配置”屏幕,其中突出显示了工具栏菜单上的“保存”按钮。

安装 Application Insights NuGet 包

我们需要将 ASP.NET Core MVC Web 应用程序配置为发送遥测。 这可使用适用于 ASP.NET Core Web 应用程序的 Application Insights NuGet 包来完成。

  1. 使用 Visual Studio,打开 1 - Starter Application\src\AzureCafe.sln

  2. 在“解决方案资源管理器”面板中,右键单击 AzureCafe 项目文件,然后选择“管理 NuGet 包”。

    “解决方案资源管理器”显示从上下文菜单中选择的“管理 NuGet 包”。

  3. 选择“浏览”选项卡,然后搜索并选择 Microsoft.ApplicationInsights.AspNetCore。 选择“安装”,然后接受许可条款。 建议使用最新稳定版本。 在开源 GitHub 存储库中可以找到 SDK 的完整发行说明。

    显示 NuGet 选项卡,其中选择了“浏览”选项卡,并在搜索框中输入了 Microsoft.ApplicationInsights.AspNetCore。Microsoft.ApplicationInsights.AspNetCore 包是从结果列表中选择的。在右侧窗格中,从下拉列表中选择了最新的稳定版本,并突出显示了“安装”按钮。

  4. 在本文的下一部分中,使 Visual Studio 处于打开状态。

启用 Application Insights 服务器端遥测

适用于 ASP.NET Core Web 应用程序的 Application Insights NuGet 包封装了一些功能,用于将服务器端遥测发送到 Azure 中的 Application Insights 资源。

  1. 在 Visual Studio 解决方案资源管理器中,找到并打开 Program.cs 文件。

    显示 Visual Studio 解决方案资源管理器,其中突出显示了 Program.cs。

  2. builder.Services.AddControllersWithViews() 语句之前插入以下代码。 此代码会自动从配置中读取 Application Insights 连接字符串值。 AddApplicationInsightsTelemetry 方法将 ApplicationInsightsLoggerProvider 注册到内置的依赖项注入容器中,然后使用该容器来满足 ILoggerILogger<TCategoryName> 实现请求。

    builder.Services.AddApplicationInsightsTelemetry();
    

    显示代码窗口,其中突出显示了前面的代码片段。

    提示

    详细了解 ASP.NET Core 中的配置选项

为 Web 应用程序启用客户端遥测

完成前面所述的步骤足以开始收集服务器端遥测数据。 此应用程序包含客户端组件,请遵循后续步骤开始收集使用情况遥测

  1. 在 Visual Studio 解决方案资源管理器中,找到并打开 \Views\_ViewImports.cshtml。 将下面的代码添加到现有文件的末尾。

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    

    显示 _ViewImports.cshtml 文件,其中突出显示了前面的代码行。

  2. 若要为应用程序正确启用客户端监视,JavaScript 代码片段必须出现在要监视的应用程序的每个页面的 <head> 部分中。 在 Visual Studio 解决方案资源管理器中,找到并打开 \Views\Shared\_Layout.cshtml,在结束 <\head> 标记之前插入以下代码。

    @Html.Raw(JavaScriptSnippet.FullScript)
    

    显示 _Layout.cshtml 文件,其中在页面的标题部分中突出显示了前一行代码。

    提示

    作为使用 FullScript 的替代方法,可以使用 ScriptBody。 如果需要控制 <script> 标记以设置内容安全策略,请使用 ScriptBody

    <script> // apply custom changes to this script tag.
        @Html.Raw(JavaScriptSnippet.ScriptBody)
    </script>
    

注意

JavaScript 注入提供默认配置体验。 如果需要设置连接字符串以外的配置,需要删除上述自动注入并手动添加 JavaScript SDK

启用对数据库查询的监视

在调查性能下降的原因时,必须要包括对数据库调用的见解。 通过配置依赖项模块启用监视。 默认情况下,将启用依赖项监视,包括 SQL。 可以按照以下步骤来捕获完整的 SQL 查询文本。

注意

SQL 文本可能包含敏感数据,例如密码和 PII。 启用此功能时务必小心。

  1. 在 Visual Studio 解决方案资源管理器中,找到并打开 Program.cs 文件。

  2. 在文件的顶部,添加以下 using 语句。

    using Microsoft.ApplicationInsights.DependencyCollector;
    
  3. builder.Services.AddApplicationInsightsTelemetry() 代码后面,插入以下命令以启用 SQL 命令文本检测。

    builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
    

    显示代码窗口,其中突出显示了前面的代码。

运行 Azure Cafe Web 应用程序

部署 Web 应用程序代码后,遥测将流向 Application Insights。 Application Insights SDK 自动将传入的 Web 请求收集到应用程序。

  1. 在解决方案资源管理器中右键单击“AzureCafe”,并从上下文菜单中选择“发布”。

    显示 Visual Studio 解决方案资源管理器,其中选择了 Azure Cafe 项目并突出显示了“发布”上下文菜单项。

  2. 选择“发布”将新代码提升到 Azure 应用服务。

    显示 AzureCafe 发布配置文件,其中突出显示了“发布”按钮。

  3. 发布成功后,新的浏览器窗口将打开到 Azure Cafe Web 应用程序。

    显示 Azure Cafe Web 应用程序。

  4. 在 Web 应用程序中执行各种活动以生成一些遥测。

    1. 选择 Cafe 旁边的“详细信息”以查看其菜单和评价。

      显示 Azure Cafe 列表的一部分,其中突出显示了“详细信息”按钮。

    2. 在“Cafe”屏幕上,选择“评价”选项卡以查看和添加评价。 选择“添加评价”按钮以添加评价。

      显示  详细信息屏幕,其中突出显示了“添加评价”按钮。

    3. 在“创建评价”对话框中,为该评价输入姓名、评分、评论并上传照片。 完成后,选择“添加评价”。

      显示“创建评价”对话框。

    4. 根据需要重复添加评价,以生成更多遥测。

实时指标

实时指标可用于快速验证是否正确配置了 Application Insights 监视。 遥测数据可能需要几分钟才能出现在门户和分析中,但实时指标会近乎实时地显示正在运行的进程的 CPU 使用情况。 它还可以显示其他遥测数据,例如请求、依赖项和跟踪。

应用程序映射

示例应用程序调用多个 Azure 资源,包括 Azure SQL、Azure Blob 存储和 Azure 语言服务(用于评价情绪分析)。

显示 Azure Cafe 示例应用程序体系结构。

Application Insights 对传入的遥测数据进行内省,并且能够生成检测到的系统集成的视觉对象映射。

  1. 访问并登录到 Azure 门户

  2. 打开示例应用程序资源组 application-insights-azure-cafe

  3. 从资源列表中,选择 azure-cafe-insights-{SUFFIX} Application Insights 资源。

  4. 从左侧菜单中,选择“调查”标题下的“应用程序映射”。 观察生成的应用程序映射。

    显示 Application Insights 应用程序映射。

查看 HTTP 调用和数据库 SQL 命令文本

  1. 在 Azure 门户中,打开 Application Insights 资源。

  2. 在左侧菜单的“调查”标题下,选择“性能”。

  3. “操作”选项卡包含应用程序接收的 HTTP 调用的详细信息。 你还可以在服务器和浏览器(客户端)数据视图之间切换。

    显示 Application Insights 的“性能”屏幕,其中突出显示了“服务器”和“浏览器”之间的切换以及应用程序接收的 HTTP 调用列表。

  4. 从表中选择“操作”,然后选择钻取到请求的示例。

    显示“性能”屏幕,其中选择了 POST 操作,突出显示了“钻取到示例”按钮,并从建议的列表中选择了一个示例。

  5. 此时将显示所选请求的端到端事务。 在本例中,创建了包含图像的评价,因此它包括对 Azure 存储、语言服务(用于情绪分析)的调用,以及对 SQL Azure 的数据库调用,以保留评价。 在此示例中,第一个选定的事件显示与 HTTP POST 调用相关的信息。

    显示端到端事务,其中选择了 HTTP Post 调用。

  6. 选择某个 SQL 项以查看向数据库发出的 SQL 命令文本。

    端到端事务显示 SQL 命令详细信息。

  7. (可选)选择对 Azure 存储或语言服务的依赖项(传出)请求。

  8. 返回到“性能”屏幕,然后选择“依赖项”选项卡来调查对外部资源的调用。 请注意,Operations 表包括对情绪分析、Blob 存储和 Azure SQL 的调用。

    显示“性能”屏幕,其中选择了“依赖项”选项卡并突出显示了 Operations 表。

使用 Application Insights 进行应用程序日志记录

日志记录概述

Application Insights 是一种可供 ASP.NET Core 应用程序使用的日志记录提供程序,当安装适用于 ASP.NET Core 的 Application Insights NuGet 包并且启用了服务器端遥测收集时,它对应用程序可用。 提醒一下,Program.cs 中的以下代码将 ApplicationInsightsLoggerProvider 注册到内置的依赖项注入容器中。

builder.Services.AddApplicationInsightsTelemetry();

ApplicationInsightsLoggerProvider 注册为日志记录提供程序后,应用就可以使用具有 ILogger 的构造函数注入或泛型类型替代 ILogger<TCategoryName> 来记录到 Application Insights。

注意

使用默认设置,日志记录提供程序配置为自动捕获严重级别为 LogLevel.Warning 或更高的日志事件。

考虑以下示例控制器,该控制器演示 ILogger 的注入,该注入使用向依赖项注入容器注册的 ApplicationInsightsLoggerProvider 进行解析。 在 Get 方法中观察记录的“参考性”、“警告”和“错误”消息。

注意

默认情况下,不会记录“参考性”级别的跟踪。 仅捕获“警告”及以上级别。

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInfo("An example of an Info trace..")
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

有关详细信息,请参阅 Logging in ASP.NET Core(ASP.NET Core 中的日志记录)。

在 Application Insights 中查看日志

上面的 ValuesController 与示例应用程序一起部署,并位于项目的 Controllers 文件夹中。

  1. 使用 Internet 浏览器打开示例应用程序。 在地址栏中,追加 /api/Values 并按 Enter

    显示浏览器窗口,其中将 /api/Values 追加到地址栏中的 URL。

  2. 稍等片刻,然后返回到 Azure 门户中的“Application Insights”资源。

    显示资源组,其中突出显示了 Application Insights 资源。

  3. 从 Application Insights 资源的左侧菜单中的“监视”部分下,选择“日志”。 在“表”窗格中的“Application Insights”树下,双击“traces”表。 如下所示修改查询以检索值控制器的跟踪,然后选择“运行”以筛选结果。

    traces 
    | where operation_Name == "GET Values/Get"
    
  4. 观察结果是否显示控制器中存在的日志记录消息。 日志严重性为 2 表示警告级别,日志严重性为 3 表示错误级别。

  5. 此外,也可以编写查询以根据日志的类别检索结果。 默认情况下,类别是注入 ILogger 的类的完全限定的名称,在本例中为 ValuesController(如果存在与该类关联的命名空间,则该名称将以命名空间作为前缀)。 重新编写并运行以下查询以根据类别检索结果。

    traces 
    | where customDimensions.CategoryName == "ValuesController"
    

控制发送到 Application Insights 的日志级别

ILogger 实现具有内置机制,可应用日志筛选。 通过此筛选可以控制发送到每个已注册的提供程序(包括 Application Insights 提供程序)的日志。 可以在配置(使用 appsettings.json 文件)或代码中使用筛选。 有关日志级别和正确用法指南的详细信息,请参阅日志级别文档。

以下示例显示如何将筛选规则应用于 ApplicationInsightsLoggerProvider,以控制发送到 Application Insights 的日志级别。

使用配置创建筛选规则

在配置中,ApplicationInsightsLoggerProvider 的别名为 ApplicationInsights。 appsettings.json 文件的以下部分将所有提供程序的默认日志级别设置都为 LogLevel.Warning。 专门针对以“ValuesController”开头的类别的 ApplicationInsights 提供程序的配置将使用 LogLevel.Error 或更高版本替代此默认值。

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

使用 appsettings.json 中的上述代码部署示例应用程序将只生成在与 ValuesController 交互时发送到 Application Insights 的错误跟踪。 这是因为 ValuesController 类别的 LogLevel 设置为“错误”,因此会抑制“警告”跟踪。

关闭对 Application Insights 的日志记录

要使用配置禁用日志记录,请将所有 LogLevel 值设置为“无”。

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

同样,在代码中,将 ApplicationInsightsLoggerProvider 的默认级别和任何后续日志级别设置为“无”。

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

开源 SDK

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

后续步骤