Application Insights para aplicativos ASP.NET Core

Artigo
11/05/2024

Este artigo descreve como habilitar e configurar o Application Insights para um aplicativo ASP.NET Core.

Observação

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo do Application Insights é coletar dados usando o OpenTelemetry. Para obter mais informações, consulte Habilitar o OpenTelemetry do Azure Monitor para aplicativos .NET, Node.js, Python e Java e nosso Roteiro do OpenTelemetry. As diretrizes de migração está disponível para .NET, Node.js e Python.

O Application Insights pode coletar a seguinte telemetria do seu aplicativo ASP.NET Core:

Requests
Dependências
Exceções
Contadores de desempenho
Pulsações
Logs

Usaremos um aplicativo MVC como exemplo. Se você estiver usando o Serviço de Trabalho, use as instruções em Application Insights para aplicativos do Serviço de Trabalho.

Uma Oferta do .NET baseada em OpenTelemetry está disponível. Para obter mais informações, consulte Visão geral de OpenTelemetry.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

Observação

Caso você deseje usar o provedor ILogger autônomo, use Microsoft.Extensions.Logging.ApplicationInsight.

Cenários com suporte

O SDK do Application Insights para ASP.NET Core pode monitorar os aplicativos, independentemente de onde ou como eles são executados. Se o seu aplicativo estiver em execução e tiver conectividade de rede com o Azure, será possível coletar telemetria. Há suporte para monitoramento do Application Insights em todos os lugares em que o .NET Core tem suporte e aborda os seguintes cenários:

Sistema operacional: Windows, Linux ou Mac
Método de hospedagem\ : no processo ou fora do processo
Método de implantação: dependente do Framework ou autossuficiente
Servidor Web: IIS (Servidor de Informações da Internet) ou Kestrel
Plataforma de hospedagem: recurso dos Aplicativos Web do Serviço de Aplicativo do Azure, Máquinas Virtuais do Azure, Docker e AKS (Serviço Kubernetes do Azure)
Versão do .NET: todas as versões do .NET com suporte oficial que não estejam em versão prévia
IDE: Visual Studio, VS Code ou linha de comando

Pré-requisitos

Você precisa de:

Um aplicativo ASP.NET Core funcional. Se precisar criar um aplicativo ASP.NET Core, siga este Tutorial do ASP.NET Core.
Uma referência a uma versão com suporte do pacote NuGet do Application Insights.
Uma cadeia de conexão do Application Insights válida. Essa cadeia de caracteres é necessária para enviar qualquer telemetria para o Application Insights. Se você precisar criar um recurso do Application Insights para obter uma cadeia de conexão, confira Criar um recurso do Application Insights.

Habilitar a telemetria do lado do servidor (Visual Studio) no Application Insights

No caso do Visual Studio para Mac, use as diretrizes manuais. Somente a versão Windows do Visual Studio dá suporte a esse procedimento.

Abra o projeto no Visual Studio.
Selecione Projeto>Adicionar Application Insights Telemetry.
Selecione Azure Application Insights>Avançar.
Escolha sua assinatura e a instância do Application Insights. Ou você pode criar uma instância com Criar. Selecione Avançar.
Adicione ou confirme sua cadeia de conexão do Application Insights Ela deve ser preenchida previamente com base em sua seleção na etapa anterior. Selecione Concluir.
Depois de adicionar o Application Insights ao seu projeto, verifique se você está usando a mais recente versão estável do SDK. Acesse Projeto>Gerenciar Pacotes NuGet>Microsoft.ApplicationInsights.AspNetCore. Se necessário, escolha Atualizar.

Habilitar a telemetria do lado do servidor (sem Visual Studio) no Application Insights

Instale o pacote NuGet do SDK do Application insights para ASP.NET Core.

Recomendamos sempre usar a versão estável mais recente. Encontre notas de versão completas para o SDK no repositório GitHub open-source .

