Configurar o SDK do Application Insights com ApplicationInsights.config ou.xml

  • Artigo

O SDK do .NET do Application Insights é composto por vários pacotes NuGet. O pacote principal fornece a API para enviar telemetria ao Application Insights. Mais pacotes fornecem módulos e inicializadores de telemetria para rastreamento automático de telemetria de seu aplicativo e o respectivo contexto. Ao ajustar o arquivo de configuração, você pode habilitar ou desabilitar módulos de telemetria e inicializadores. Você também pode definir parâmetros para alguns deles.

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, confira Habilitar o OpenTelemetry do Azure Monitor para aplicativos .NET, Node.js, Python e Java.

O arquivo de configuração é nomeado como ApplicationInsights.config ou ApplicationInsights.xml. O nome depende do tipo do aplicativo. Ele é adicionado automaticamente ao seu projeto quando você instala a maioria das versões do SDK. Por padrão, quando você usa a experiência automatizada dos projetos de modelo do Visual Studio que dão suporte a Adicionar>Application Insights Telemetry, o arquivo ApplicationInsights.config é criado na pasta raiz do projeto. Quando ele é compilado, ele é copiado para a pasta bin. Também é adicionado a um aplicativo web pelo Application Insights Agent em um servidor IIS. O arquivo de configuração será ignorado se a extensão para o site do Azure ou a extensão para VMs do Azure e o conjuntos de dimensionamento de máquinas virtuais forem usados.

Não há um arquivo equivalente para controlar o SDK em uma página da Web.

Este documento descreve as seções que você vê no arquivo de configuração, como elas controlam os componentes do SDK, e quais pacotes NuGet carregam esses componentes.

Observação

As instruções ApplicationInsights.config e .xml não se aplicam ao SDK do .NET Core. Para configurar aplicativos ASP.NET Core, siga as instruções no Application Insights para aplicativos ASP.NET Core.

Módulos de telemetria (ASP.NET)

Cada módulo de telemetria coleta um tipo específico de dados e usa o API principal para enviar os dados. Os módulos são instalados por diferentes pacotes NuGet, que também adicionam as linhas necessárias para o arquivo. config.

Há um nó no arquivo de configuração para cada módulo. Para desabilitar um módulo, exclua o nó ou remova o comentário dele.

acompanhamento de dependência

Dependency tracking coleta a telemetria sobre chamadas para bancos de dados e serviços externos e torna o seu aplicativo. Para permitir que esse módulo funcione em um servidor IIS, é necessário instalar o Application Insights Agent.

Você também pode gravar seu próprio código de rastreamento de dependência usando a API TrackDependency.

As dependências podem ser coletadas automaticamente sem modificar seu código usando a anexação baseada em agente (sem código). Para usá-la em aplicativos Web do Azure, habilite a extensão do Application Insights. Para usá-la na VM do Azure ou em um conjunto de dimensionamento de máquinas virtuais do Azure, habilite a extensão de monitoramento de aplicativo para VMs e conjuntos de dimensionamento de máquinas virtuais.

Coletor de desempenho

O coletor de desempenhocoleta contadores de desempenho do sistema, como CPU, memória e carregamento de rede de instalações do IIS. É possível especificar quais contadores coletar, incluindo contadores de desempenho que você mesmo configurou.

Telemetria de diagnóstico do Application Insights

A classe DiagnosticsTelemetryModule relata erros no próprio código de instrumentação do Application Insights. Exemplos são se o código não puder acessar contadores de desempenho ou se ITelemetryInitializer gerar uma exceção. A telemetria de rastreamento rastreada por esse módulo aparece na Pesquisa de Diagnóstico.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights . Se você instalar apenas esse pacote, o arquivo applicationinsights. config não é criado automaticamente.

Modo de desenvolvedor

A classe DeveloperModeWithDebuggerAttachedTelemetryModule força o Application Insights TelemetryChannel a enviar dados imediatamente, um item de telemetria por vez, quando um depurador é anexado ao processo do aplicativo. Esse design reduz o tempo entre o momento em que o aplicativo rastreia a telemetria e quando ela aparece no portal do Application Insights. Faz com uma sobrecarga significativa na largura de banda de CPU e rede.

Acompanhamento de solicitação da Web

O acompanhamento de solicitação da Web relata o tempo de resposta e o código de resultado das solicitações HTTP.

Acompanhamento de exceções

