Usar Application Insights para telemetria .NET Aspire

Artigo
12/16/2024

Azure Application Insights, um recurso do Azure Monitor, se destaca no Gerenciamento de Desempenho de Aplicativos (APM) para aplicativos Web ao vivo. .NET Aspire projetos foram concebidos para usar OpenTelemetry para telemetria de aplicações. OpenTelemetry suporta um modelo de extensão para suportar o envio de dados para diferentes APMs. .NET .NET Aspire usa OTLP por padrão para exportação de telemetria, que é usada pelo painel durante o desenvolvimento. Azure Monitor (ainda) não suporta 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 a sua configuração no projeto do host da aplicação e use a distribuição do Azure Monitor nas configurações padrão de serviço do projeto.

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. No seu projeto .NET Aspire, pode decidir se quer que .NET Aspire disponibilize um recurso Application Insights ao implementar no Azure. Você também pode optar por 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 do recurso no projeto de host do aplicativo.

Provisionamento de informações de aplicação durante o desdobramento 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 de host do aplicativo e faça referência a ela em cada projeto/recurso que precisa enviar telemetria para Application Insights. As etapas incluem:

Adicione uma referência de pacote NuGet a Aspire.Hosting.Azure.ApplicationInsights no projeto hospedeiro da aplicação.
Atualize o código do host do aplicativo para usar o recurso Application Insights e faça referência a ele a partir 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 os passos em para implementar um projeto .NET Aspire em Azure Container Apps utilizando o Azure Developer CLI (guia detalhado) para implementar a aplicação em 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.

Aprovisionamento 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. Ele pode ser encontrado na página Visão geral da instância do Application Insights.

Se desejar usar uma instância de Application Insights provisionada manualmente, use a API AddConnectionString no projeto host do aplicativo para informar aos projetos/contêineres para onde enviar os dados de telemetria. A distro do Azure Monitor espera que a variável de ambiente seja APPLICATIONINSIGHTS_CONNECTION_STRING, portanto, isso precisa ser explicitamente definido 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();

Utilização 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 isso é 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 abaixo é para fins de ilustração.

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

Observação

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 uma aplicação Aspire com Azure Developer CLI (azd), ele reconhecerá o recurso da cadeia de conexão e pedirá um valor. Isso permite que um recurso diferente seja usado para a implantação em comparação com o valor usado para o desenvolvimento local.

Implantação mista

Se desejar 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 requer que forneça as informações da string de conexão nos segredos da aplicação para uso durante o desenvolvimento, e será solicitado que insira a string de conexão por azd durante a implantação.

Usar a distro do Azure Monitor

Para simplificar a exportação para o Azure Monitor, este exemplo usa o Azure Monitor Exporter Repo. Este é um pacote wrapper em torno do pacote Azure Monitor OpenTelemetry Exporter que facilita a exportação para o 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 .NET.NET Aspire. Para obter mais informações, consulte .NET.NET Aspire padrões de serviço.

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

Adicione uma instrução using à parte superior do projeto.

using Azure.Monitor.OpenTelemetry.AspNetCore;

Descomente a linha no AddOpenTelemetryExporters para usar o exportador do Monitor 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;
}

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

Partilhar via