O seguinte exemplo de código mostra as alterações a serem adicionadas ao arquivo do projeto .csproj:
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

Adicione AddApplicationInsightsTelemetry() à sua classe startup.cs ou program.cs. A escolha depende de sua versão do .NET Core.

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

Adicione builder.Services.AddApplicationInsightsTelemetry(); após o método WebApplication.CreateBuilder() em sua classe Program, como neste exemplo:

// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

Adicione services.AddApplicationInsightsTelemetry(); ao método ConfigureServices() na sua classe Startup, como neste exemplo:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // The following line enables Application Insights telemetry collection.
    services.AddApplicationInsightsTelemetry();

    // This code adds other services for your application.
    services.AddMvc();
}

Observação

Não há mais suporte para essa versão do .NET.

Definir a cadeia de conexão.

Embora seja possível fornecer uma cadeia de conexão como parte do argumento ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetry, recomendamos que você especifique a cadeia de conexão na configuração. O exemplo de código a seguir mostra como especificar uma cadeia de conexão no appsettings.json. Verifique se o appsettings.json foi copiado para a pasta raiz do aplicativo durante a publicação.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
Como alternativa, especifique a cadeia de conexão na variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING ou ApplicationInsights:ConnectionString no arquivo de configuração JSON.

Por exemplo:
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- Normalmente, APPLICATIONINSIGHTS_CONNECTION_STRING é usado em Aplicativos Web. Ele também pode ser usado em todos os locais compatíveis com esse SDK.
Observação

Uma cadeia de conexão especificada no código supera a variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING que, por sua vez, supera outras opções.

Segredos do usuário e outros provedores de configuração

Se você quiser armazenar a cadeia de conexão em segredos de usuário do ASP.NET Core ou recuperá-la de outro provedor de configuração, use a sobrecarga com um parâmetro Microsoft.Extensions.Configuration.IConfiguration. Um parâmetro de exemplo é services.AddApplicationInsightsTelemetry(Configuration);.

No Microsoft.ApplicationInsights.AspNetCore versão 2.15.0 e posterior, chamar services.AddApplicationInsightsTelemetry() lê automaticamente a cadeia de conexão de Microsoft.Extensions.Configuration.IConfiguration do aplicativo. Não é necessário fornecer IConfiguration explicitamente.

Se IConfiguration tiver carregado a configuração de vários provedores, então services.AddApplicationInsightsTelemetry priorizará a configuração de appsettings.json, independentemente da ordem na qual os provedores são adicionados. Use o método services.AddApplicationInsightsTelemetry(IConfiguration) para ler a configuração do IConfiguration sem esse tratamento preferencial para appsettings.json.

Execute seu aplicativo.

Execute o aplicativo e faça solicitações a ele. A telemetria agora deve fluir para o Application Insights. O SDK do Application Insights coleta automaticamente as solicitações da Web recebidas pelo aplicativo, juntamente com a telemetria a seguir.

Live Metrics

Métricas dinâmicas podem ser usadas para verificar rapidamente se o monitoramento de aplicativo com o Application Insights está configurado corretamente. A telemetria pode levar alguns minutos para aparecer no portal do Azure, mas o painel de métricas dinâmicas mostra o uso da CPU do processo em execução quase em tempo real. Ele também pode mostrar outras telemetrias, como solicitações, dependências, rastreamentos etc.

Habilitar métricas dinâmicas usando código para qualquer aplicativo .NET

Observação

As métricas dinâmicas são habilitadas por padrão durante a integração usando as instruções recomendadas para aplicativos .NET.

Para fazer a configuração manual das métricas dinâmicas:

Instale o pacote NuGet Microsoft.ApplicationInsights.PerfCounterCollector.
O exemplo de código de aplicativo de console a seguir mostra como configurar as métricas dinâmicas:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