A classe ExceptionTrackingTelemetryModule rastreia exceções sem tratamento no aplicativo Web. Para saber mais, confira Falhas e exceções.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Pacote NuGet Microsoft.ApplicationInsights.Web.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: rastreia a tarefa não observada. Exceções.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: rastreia as exceções sem tratamento para funções de trabalho, serviços Windows e aplicativos de console.
  • Application Insights Windows Server .

Acompanhamento de EventSource

A classe EventSourceTelemetryModule permite configurar eventos EventSource para serem enviados ao Application Insights como rastreamentos. Para obter informações sobre o acompanhamento de eventos EventSource, consulte Usar eventos EventSource.

Acompanhamento de evento ETW

A classe EtwCollectorTelemetryModule permite configurar eventos de provedores ETW para serem enviados ao Application Insights como rastreamentos. Para obter informações sobre o acompanhamento de eventos ETW, consulte Usar eventos ETW.

Microsoft.ApplicationInsights

O pacote Microsoft.ApplicationInsights fornece a API core do SDK. Os outros módulos de telemetria usam essa API. Também é possível usá-la para definir sua própria telemetria.

  • Nenhuma entrada em ApplicationInsights.config.
  • Microsoft.ApplicationInsights . Se você acabou de instalar este NuGet, nenhum arquivo. config será gerado.

Canal de telemetria

O canal de telemetria gerencia o armazenamento em buffer e a transmissão de telemetria ao serviço Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel é o canal padrão para aplicativos Web. Ele armazena os dados em buffer na memória e emprega mecanismos de repetição e armazenamento em disco local para uma entrega de telemetria mais confiável.
  • Microsoft.ApplicationInsights.InMemoryChannel é um canal de telemetria leve. Ele será usado se nenhum outro canal estiver configurado.

Inicializadores de telemetria (ASP.NET)

Os inicializadores de telemetria definem propriedades de contexto que são enviadas com cada item de telemetria.

Você pode escrever seus próprios inicializadores para definir as propriedades de contexto.

Todos os inicializadores padrão foram configurados pelos pacotes NuGet WindowsServer ou Web:

  • AccountIdTelemetryInitializer define a propriedade AccountId.

  • AuthenticatedUserIdTelemetryInitializer define a propriedade AuthenticatedUserId como definida pelo SDK do JavaScript.

  • AzureRoleEnvironmentTelemetryInitializer atualiza as propriedades RoleName e RoleInstance do contexto Device para todos os itens de telemetria com informações extraídas do ambiente de runtime do Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializer atualiza a Version propriedade do Component contexto para todos os itens de telemetria com o valor extraído do arquivo BuildInfo.config produzido pelo MS Build.

  • ClientIpHeaderTelemetryInitializer atualiza a propriedade Ip do contexto Location de todos os itens de telemetria baseados no cabeçalho HTTP X-Forwarded-For da solicitação.

  • DeviceTelemetryInitializer atualiza as propriedades a seguir do contexto Device para todos os itens de telemetria.

    • Type é definido como PC.
    • Id é definido para o nome de domínio do computador onde o aplicativo Web está em execução.
    • OemName é definido como o valor extraído do campo Win32_ComputerSystem.Manufacturer usando WMI.
    • Model é definido como o valor extraído do campo Win32_ComputerSystem.Model usando WMI.
    • NetworkType é definido como o valor extraído da propriedade NetworkInterface.
    • Language é definido como o nome da propriedade CurrentCulture.

  • DomainNameRoleInstanceTelemetryInitializer atualiza a propriedade RoleInstance do contexto Device para todos os itens de telemetria com o nome de domínio do computador onde o aplicativo Web está em execução.

  • OperationNameTelemetryInitializer atualiza a propriedade Name das propriedades RequestTelemetry e Name do contexto Operation de todos os itens de telemetria baseados no método HTTP, incluindo os nomes do controlador MVC do ASP.NET e a ação invocada para processar a solicitação.

  • OperationIdTelemetryInitializer ou OperationCorrelationTelemetryInitializer atualiza a propriedade de contexto Operation.Id de todos os itens de telemetria rastreados ao manipular uma solicitação com o RequestTelemetry.Id gerado automaticamente.

  • SessionTelemetryInitializer atualiza a propriedade Id do contexto Session para todos os itens de telemetria com valor extraído do cookie ai_session gerado pelo código de instrumentação do JavaScript ApplicationInsights em execução no navegador do usuário.

  • SyntheticTelemetryInitializer ou SyntheticUserAgentTelemetryInitializer atualiza as propriedades de contexto User, Session e Operation de todos os itens de telemetria rastreados ao lidar com uma solicitação de uma fonte sintética, como um teste de disponibilidade ou um bot do mecanismo de pesquisa. Por padrão, o Metrics Explorer não exibe telemetria sintética.

    Os <Filters> definem as propriedades de identificação das solicitações.

  • UserTelemetryInitializer atualiza as propriedades Id e AcquisitionDate do contexto User para todos os itens de telemetria com valores extraídos do cookie ai_user gerado pelo código de instrumentação do JavaScript do Application Insights em execução no navegador do usuário.

  • WebTestTelemetryInitializer define a ID de usuário, a ID de sessão e as propriedades de fonte sintética para solicitações HTTP provenientes dos testes de disponibilidade. Os <Filters> definem as propriedades de identificação das solicitações.

