Partilhar via

Canais de telemetria no Application Insights

Os canais de telemetria são parte integrante dos SDKs do Application Insights. Eles gerenciam o buffer e a transmissão de telemetria para o serviço Application Insights. As versões .NET e .NET Core dos SDKs têm dois canais de telemetria internos: InMemoryChannel e ServerTelemetryChannel. Este artigo descreve cada canal e mostra como personalizar o comportamento do canal.

Atenção

Recomendamos a Distro OpenTelemetry do Azure Monitor para novas aplicações ou clientes, de forma a potenciar o Azure Monitor Application Insights. A Distro OpenTelemetry do Azure Monitor oferece uma funcionalidade e experiência semelhantes às do SDK do Application Insights. É possível migrar do SDK do Application Insights usando os guias de migração para .NET, Node.jse Python, mas ainda estamos trabalhando para adicionar mais alguns recursos para compatibilidade com versões anteriores.

O que são canais de telemetria?

Os canais de telemetria são responsáveis por armazenar itens de telemetria em buffer e enviá-los para o serviço Application Insights, onde são armazenados para consulta e análise. Um canal de telemetria é qualquer classe que implementa a Microsoft.ApplicationInsights.ITelemetryChannel interface.

O Send(ITelemetry item) método de um canal de telemetria é chamado depois que todos os inicializadores de telemetria e processadores de telemetria são chamados. Assim, quaisquer itens deixados de lado por um processador de telemetria não chegarão ao canal. Normalmente Send() , o método não envia os itens para o back-end instantaneamente. Normalmente, ele os armazena em buffer na memória e os envia em lotes para uma transmissão eficiente.

Evite ligar para Flush() a menos que seja fundamental enviar a telemetria armazenada em buffer imediatamente. Use-o somente em cenários como desligamento de aplicativos, tratamento de exceções ou ao usar processos de curta duração, como trabalhos em segundo plano ou ferramentas de linha de comando. Em aplicativos Web ou serviços de longa execução, o SDK lida com o envio de telemetria automaticamente. Chamar Flush() desnecessariamente pode causar problemas de desempenho.

Live Metrics Stream também tem um canal personalizado que alimenta a transmissão ao vivo de telemetria. Este canal é independente do canal de telemetria regular, e este documento não se aplica a ele.

Canais de telemetria integrados

Os SDKs .NET e .NET Core do Application Insights são fornecidos com dois canais internos:

  • InMemoryChannel: Um canal leve que armazena itens em buffer na memória até que eles sejam enviados. Os itens são armazenados em buffer na memória e liberados uma vez a cada 30 segundos ou sempre que 500 itens são armazenados em buffer. Este canal oferece garantias mínimas de confiabilidade porque não tenta enviar telemetria novamente após uma falha. Este canal também não mantém itens no disco. Assim, todos os itens não enviados são perdidos permanentemente após o desligamento do aplicativo, seja ele gracioso ou não. Esse canal implementa um Flush() método que pode ser usado para forçar a liberação de quaisquer itens de telemetria na memória de forma síncrona. Este canal é adequado para aplicações de curta duração onde uma descarga síncrona é ideal.

    Esse canal faz parte do pacote NuGet maior do Microsoft.ApplicationInsights e é o canal padrão que o SDK usa quando nada mais é configurado.

  • ServerTelemetryChannel: Um canal mais avançado que tem políticas de repetição e a capacidade de armazenar dados em um disco local. Este canal tenta novamente enviar telemetria se ocorrerem erros transitórios. Esse canal também usa armazenamento em disco local para manter itens no disco durante interrupções de rede ou altos volumes de telemetria. Devido a esses mecanismos de repetição e armazenamento em disco local, esse canal é considerado mais confiável. Recomendamos para todos os cenários de produção. Este canal é o padrão para aplicativos ASP.NET e ASP.NET Core que são configurados de acordo com a documentação oficial. Esse canal é otimizado para cenários de servidor com processos de longa execução. O Flush() método implementado por este canal não é síncrono.

    Esse canal é fornecido como o pacote NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel e é adquirido automaticamente quando você usa o pacote NuGet Microsoft.ApplicationInsights.Web ou Microsoft.ApplicationInsights.AspNetCore.

Configurar um canal de telemetria

Configure um canal de telemetria definindo-o para a configuração de telemetria ativa. Para aplicativos ASP.NET, a configuração envolve definir a instância do canal de telemetria para TelemetryConfiguration.Active ou modificando ApplicationInsights.config. Para aplicativos ASP.NET Core, a configuração envolve a adição do canal ao contêiner de injeção de dependência.