O exemplo acima é para um aplicativo de console, mas o mesmo código pode ser usado em qualquer aplicativo .NET. Se quaisquer outros módulos de telemetria estiverem habilitados para coleta automática de telemetria, é importante garantir que a mesma configuração usada para inicializar esses módulos seja usada para o módulo de métricas ao vivo.

Logs do ILogger

A configuração padrão coleta logs ILogger Warning e logs mais graves. Para saber mais, confira Como fazer para personalizar a coleta de logs do ILogger?.

Dependências

Por padrão, a coleta de dependências está habilitada. Acompanhamento de dependência no Application Insights explica as dependências coletadas automaticamente e também contém etapas explicando como realizar o acompanhamento manual.

Contadores de desempenho

O suporte a contadores de desempenho no ASP.Net Core é limitado:

As versões 2.4.1 e posteriores do SDK coletarão contadores de desempenho se o aplicativo estiver sendo executado em Aplicativos Web (Windows).
As versões 2.7.1 e posteriores do SDK coletarão contadores de desempenho se o aplicativo estiver sendo executado no Windows e se destinar a netstandard2.0 ou posterior.
Para aplicativos destinados a .NET Framework, todas as versões do SDK dão suporte a contadores de desempenho.
As versões 2.8.0 e posteriores dão suporte ao contador de CPU/memória no Linux. Nenhum outro contador tem suporte no Linux. Para obter contadores do sistema no Linux e em outros ambientes não Windows, use EventCounters.

EventCounter

O EventCounterCollectionModule está habilitado por padrão. Para saber como configurar a lista de contadores a serem coletados, consulte Introdução ao EventCounters.

Enriquecer dados por meio de HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Habilitar telemetria do lado do cliente para aplicativos Web

As etapas anteriores são suficientes para ajudá-lo a começar a coletar a telemetria do lado do servidor. Se o seu aplicativo tiver componentes no lado do cliente, siga as próximas etapas para começar a coletar a telemetria de uso usando a injeção do Script do Carregador do SDK do JavaScript (Web) por configuração.

Em _ViewImports.cshtml, adicione a injeção:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

Em _Layout.cshtml, insira HtmlHelper no final da seção <head>, antes de qualquer outro script. Se você quiser gerar relatórios sobre qualquer telemetria personalizada de JavaScript da página, insira-a após este snippet:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

Como alternativa ao uso de FullScript, ScriptBody está disponível a partir da versão 2.14 do SDK do Application Insights para o ASP.NET Core. Use ScriptBody se você precisar controlar a tag <script> para definir uma Política de Segurança de Conteúdo:

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

Os nomes de arquivo .cshtml referenciados anteriormente são de um modelo de aplicativo MVC padrão. Se você quiser habilitar corretamente o monitoramento do lado do cliente para o aplicativo, o Script de Carregador de SDK do JavaScript (web) deverá aparecer na seção <head> de cada página do aplicativo que deseja monitorar. Adicione o Script de Carregador de SDK do JavaScript (Web) a _Layout.cshtml em um modelo de aplicativo para habilitar o monitoramento do lado do cliente.

Se o projeto não incluir _Layout.cshtml, você ainda poderá adicionar o monitoramento do lado do cliente adicionando o Script de Carregador de SDK do JavaScript (Web) a um arquivo equivalente que controla o <head> de todas as páginas no aplicativo. Como alternativa, é possível adicionar o Script de Carregador de SDK do JavaScript (Web) a várias páginas, mas não recomendamos isso.

Observação

A injeção de JavaScript fornece uma experiência de configuração padrão. Se você precisar de alguma configuração além da configuração da cadeia de conexão, precisará remover a injeção automática conforme descrito e adicionar manualmente o SDK do JavaScript.

Configurar o SDK do Application Insights

Você pode personalizar o SDK do Application Insights para o ASP.NET Core para alterar a configuração padrão. Os usuários do SDK do Application Insights para ASP.NET podem estar familiarizados com a alteração da configuração usando ApplicationInsights.config ou modificando TelemetryConfiguration.Active. No caso do ASP.NET Core, faça quase todas as alterações de configuração no método ConfigureServices() da classe Startup.cs, a menos que haja orientação em contrário. As seções a seguir oferecem mais informações.