Para aplicativos .NET em execução no Azure Service Fabric, você pode incluir o pacote do NuGet Microsoft.ApplicationInsights.ServiceFabric. Este pacote inclui uma propriedade FabricTelemetryInitializer, que adiciona propriedades do Service Fabric a itens de telemetria. Para obter mais informações, consulte a página do GitHub sobre as propriedades adicionadas por este pacote do NuGet.

Processadores de telemetria (ASP.NET)

Processadores de telemetria podem filtrar e modificar cada item de telemetria antes de serem enviados do SDK para o portal.

Você pode escrever seus próprios processadores de telemetria.

Processador de telemetria de amostragem adaptável (da 2.0.0-beta3)

Essa funcionalidade é habilitada por padrão. Se seu aplicativo envia uma quantidade de telemetria considerável, esse processador remove parte dela.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

O parâmetro fornece o destino que o algoritmo tenta obter. Cada instância do SDK funciona de forma independente. Assim, se o servidor for um cluster de vários computadores, o volume real de telemetria será multiplicado adequadamente.

Saiba mais sobre amostragem.

Processador de telemetria de amostragem de taxa fixa (da 2.0.0-beta1)

Também há um processador de telemetria de amostragem padrão (a partir da 2.0.1):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

Veja exemplos de código de cadeia de conexão.

InstrumentationKey

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.

Essa configuração determina o recurso do Application Insights em que seus dados aparecem. Normalmente, você cria um recurso separado com uma chave separada para cada um dos aplicativos.

Se você quiser definir a chave dinamicamente, por exemplo, caso queira enviar os resultados do seu aplicativo para outros recursos, é possível omitir a chave do arquivo de configuração e defini-lo no código.

Para definir a chave para todas as instâncias de TelemetryClient, incluindo módulos de telemetria padrão, execute esta etapa em um método de inicialização, como global.aspx.cs em um serviço ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Se quiser enviar um conjunto específico de eventos para um recurso diferente, você pode definir a chave para um cliente de telemetria específico:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Para obter uma nova chave, crie um novo recurso no portal do Application Insights.

Provedor ApplicationId

O provedor está disponível desde a v2.6.0.

A finalidade desse provedor é procurar uma ID de aplicativo com base em uma chave de instrumentação. A ID do aplicativo está incluída em RequestTelemetry e DependencyTelemetry e é usada para determinar a correlação no portal.

Essa funcionalidade está disponível configurando TelemetryConfiguration.ApplicationIdProvider no código ou no arquivo de configuração.

Interface: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Fornecemos duas implementações no SDK Microsoft.ApplicationInsights: ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Esse wrapper é destinado à API de Perfil. Ele limitará as solicitações e os resultados do cache.

Este provedor é adicionado ao arquivo de configuração quando você instala Microsoft.ApplicationInsights.DependencyCollector ou Microsoft.ApplicationInsights.Web.

Essa classe tem uma propriedade opcional ProfileQueryEndpoint. Por padrão, ela é definida como https://dc.services.visualstudio.com/api/profiles/{0}/appId. Se for necessário configurar um proxy para essa configuração, é recomendável usar um proxy de endereço básico e incluir "/api/profiles/{0}/appId". Um {0} é substituído em runtime mediante solicitação com a chave de instrumentação.

Exemplo de configuração por ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemplo de Configuração por código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Esse provedor estático depende dos pares de ID do aplicativo/chave de instrumentação configurados.

Essa classe tem a propriedade Defined, que é um Dictionary<string,string> dos pares de chave de instrumentação/ID do aplicativo.

Essa classe tem a propriedade opcional Next, que pode ser utilizada para configurar outro provedor a ser usado quando uma chave de instrumentação solicitada não existir na configuração.

Exemplo de configuração por ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemplo de Configuração por código

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Configurar a coleta de instantâneo para aplicativos ASP.NET

Configurar uma coleção de instantâneos para aplicativos ASP.NET.

Próximas etapas

Saiba mais sobre a API