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

  • Artigo

O SDK do .NET do Application Insights consiste em muitos pacotes NuGet. O pacote principal fornece a API para enviar telemetria para o Application Insights. Mais pacotes fornecem módulos de telemetria e inicializadores para rastrear automaticamente a telemetria do seu aplicativo e seu contexto. Ajustando 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.

Nota

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

O arquivo de configuração é nomeado ApplicationInsights.config ou ApplicationInsights.xml. O nome depende do tipo do seu pedido. 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 oferecem suporte a Telemetria Add>Application Insights, o ApplicationInsights.config arquivo é criado na pasta raiz do projeto. Quando é compilado, é copiado para a pasta bin. Ele 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 sites do Azure ou a extensão para VMs do Azure e conjuntos de dimensionamento de máquinas virtuais for usada.

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

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

Nota

As ApplicationInsights.config instruções e .xml não se aplicam ao SDK do .NET Core. Para configurar aplicativos .NET Core, siga as instruções em 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 a API principal para enviar os dados. Os módulos são instalados por diferentes pacotes NuGet, que também adicionam as linhas necessárias ao arquivo .config.

Há um nó no arquivo de configuração para cada módulo. Para desativar um módulo, exclua o nó ou comente-o.

Rastreio de dependências

O controle de dependência coleta telemetria sobre chamadas que seu aplicativo faz para bancos de dados e serviços e bancos de dados externos. Para permitir que esse módulo funcione em um servidor IIS, você precisa instalar o Application Insights Agent.

Você também pode escrever seu próprio código de controle 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á-lo em aplicativos Web do Azure, habilite a extensão Application Insights. Para usá-lo em uma VM do Azure ou em um conjunto de dimensionamento de máquina virtual do Azure, habilite a extensão de Monitoramento de Aplicativo para VMs e conjuntos de escala de máquina virtual.

Coletor de desempenho

O coletor de desempenho coleta contadores de desempenho do sistema, como CPU, memória e carga de rede de instalações do IIS. Você pode especificar quais contadores coletar, incluindo contadores de desempenho que você mesmo configurou.

Telemetria de diagnóstico do Application Insights

A DiagnosticsTelemetryModule classe 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 lançar uma exceção. A telemetria de rastreamento rastreada por este módulo aparece na Pesquisa de diagnóstico.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Pacote NuGet Microsoft.ApplicationInsights . Se você instalar apenas este pacote, o arquivo ApplicationInsights.config não será criado automaticamente.

Modo de desenvolvedor

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

Rastreamento de solicitações da Web

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

Rastreamento de exceções

A ExceptionTrackingTelemetryModule classe rastreia exceções não tratadas em seu aplicativo Web. Para obter mais informações, consulte Falhas e exceções.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Pacote NuGet Microsoft.ApplicationInsights.Web .
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Rastreia tarefas não observadas. exceções.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Rastreia exceções não tratadas para funções de trabalho, serviços do Windows e aplicativos de console.
  • Pacote NuGet do Windows Server do Application Insights.

Rastreamento EventSource

A EventSourceTelemetryModule classe permite configurar eventos EventSource a serem enviados para o Application Insights como rastreamentos. Para obter informações sobre como controlar eventos EventSource, consulte Usando eventos EventSource.

Rastreamento de eventos ETW

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

Microsoft.ApplicationInsights

O Microsoft.ApplicationInsights pacote fornece a API principal do SDK. Os outros módulos de telemetria usam essa API. Você também pode usá-lo para definir sua própria telemetria.

Canal de telemetria

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

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel é o canal padrão para aplicativos Web. Ele armazena 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 é usado se nenhum outro canal estiver configurado.

Inicializadores de telemetria (ASP.NET)

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

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

Os inicializadores padrão são todos definidos pelos pacotes NuGet da Web ou do WindowsServer:

  • AccountIdTelemetryInitializer Define a AccountId propriedade.

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

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

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

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

  • DeviceTelemetryInitializer Atualiza as seguintes propriedades do contexto para todos os itens de Device telemetria.

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

  • DomainNameRoleInstanceTelemetryInitializer Atualiza a RoleInstance Device propriedade do contexto para todos os itens de telemetria com o nome de domínio do computador onde o aplicativo Web está sendo executado.

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

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

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

  • SyntheticTelemetryInitializer ou SyntheticUserAgentTelemetryInitializer atualiza as Userpropriedades , Sessione Operation context de todos os itens de telemetria rastreados ao lidar com uma solicitação de uma fonte sintética, como um teste de disponibilidade ou bot de mecanismo de pesquisa. Por padrão, o explorador de métricas não exibe telemetria sintética.

    O <Filters> conjunto de propriedades de identificação das solicitações.

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

  • WebTestTelemetryInitializerdefine o ID do usuário, o ID da sessão e as propriedades de fonte sintética para solicitações HTTP provenientes de testes de disponibilidade. O <Filters> conjunto de propriedades de identificação das solicitações.

Para aplicativos .NET em execução no Azure Service Fabric, você pode incluir o Microsoft.ApplicationInsights.ServiceFabric pacote NuGet. Este pacote inclui uma FabricTelemetryInitializer propriedade, 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 NuGet.

Processadores de telemetria (ASP.NET)

Os processadores de telemetria podem filtrar e modificar cada item de telemetria antes de ser enviado do SDK para o portal.

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

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

Esta funcionalidade está ativada por predefinição. Se o seu aplicativo enviar uma telemetria considerável, esse processador removerá 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 alcançar. Cada instância do SDK funciona de forma independente. Assim, se o seu servidor for um cluster de várias máquinas, o volume real de telemetria será multiplicado de acordo.

Saiba mais sobre amostragem.

Processador de telemetria de amostragem de taxa fixa (a partir de 2.0.0-beta1)

Há também um processador de telemetria de amostragem padrão (a partir da versão 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

Consulte Exemplos de código de cadeia de conexão.

InstrumentaçãoKey

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

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

Se você quiser definir a chave dinamicamente, por exemplo, se quiser enviar resultados do seu aplicativo para recursos diferentes, você pode omitir a chave do arquivo de configuração e defini-la em código.

Para definir a chave para todas as instâncias do , incluindo módulos de telemetria padrão, execute esta etapa em um método de TelemetryClientinicializaçã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 a partir da v2.6.0.

O objetivo deste provedor é procurar um ID de aplicativo com base em uma chave de instrumentação. O ID do aplicativo é incluído e RequestTelemetry DependencyTelemetry usado para determinar a correlação no portal.

Essa funcionalidade está disponível definindo 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 do Microsoft.ApplicationInsights : ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Este wrapper é para a nossa API de perfil. Ele irá limitar as solicitações e os resultados do cache.

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

Esta classe tem uma propriedade ProfileQueryEndpointopcional. Por padrão, ele é definido como https://dc.services.visualstudio.com/api/profiles/{0}/appId. Se você precisar configurar um proxy para essa configuração, recomendamos que você faça proxy do endereço base e inclua "/api/profiles/{0}/appId". A {0} é substituído em tempo de execução por solicitação com a chave de instrumentação.

Exemplo de configuração via 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 via código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

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

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

Essa classe tem a propriedade Nextopcional , que pode ser usada para configurar outro provedor a ser usado quando uma chave de instrumentação é solicitada que não existe em sua configuração.

Exemplo de configuração via 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 via 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âneos para aplicativos ASP.NET

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

Próximos passos

Saiba mais sobre a API