Observação

Em aplicativos ASP.NET Core, não é possível alterar a configuração modificando TelemetryConfiguration.Active.

Uso do ApplicationInsightsServiceOptions

Você pode modificar algumas configurações comuns passando ApplicationInsightsServiceOptions para AddApplicationInsightsTelemetry, como neste exemplo:

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

Observação

Não há mais suporte para essa versão do .NET.

Esta tabela tem a lista completa das configurações ApplicationInsightsServiceOptions:

Configuração	Descrição	Padrão
EnablePerformanceCounterCollectionModule	Habilita/desabilita `PerformanceCounterCollectionModule`.	True
EnableRequestTrackingTelemetryModule	Habilita/desabilita `RequestTrackingTelemetryModule`.	True
EnableEventCounterCollectionModule	Habilita/desabilita `EventCounterCollectionModule`.	True
EnableDependencyTrackingTelemetryModule	Habilita/desabilita `DependencyTrackingTelemetryModule`.	True
EnableAppServicesHeartbeatTelemetryModule	Habilita/desabilita `AppServicesHeartbeatTelemetryModule`.	True
EnableAzureInstanceMetadataTelemetryModule	Habilita/desabilita `AzureInstanceMetadataTelemetryModule`.	True
EnableQuickPulseMetricStream	Habilitar/desabilitar o recurso LiveMetrics.	Verdadeiro
EnableAdaptiveSampling	Habilita/Desabilita a Amostragem Adaptável.	Verdadeiro
EnableHeartbeat	Habilitar/desabilitar o recurso de pulsações. Ele envia periodicamente (padrão de 15 min) uma métrica personalizada chamada `HeartbeatState` com informações sobre o runtime, como a versão do .NET e informações do ambiente do Azure, se aplicável.	Verdadeiro
AddAutoCollectedMetricExtractor	Habilitar/desabilitar o `AutoCollectedMetrics extractor`. Esse processador de telemetria envia métricas pré-agregadas sobre solicitações/dependências antes que a amostragem ocorra.	True
RequestCollectionOptions.TrackExceptions	Habilitar/desabilitar o relatório de monitoramento de exceções sem tratamento pelo módulo de coleta de solicitações.	Falso em `netstandard2.0` (porque as exceções são acompanhadas com `ApplicationInsightsLoggerProvider`). Caso contrário, true.
EnableDiagnosticsTelemetryModule	Habilita/desabilita `DiagnosticsTelemetryModule`. Desabilitar faz com que as seguintes configurações sejam ignoradas: `EnableHeartbeat`, `EnableAzureInstanceMetadataTelemetryModule` e `EnableAppServicesHeartbeatTelemetryModule`.	True

Confira as definições configuráveis no ApplicationInsightsServiceOptions para obter a lista mais atualizada.

Recomendações de configuração para o SDK do Microsoft.ApplicationInsights.AspNetCore 2.15.0 e posterior

No SDK do Microsoft.ApplicationInsights.AspNetCore SDK versão 2.15.0 e posterior, defina todas as configurações disponíveis em ApplicationInsightsServiceOptions, incluindo ConnectionString. Use a instância de IConfiguration do aplicativo. As configurações devem estar na seção ApplicationInsights, conforme mostrado no exemplo a seguir. A seção a seguir de appsettings.json configura a cadeia de conexão, desabilita a amostragem adaptável e a coleta do contador de desempenho.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Se builder.Services.AddApplicationInsightsTelemetry(aiOptions) for para ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) para ASP.NET Core 3.1 e anteriores for usado, ele substituirá as configurações de Microsoft.Extensions.Configuration.IConfiguration.

amostragem