As seções a seguir mostram exemplos de configuração da StorageFolder configuração para o canal em vários tipos de aplicativos. StorageFolder é apenas uma das configurações configuráveis. Para obter a lista completa de definições de configuração, consulte a seção Configurações configuráveis em canais mais adiante neste artigo.

Configuração usando ApplicationInsights.config para aplicativos ASP.NET

A seção a seguir do ApplicationInsights.config mostra o ServerTelemetryChannel canal configurado com StorageFolder definido para um local personalizado:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity  -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

Configuração em código para aplicações ASP.NET

O código a seguir configura uma ServerTelemetryChannel instância com StorageFolder definido para um local personalizado. Adicione esse código no início do aplicativo, normalmente no Application_Start() método em Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Configuração em código para aplicações ASP.NET Core

Modifique o ConfigureServicesStartup.cs método da classe como mostrado aqui:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Importante

A configuração do canal usando TelemetryConfiguration.Active não é suportada para aplicativos ASP.NET Core.

Configuração em código para aplicativos de console .NET/.NET Core

Para aplicativos de console, o código é o mesmo para .NET e .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Detalhes operacionais do ServerTelemetryChannel

ServerTelemetryChannel armazena os itens que chegam em um buffer na memória. Os itens são serializados, compactados e armazenados em uma Transmission instância uma vez a cada 30 segundos ou quando 500 itens foram armazenados em buffer. Uma única Transmission instância contém até 500 itens e representa um lote de telemetria que é enviado por uma única chamada HTTPS para o serviço Application Insights.

Por padrão, um máximo de 10 Transmission instâncias podem ser enviadas em paralelo. Se a telemetria estiver chegando a taxas mais rápidas, ou se a rede ou o back-end do Application Insights estiver lento, Transmission as instâncias serão armazenadas na memória. A capacidade padrão desse buffer na memória Transmission é de 5 MB. Quando a capacidade na memória é excedida, Transmission as instâncias são armazenadas no disco local até um limite de 50 MB.

Transmission As instâncias são armazenadas no disco local também quando há problemas de rede. Somente os itens armazenados em um disco local sobrevivem a uma falha de aplicativo. Eles são enviados sempre que o aplicativo é reiniciado. Se os problemas de rede persistirem, ServerTelemetryChannel usa uma lógica de backoff exponencial que varia de 10 segundos a 1 hora antes de tentar enviar novamente a telemetria.

Configurações configuráveis em canais

Para obter a lista completa de configurações configuráveis para cada canal, consulte:

Aqui estão as configurações mais usadas para ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: A quantidade máxima de memória, em bytes, usada pelo canal para buffer transmissões na memória. Quando essa capacidade é atingida, novos itens são armazenados diretamente no disco local. O valor padrão é 5 MB. Definir um valor mais alto leva a menos uso do disco, mas lembre-se de que os itens na memória serão perdidos se o aplicativo falhar.
  • MaxTransmissionSenderCapacity: O número máximo de Transmission instâncias que serão enviadas para o Application Insights ao mesmo tempo. O valor predefinido é 10. Essa configuração pode ser configurada para um número maior, o que recomendamos quando um grande volume de telemetria é gerado. O volume elevado ocorre normalmente durante o teste de carga ou quando a amostragem está desligada.
  • StorageFolder: A pasta usada pelo canal para armazenar itens no disco conforme necessário. No Windows, %LOCALAPPDATA% ou %TEMP% é usado se nenhum outro caminho for especificado explicitamente. Em ambientes diferentes do Windows, você deve especificar um local válido ou a telemetria não será armazenada no disco local.

Que canal devo utilizar?

Recomendamos ServerTelemetryChannel para a maioria dos cenários de produção que envolvem aplicativos de longa execução. Para obter mais informações sobre a limpeza de telemetria, leia sobre como usar Flush().

Quando utilizar Flush()

O método Flush() envia a telemetria em buffer imediatamente. No entanto, só deve ser utilizado em cenários específicos.

Utilize Flush() quando:

  • A aplicação está prestes a ser encerrada e pretendes garantir que a telemetria seja enviada antes de saíres.
  • Você está num tratador de exceções e precisa garantir que a telemetria seja enviada.
  • Você está escrevendo um processo de curta duração, como um trabalho em segundo plano ou uma ferramenta CLI que sai rapidamente.

Evite usar Flush() em aplicativos de longa execução, como serviços Web. O SDK gerencia automaticamente o buffer e a transmissão. Ligar Flush() desnecessariamente pode causar problemas de desempenho e não garante que todos os dados sejam enviados, especialmente quando se utiliza ServerTelemetryChannel, que não faz a limpeza de forma síncrona.

SDK de código aberto

Como todo SDK para Application Insights, os canais são de código aberto. Leia e contribua para o código ou relate problemas no repositório oficial do GitHub.

Próximos passos