Usar Application Insights para .NET Aspire telemetria

Artigo
12/15/2024

Azure Application Insights, um recurso do Azure Monitor, se destaca no APM (Gerenciamento de Desempenho de Aplicativos) para aplicativos Web dinâmicos. Projetos .NET Aspire são desenvolvidos para usar OpenTelemetry para telemetria de aplicações. OpenTelemetry dá suporte a um modelo de extensão para dar suporte ao envio de dados para APMs diferentes. .NET .NET Aspire usa OTLP por padrão para exportação de telemetria, que é usada pelo painel durante o desenvolvimento. Azure Monitor não dá suporte (ainda) ao OTLP, portanto, os aplicativos precisam ser modificados para usar o exportador do Azure Monitor e configurados com a cadeia de conexão.

Para usar o Application Insights, especifique sua configuração no projeto de host do aplicativo e use a distribuição Azure Monitor no projeto padrão do serviço.

Escolhendo como Application Insights é provisionado

.NET Aspire tem a capacidade de provisionar recursos de nuvem como parte da implantação de nuvem, incluindo Application Insights. Em seu projeto de .NET Aspire, você pode decidir se deseja .NET Aspire provisionar um recurso de Application Insights ao implantar no Azure. Você também pode selecionar para usar um recurso de Application Insights existente fornecendo sua cadeia de conexão. As informações de conexão são gerenciadas pela configuração de recursos no projeto do host do aplicativo.

Provisionando insights do aplicativo durante a implantação do Azure

Com essa opção, uma instância de Application Insights será criada para você quando o aplicativo for implantado usando o Azure Developer CLI (azd).

Para usar o provisionamento automático, especifique uma dependência no projeto do host do aplicativo e faça referência a ele em cada projeto/recurso que precise enviar telemetria para Application Insights. As etapas incluem:

Adicionar uma referência de pacote Nuget a Aspire.Hosting.Azure.ApplicationInsights no projeto host do aplicativo.
Atualize o código do host do aplicativo para usar o recurso Application Insights e referencie-o de cada projeto:

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();

Siga as etapas em Implantar um projeto de .NET Aspire para Azure Container Apps usando oAzure Developer CLI (guia detalhado) para implantar o aplicativo no Azure Container Apps. azd criará um recurso Application Insights como parte do mesmo grupo de recursos e configurará a cadeia de conexão para cada contêiner.

Fornecimento manual do recurso Application Insights

Application Insights usa uma cadeia de conexão para informar ao exportador de OpenTelemetry para onde enviar os dados de telemetria. A cadeia de conexão é específica para a instância de Application Insights para a qual você deseja enviar a telemetria. Isto pode ser encontrado na página Visão Geral da instância do Application Insights.

Se você quiser usar uma instância de Application Insights provisionada manualmente, use a API AddConnectionString no projeto de host do aplicativo para informar aos projetos/contêineres para onde enviar os dados de telemetria. A distribuição Azure Monitor espera que a variável de ambiente seja APPLICATIONINSIGHTS_CONNECTION_STRING, de modo que precise ser definida explicitamente ao definir a cadeia de conexão.

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();

Uso de recursos durante o desenvolvimento

Ao executar o projeto .NET.NET Aspire localmente, o código anterior lê a cadeia de conexão da configuração. Como esse é um segredo, você deve armazenar o valor em segredos do aplicativo. Clique com o botão direito do mouse no projeto de host do aplicativo e escolha Gerenciar Segredos no menu de contexto para abrir o arquivo de segredos do projeto de host do aplicativo. No arquivo, adicione a chave e sua cadeia de conexão específica, o exemplo a seguir é para fins ilustrativos.

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

Nota

O name especificado no código do host do aplicativo precisa corresponder a uma chave dentro da seção ConnectionStrings no arquivo de configurações.

Uso de recursos durante a implantação

Ao implantar um aplicativo Aspire com Azure Developer CLI (azd), ele reconhecerá o recurso de cadeia de conexão e solicitará um valor. Isso permite que um recurso diferente seja usado para a implantação a partir do valor usado para desenvolvimento local.

Implantação mista

Se você quiser usar um mecanismo de implantação diferente por contexto de execução, use a API apropriada condicionalmente. Por exemplo, o código a seguir usa uma conexão pré-fornecida no momento do desenvolvimento e um recurso provisionado automaticamente no momento da implantação.

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();

Dica

O código anterior exige que você forneça as informações da cadeia de conexão nos segredos do aplicativo para uso durante o desenvolvimento, e você será solicitado a fornecer a cadeia de conexão pelo azd no momento da implantação.

Usar a distribuição Azure Monitor

Para simplificar a exportação para o Azure Monitor, este exemplo usa o repositório Monitor Exporter do Azure. Este é um pacote wrapper em torno do pacote Azure Monitor OpenTelemetry Exportador que facilita a exportação para Azure Monitor com um conjunto de padrões comuns.

Adicione o seguinte pacote ao projeto ServiceDefaults, para que ele seja incluído em cada um dos serviços de .NET.NET Aspire. Para obter mais informações, consulte .NET.NET Aspire configurações padrão de serviço.

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

Adicione uma declaração using ao início do projeto.

using Azure.Monitor.OpenTelemetry.AspNetCore;

Descompacte a linha em AddOpenTelemetryExporters para usar o exportador 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;
}

É possível personalizar ainda mais o exportador do Azure Monitor, incluindo personalizar o nome do recurso e alterar a amostragem. Para obter mais informações, consulte Personalizar o exportador do Monitor Azure. Usando a versão sem parâmetros de UseAzureMonitor(), a cadeia de conexão será obtida da variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, que configuramos por meio do projeto de host do aplicativo.

Compartilhar via