O SDK do Application Insights para o ASP.NET Core dá suporte à amostragem adaptável e de taxa fixa. A amostragem adaptável está habilitada por padrão.

Para obter mais informações, confira Configurar a amostragem adaptável para aplicativos ASP.NET Core.

Adicionar TelemetryInitializers

Use inicializadores de telemetria quando quiser enriquecer a telemetria com mais informações.

Adicione qualquer novo TelemetryInitializer ao contêiner DependencyInjection, conforme mostrado no código a seguir. O SDK seleciona automaticamente qualquer TelemetryInitializer que seja adicionado ao contêiner DependencyInjection.

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Observação

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funciona com inicializadores simples. Para outros, builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); é necessário.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

Observação

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funciona com inicializadores simples. Para outros, services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); é necessário. Não há mais suporte para essa versão do .NET.

Remover TelemetryInitializers

Os inicializadores de telemetria estão presentes por padrão. Para remover todos os inicializadores de telemetria, ou alguns específicos, use o código de exemplo a seguir depois de chamar AddApplicationInsightsTelemetry().

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // Remove a specific built-in telemetry initializer
    var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                        (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
    if (tiToRemove != null)
    {
        services.Remove(tiToRemove);
    }

    // Remove all initializers
    // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
    services.RemoveAll(typeof(ITelemetryInitializer));
}

Observação

Não há mais suporte para essa versão do .NET.

Adicionar processadores de telemetria

Você pode adicionar processadores de telemetria personalizados ao TelemetryConfiguration usando o método de extensão AddApplicationInsightsTelemetryProcessor no IServiceCollection. Você usa processadores de telemetria em cenários de filtragem avançada. Use o seguinte exemplo:

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

Observação

Não há mais suporte para essa versão do .NET.

Configurar ou remover TelemetryModules padrão

O Application Insights coleta automaticamente a telemetria sobre cargas de trabalho específicas sem a necessidade de acompanhamento manual do usuário.

Os módulos de coleta automática a seguir estão habilitados por padrão. Esses módulos são responsáveis por coletar automaticamente a telemetria. Você pode desabilitá-los ou configurá-los para alterar o comportamento padrão deles.

RequestTrackingTelemetryModule: coleta RequestTelemetry de solicitações de entrada da Web.
DependencyTrackingTelemetryModule: coleta DependencyTelemetry de chamadas HTTP de saída e de chamadas SQL.
PerformanceCollectorModule: coleta PerformanceCounters no Windows.
QuickPulseTelemetryModule: Coleta telemetria para mostrar no painel de métricas ao vivo.
AppServicesHeartbeatTelemetryModule: coleta pulsações (que são enviadas como métricas personalizadas) sobre o ambiente do Serviço de Aplicativo em que o aplicativo está hospedado.
AzureInstanceMetadataTelemetryModule: coleta pulsações (que são enviadas como métricas personalizadas) sobre o ambiente de VM do Azure em que o aplicativo está hospedado.
EventCounterCollectionModule: coleta EventCounters. Este módulo é um novo recurso e está disponível no SDK versão 2.8.0 e posterior.

Para configurar qualquer TelemetryModule padrão, use o método de extensão ConfigureTelemetryModule<T> em IServiceCollection, conforme mostrado no seguinte exemplo:

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // The following configures DependencyTrackingTelemetryModule.
    // Similarly, any other default modules can be configured.
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
            {
                module.EnableW3CHeadersInjection = true;
            });

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
            }
        );

    // The following removes PerformanceCollectorModule to disable perf-counter collection.
    // Similarly, any other default modules can be removed.
    var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

Observação

Não há mais suporte para essa versão do .NET.

Nas versões 2.12.2 e posteriores, o ApplicationInsightsServiceOptions inclui uma opção fácil para desabilitar qualquer um dos módulos padrão.

Configure um canal de telemetria

O canal de telemetria padrão é ServerTelemetryChannel. O exemplo a seguir mostra como substituí-lo.

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

