請使用 Application Insights 進行 .NET Aspire 遙測

發行項
12/15/2024

Azure Application Insights是 Azure 監視器的一項功能，在即時 Web 應用程式的應用程式效能管理（APM）方面表現優異。 .NET Aspire 專案的設計目的是使用 OpenTelemetry 進行應用程式遙測。 OpenTelemetry 支援擴充模型，以支援將數據傳送至不同的 APM。 .NET .NET Aspire 預設使用 OTLP 來匯出遙測數據，該功能在開發期間由儀錶板使用。 Azure 監視器尚未支援 OTLP，因此需要修改應用程式以使用 Azure 監視器匯出工具，並使用連接字串進行設定。

若要使用 Application insights，您需要在應用程式主專案中指定其組態。和將使用服務預設值專案中的 Azure 監控分發版本。

選擇布建 Application Insights 的方法

.NET Aspire 有能力在雲端部署過程中提供雲端資源，包括 Application Insights。在 .NET Aspire 專案中，您可以在部署至 Azure時，決定是否要 .NET Aspire 布建 Application Insights 資源。您也可以提供連線字串來選擇使用現有的 Application Insights 資源。連線資訊是由應用程式主機專案中的資源組態所管理。

在 Azure 部署期間設置 Application Insights

使用此選項時，當您使用 Azure Developer CLI （azd）部署應用程式時，將會為您建立 Application Insights 實例。

若要使用自動布建，您可以在應用程式主專案中指定相依性，並在需要將遙測傳送至 Application Insights的每個專案/資源中參考它。這些步驟包括：

將 NuGet 套件引用新增至應用程式主機專案的 Aspire.Hosting.Azure.ApplicationInsights。
更新應用程式主機代碼以使用 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();

請遵循部署 .NET Aspire 專案至 Azure Container Apps的步驟，使用中的 Azure Developer CLI （深入指南）將應用程式部署至 Azure Container Apps。 azd 會建立 Application Insights 資源作為相同資源群組的一部分，併為每個容器設定連接字串。

手動布建 Application Insights 資源

Application Insights 使用連接字串來告訴 OpenTelemetry 匯出工具傳送遙測數據的位置。這個連接字串是專為您想要傳送遙測資料的 Application Insights 實例而設。您可以在 Application Insights 實例的 [概觀] 頁面中找到。

如果您想要使用手動布建的 Application Insights 實例，則您應該使用應用程式主專案中的 AddConnectionString API 來告訴專案/容器要傳送遙測數據的位置。 Azure 監視器的發行版本預期環境變數為 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 監視器版本

為了簡化匯出至 Azure 監視器，此範例會使用 Azure 監視器匯出器存放庫。這是一個環繞 Azure Monitor OpenTelemetry Exporter 套件的封裝套件，使您可以更輕鬆地使用一組通用預設值匯出至 Azure Monitor。

將下列套件新增至 ServiceDefaults 專案，使其包含在每個 .NET.NET Aspire 服務中。如需詳細資訊，請參閱 .NET.NET Aspire 服務預設值。

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

將using語法新增至程式碼開頭。

using Azure.Monitor.OpenTelemetry.AspNetCore;

取消註注 AddOpenTelemetryExporters 中的行，以使用 Azure 監視器匯出工具：

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 監視器匯出工具，包括自定義資源名稱和變更取樣。如需詳細資訊，請參閱自訂 Azure 監視器匯出工具。使用無參數版本的 UseAzureMonitor()，將會從 APPLICATIONINSIGHTS_CONNECTION_STRING 環境變數中取回連接字串，我們會透過應用程式主機項目進行設定。

共用方式為