使用 Application Insights 进行 .NET Aspire 遥测

项目
12/15/2024

Azure Application Insights是 Azure Monitor 的一项功能，在实时网页应用程序的应用性能管理（APM）方面表现出色。 .NET Aspire 项目旨在将 OpenTelemetry 用于应用程序遥测。 OpenTelemetry 支持扩展模型，以支持将数据发送到不同的 APM。默认.NET.NET Aspire 使用 OTLP 进行遥测导出，仪表板在开发过程中使用它。 Azure Monitor 还未支持 OTLP，因此需要修改应用程序以便使用 Azure Monitor 导出程序，并通过连接字符串进行配置。

若要使用 Application Insights，请在应用主机项目中指定其配置和，并在服务默认项目中使用 Monitor 发行版。

选择如何预配 Application Insights

.NET Aspire 能够将云资源预配为云部署的一部分，包括 Application Insights。在 .NET Aspire 项目中，可以决定在部署到 Azure时是否希望 .NET Aspire 预配 Application Insights 资源。还可以选择使用现有的 Application Insights 资源，只需提供其连接字符串。连接信息由应用主机项目中的资源配置管理。

在 Azure 部署期间配置应用程序洞察

在部署应用程序时使用此选项，将通过 Azure Developer CLI （azd）为你创建一个 Application Insights 实例。

若要使用自动预配，请在应用主机项目中指定依赖项，并在需要将遥测数据发送到 Application Insights的每个项目/资源中引用它。这些步骤包括：

在应用程序主机项目中为 Aspire.Hosting.Azure.ApplicationInsights 添加 Nuget 包引用。
更新应用主机代码以使用 Application Insights 资源，并从每个项目中引用它：

var builder = DistributedApplication.CreateBuilder(args);

// Automatically provision an Application Insights resource
var insights = builder.AddAzureApplicationInsights("MyApplicationInsights");

// Reference the resource from each project 
var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

按照中的步骤，用 Azure Developer CLI（深入指南）将 .NET Aspire 项目部署到 Azure Container Apps 并把应用程序部署到 Azure Container Apps。 azd 将创建一个 Application Insights 资源作为同一资源组的一部分，并为每个容器配置连接字符串。

手动预配 Application Insights 资源

Application Insights 使用连接字符串告诉 OpenTelemetry 导出程序发送遥测数据的位置。连接字符串特定于要向其发送遥测数据的 Application Insights 实例。可以在 Application Insights 实例的“概述”页中找到它。

如果要使用手动预配的 Application Insights 实例，则应在应用主机项目中使用 AddConnectionString API 来告知项目/容器在何处发送遥测数据。 Azure Monitor 发行版要求环境变量 APPLICATIONINSIGHTS_CONNECTION_STRING，因此在定义连接字符串时需要显式设置该变量。

var builder = DistributedApplication.CreateBuilder(args);

var insights = builder.AddConnectionString(
    "myInsightsResource",
    "APPLICATIONINSIGHTS_CONNECTION_STRING");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

开发期间的资源使用情况

在本地运行 .NET.NET Aspire 项目时，前面的代码从配置中读取连接字符串。由于这是机密，因此应将该值存储在应用机密中。右键单击应用主机项目，然后从上下文菜单中选择 管理机密 打开应用主机项目的机密文件。在文件中添加密钥和特定连接字符串，下面的示例用于说明目的。

{
  "ConnectionStrings": {
    "myInsightsResource": "InstrumentationKey=12345678-abcd-1234-abcd-1234abcd5678;IngestionEndpoint=https://westus3-1.in.applicationinsights.azure.com"
  }
}

注意

应用主机代码中指定的 name 需要匹配设置文件中 ConnectionStrings 节内的键。

部署期间的资源使用情况

使用 Azure Developer CLI（azd）部署 Aspire 应用程序时，它将识别连接字符串资源并提示输入值。这使得可以在部署中使用与本地开发时所用的值不同的资源。

混合部署

如果要为每个执行上下文使用不同的部署机制，请有条件地使用相应的 API。例如，以下代码在开发时使用预先提供的连接，并在部署时使用自动预配的资源。

var builder = DistributedApplication.CreateBuilder(args);

var insights = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureApplicationInsights("myInsightsResource")
    : builder.AddConnectionString("myInsightsResource", "APPLICATIONINSIGHTS_CONNECTION_STRING");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

提示

在开发阶段，上述代码要求你在应用程序机密中提供连接字符串信息，而在部署时系统将通过 azd 提示你输入连接字符串。

使用 Azure Monitor 发行版

为了使导出到 Azure Monitor 更简单，此示例使用 Azure Monitor 导出工具库。这是围绕 Azure Monitor OpenTelemetry 导出程序包的一个包装程序包，它使得通过一组常见默认配置导出到 Azure Monitor 更加方便。

将以下包添加到 ServiceDefaults 项目中，以便将其包含在每个 .NET.NET Aspire 服务中。有关详细信息，请参阅 .NET.NET Aspire 服务默认值。

<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" 
                  Version="*" />

将 using 语句添加到项目文件的开头。

using Azure.Monitor.OpenTelemetry.AspNetCore;

取消注释 AddOpenTelemetryExporters 中的行以使用 Azure Monitor 导出程序：

private static IHostApplicationBuilder AddOpenTelemetryExporters(
    this IHostApplicationBuilder builder)
{
    // Omitted for brevity...

    // Uncomment the following lines to enable the Azure Monitor exporter 
    // (requires the Azure.Monitor.OpenTelemetry.AspNetCore package)
    if (!string.IsNullOrEmpty(builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]))
    {
        builder.Services.AddOpenTelemetry().UseAzureMonitor();
    }
    return builder;
}

可以进一步自定义 Azure Monitor 导出程序，包括自定义资源名称和更改采样。有关详细信息，请参阅自定义 Azure Monitor 导出程序。使用无参数版本的 UseAzureMonitor()，将从 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量中获取连接字符串，我们通过应用主机项目进行了设置。

通过