using Microsoft.ApplicationInsights.Channel;

public void ConfigureServices(IServiceCollection services)
{
    // Use the following to replace the default channel with InMemoryChannel.
    // This can also be applied to ServerTelemetryChannel.
    services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

    services.AddApplicationInsightsTelemetry();
}

Observação

Não há mais suporte para essa versão do .NET.

Observação

Se quiser liberar o buffer, consulte Liberando dados. Por exemplo,você poderá querer liberar o buffer se estiver usando o SDK em um aplicativo que é desligado.

Desabilitar a telemetria dinamicamente

Se quiser desabilitar a telemetria de modo condicional e dinâmico, você pode resolver a instância TelemetryConfiguration com um contêiner de injeção de dependência do ASP.NET Core em qualquer lugar do seu código e definir o sinalizador DisableTelemetry nele.

ASP.NET Core 6 e versões posteriores
ASP.NET Core 5 e versões anteriores

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
{
    configuration.DisableTelemetry = true;
    ...
}

Observação

Não há mais suporte para essa versão do .NET.

O exemplo de código anterior impede o envio de telemetria para o Application Insights. Ele não impede que nenhum módulo de coleta automática colete telemetria. Se você desejar remover um módulo de coleção automática específico, consulte Remover o módulo de telemetria.

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

O Application Insights dá suporte ao ASP.NET Core 3.1?

O ASP.NET Core 3.1 não tem mais suporte da Microsoft.

O SDK do Application Insights para ASP.NET Core versão 2.8.0 e Visual Studio 2019 ou posterior pode ser usado com aplicativos ASP.NET Core 3.1.

Como posso acompanhar a telemetria que não é coletada automaticamente?

Obtenha uma instância de TelemetryClient usando a injeção de construtor e chame o método TrackXXX() necessário nela. Não recomendamos criar novas instâncias TelemetryClient ou TelemetryConfiguration em um aplicativo ASP.NET Core. Uma instância singleton do TelemetryClient já está registrada no contêiner de DependencyInjection, que compartilha o TelemetryConfiguration com o restante da telemetria. Crie uma instância de TelemetryClient apenas se ela precisar de uma configuração separada do restante da telemetria.

O exemplo a seguir mostra como acompanhar mais a telemetria de um controlador.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Para obter mais informações sobre relatórios de dados personalizados no Application Insights, confira Referência de API das métricas personalizadas do Application Insights. Uma abordagem semelhante pode ser usada para enviar métricas personalizadas para o Application Insights usando a API GetMetric.

Como fazer a captura do corpo da solicitação e da resposta na minha telemetria?

O ASP.NET Core tem suporte integrado para registrar informações de solicitação/resposta HTTP (incluindo corpo) via ILogger. Recomenda-se aproveitar isso. Isso pode potencialmente expor informações de identificação pessoal (PII) em telemetria e pode fazer com que os custos (custos de desempenho e faturação do Application Insights) aumentem significativamente, por isso avalie cuidadosamente os riscos antes de utilizar isto.

Como personalizar a coleta de logs do ILogger?

A configuração padrão do Application Insights é capturar apenas o Aviso e logs mais graves.

Capture informações e logs menos graves alterando a configuração de log do provedor do Application Insights da seguinte maneira.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

É importante observar que o exemplo seguinte não fará com que o provedor do Application Insights capture logs Information. Ele não os captura porque o SDK adiciona um filtro de log padrão que instrui o ApplicationInsights a capturar os logs Warning e mais graves. O Application Insights requer uma substituição explícita.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Para obter mais informações, confira a Configuração do ILogger.

Alguns modelos do Visual Studio usavam o método de extensão UseApplicationInsights() em IWebHostBuilder para habilitar o Application Insights. Esse uso ainda é válido?

Embora o método de extensão UseApplicationInsights() ainda tenha suporte, ele está marcado como obsoleto no SDK do Application insights versão 2.8.0 e posterior. Ele é removido na próxima versão principal do SDK. Para habilitar a telemetria do Application Insights, use o AddApplicationInsightsTelemetry(), pois ele fornece sobrecargas para controlar algumas configurações. Além disso, em aplicativos ASP.NET Core 3.X, services.AddApplicationInsightsTelemetry() é a única maneira de habilitar o Application Insights.

Estou implantando meu aplicativo ASP.NET Core em aplicativos Web. Ainda devo habilitar a extensão Application Insights em aplicativos Web?

Se o SDK estiver instalado no momento da compilação, conforme mostrado neste artigo, você não precisará habilitar a extensão Application Insights no portal do Serviço de Aplicativo. Se a extensão estiver instalada, ela recuará quando detectar que o SDK já foi adicionado. Se você habilitar o Application Insights da extensão, não precisará instalar e atualizar o SDK. Porém, se você habilitar o Application Insights seguindo as instruções deste artigo, terá mais flexibilidade porque:

A telemetria do Application Insights continuará a funcionar em:
- Todos os sistemas operacionais, incluindo Windows, Linux e Mac.
- Todos os modos de publicação, incluindo modos autocontidos ou dependentes da estrutura.
- Todas as estruturas de destino, incluindo o .NET Framework completo.
- Todas as opções de hospedagem, incluindo aplicativos Web, VMs, Linux, contêineres, AKS e hospedagem não Azure.
- Todas as versões do .NET Core, incluindo as versões preliminares.
Você pode ver a telemetria localmente quando estiver depurando do Visual Studio.
Você pode acompanhar mais telemetria personalizada usando a API TrackXXX().
Você tem controle total sobre a configuração.

Posso habilitar o monitoramento do Application Insights usando ferramentas como o Agente do Application Insights do Azure Monitor (anteriormente Status Monitor v2)?

Sim. No Agente do Application Insights 2.0.0-beta1 e posterior, há suporte para os aplicativos ASP.NET Core hospedados no IIS.

Se eu executar meu aplicativo no Linux, todos os recursos terão suporte?

Sim. O suporte a recursos no SDK é o mesmo em todas as plataformas, com as seguintes exceções:

O SDK coleta contadores de eventos no Linux porque há suporte para os contadores de desempenho apenas no Windows. A maioria das métricas são as mesmas.

Esse SDK é compatível com Worker Services?

Não. Use Application Insights para aplicativos Worker Service (aplicativos não HTTP) para serviços de trabalho.

Como posso desinstalar o SDK?

Para remover o Application Insights, você precisará remover os pacotes NuGet e as referências da API em seu aplicativo. Você pode desinstalar pacotes NuGet usando o Gerenciador de Pacotes NuGet no Visual Studio.

Observação

Essas instruções são para desinstalar o SDK do ASP.NET Core. Se você precisar desinstalar o SDK do ASP.NET, consulte Como posso desinstalar o SDK do ASP.NET?.

Desinstale o pacote Microsoft.ApplicationInsights.AspNetCore usando o Gerenciador de Pacotes NuGet.
Para remover o Application Insights completamente, verifique e exclua manualmente o código ou os arquivos adicionados juntamente com todas as chamadas à API que você adicionou no seu projeto. Para obter mais informações, confira O que é criado ao adicionar o SDK do Application Insights?.

O que é criado ao adicionar o SDK do Application Insights?

Quando você adiciona o Application Insights ao seu projeto, ele cria arquivos e adiciona código a alguns dos seus arquivos. A simples desinstalação dos Pacotes NuGet nem sempre descarta os arquivos e o código. Para remover completamente Application Insights, você deve verificar e excluir manualmente o código ou os arquivos adicionados juntamente com as chamadas à API que você adicionou em seu projeto.

Quando você adiciona o Application Insights Telemetry a um projeto de modelo do ASP.NET Core do Visual Studio, ele adiciona os seguintes códigos:

[Nome do seu projeto]. csproj

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

Appsettings.json:

"ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

ConnectedService.json

{
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

Startup.cs

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

Como posso desativar a correlação de telemetria?

Para desabilitar a correlação de telemetria no código, veja <ExcludeComponentCorrelationHttpHeadersOnDomains> em Application Insights para aplicativos de console.

Solução de problemas

Confira o artigo de solução de problemas dedicado.

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

Os SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST para nossos pontos de extremidade de ingestão. Você pode testar a conectividade do servidor Web ou do computador host do aplicativo para os pontos de extremidade do serviço de ingestão usando clientes REST brutos do PowerShell ou comandos curl. Confira Solucionar problemas de telemetria de aplicativo ausente no Application Insights do Azure Monitor.

SDK do código-fonte aberto

Ler e contribuir para o código.

Para obter as atualizações e as correções de bugs mais recentes, confira as notas sobre a versão.

Notas de versão

Para a versão 2,12 e mais recente: SDKs do .net (incluindo ASP.net, ASP.NET Core e os adaptadores de log)

Nossas Atualizações de Serviço também resumem as principais melhorias do Application Insights.

Próximas etapas

Explore os fluxos dos usuários para compreender como os usuários se movem pelo aplicativo.
Configure uma coleta de instantâneos para ver o estado do código-fonte e as variáveis no momento em que uma exceção é lançada.
Use a API para enviar os seus eventos e métricas para uma exibição detalhada do desempenho e do uso do aplicativo.
Use os Testes de disponibilidade para verificar seu aplicativo constante em todo o mundo.
Saiba mais sobre a injeção de dependência no ASP.NET Core.

Compartilhar via

Application Insights para aplicativos ASP.NET Core

Cenários com suporte

Pré-requisitos

Habilitar a telemetria do lado do servidor (Visual Studio) no Application Insights

Habilitar a telemetria do lado do servidor (sem Visual Studio) no Application Insights

Segredos do usuário e outros provedores de configuração

Execute seu aplicativo.

Live Metrics

Habilitar métricas dinâmicas usando código para qualquer aplicativo .NET

Logs do ILogger

Dependências

Contadores de desempenho

EventCounter

Enriquecer dados por meio de HTTP

Habilitar telemetria do lado do cliente para aplicativos Web

Configurar o SDK do Application Insights

Uso do ApplicationInsightsServiceOptions

Recomendações de configuração para o SDK do Microsoft.ApplicationInsights.AspNetCore 2.15.0 e posterior

amostragem

Adicionar TelemetryInitializers

Remover TelemetryInitializers

Adicionar processadores de telemetria

Configurar ou remover TelemetryModules padrão

Configure um canal de telemetria

Desabilitar a telemetria dinamicamente

Perguntas frequentes

O Application Insights dá suporte ao ASP.NET Core 3.1?

Como posso acompanhar a telemetria que não é coletada automaticamente?

Como fazer a captura do corpo da solicitação e da resposta na minha telemetria?

Como personalizar a coleta de logs do ILogger?

Alguns modelos do Visual Studio usavam o método de extensão UseApplicationInsights() em IWebHostBuilder para habilitar o Application Insights. Esse uso ainda é válido?

Estou implantando meu aplicativo ASP.NET Core em aplicativos Web. Ainda devo habilitar a extensão Application Insights em aplicativos Web?

Posso habilitar o monitoramento do Application Insights usando ferramentas como o Agente do Application Insights do Azure Monitor (anteriormente Status Monitor v2)?

Se eu executar meu aplicativo no Linux, todos os recursos terão suporte?

Esse SDK é compatível com Worker Services?

Como posso desinstalar o SDK?

O que é criado ao adicionar o SDK do Application Insights?

Como posso desativar a correlação de telemetria?

Solução de problemas

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

SDK do código-fonte aberto

Notas de versão

Próximas etapas

Comentários

Recursos adicionais