Canais de telemetria no Application Insights

  • Artigo

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

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 que são canais de telemetria?

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

O método Send(ITelemetry item) de um canal de telemetria é chamado depois que todos os inicializadores e processadores de telemetria são chamados. Portanto, qualquer item derrubado por um processador de telemetria não alcançará o canal. O método Send() geralmente não envia os itens para o back-end de forma instantânea. Normalmente, ele os armazena em buffers na memória e os envia em lotes, para obter uma transmissão eficiente.

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

Canais de telemetria integrados

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

  • InMemoryChannel: Um canal leve que armazena itens 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 novamente a telemetria após uma falha. Esse canal também não mantém itens em disco. Portanto, todos os itens não enviados são perdidos permanentemente após o desligamento do aplicativo, sejam eles normais ou não. Este canal implementa um método Flush() que pode ser usado para forçar a liberação de qualquer item 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.

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

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

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

Configure um canal de telemetria

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

As seções a seguir mostram exemplos de como definir a configuração StorageFolder do 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, confira a seção Configurações configuráveis nos canais mais tarde neste artigo.

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

A seção a seguir de ApplicationInsights.config mostra o canal ServerTelemetryChannel 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 aplicativos ASP.NET

O código a seguir configura uma instância ServerTelemetryChannel com StorageFolder definido como um local personalizado. Adicione este código no início do aplicativo, normalmente no método Application_Start() 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 aplicativos ASP.NET Core

Modifique o método ConfigureServices da classe Startup.cs conforme 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

Configurar o canal usando TelemetryConfiguration.Active não tem suporte dos aplicativos ASP.NET Core.

Configuração no 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 de ServerTelemetryChannel

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

Por padrão, no máximo 10 instâncias Transmission 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 for lento, as instâncias Transmission serão armazenadas na memória. A capacidade padrão desse buffer Transmission na memória é 5 MB. Quando a capacidade da memória é excedida, as instâncias Transmission são armazenadas no disco local até um limite de 50 MB.

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

Configurações configuráveis em canais

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

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

  • MaxTransmissionBufferCapacity: A quantidade máxima de memória, em bytes, usada pelo canal para fazer o buffer das 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 travar.
  • MaxTransmissionSenderCapacity: O número máximo de instâncias Transmission que serão enviadas ao Application Insights ao mesmo tempo. O valor padrão é 10. Essa configuração pode ser definida para um número maior, o que é recomendável quando é gerado um grande volume de telemetria. O volume alto normalmente ocorre durante o teste de carga ou quando a amostragem é 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.

Qual canal devo usar?

Recomendamos ServerTelemetryChannel para a maioria dos cenários de produção que envolvem aplicativos de execução prolongada. O método Flush() implementado por ServerTelemetryChannel não é síncrono. Ele também não garante o envio de todos os itens pendentes da memória ou disco.

Se você usar este canal em cenários em que o aplicativo está prestes a ser desligado, insira um pouco de atraso após chamar Flush(). A quantidade exata de atraso que você pode exigir não é previsível. Depende de fatores como quantos itens ou instâncias Transmission estão na memória, quantos estão no disco, quantos estão sendo transmitidos para o back-end e se o canal está no meio de cenários de back-off exponencial.

Se você precisar fazer uma liberação síncrona, use InMemoryChannel.

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

O canal do Application Insights garante a entrega de telemetria? Se não, quais são os cenários em que a telemetria pode ser perdida?

A resposta curta é que nenhum dos canais integrados oferece uma garantia do tipo de transação de entrega de telemetria para o backend. ServerTelemetryChannel é mais avançado em comparação com InMemoryChannel para entrega confiável, mas também faz apenas uma tentativa de melhor esforço para enviar telemetria. A telemetria ainda pode ser perdida em várias situações, incluindo estes cenários comuns:

  • Os itens na memória são perdidos quando o aplicativo trava.
  • A telemetria é perdida durante longos períodos de problemas de rede. A telemetria é armazenada no disco local durante interrupções da rede ou quando ocorrem problemas com o back-end do Application Insights. No entanto, itens com mais de 48 horas são descartados.
  • Os locais de disco padrão para armazenar telemetria no Windows são% LOCALAPPDATA% ou% TEMP%. Esses locais são normalmente locais para a máquina. Se o aplicativo migrar fisicamente de um local para outro, qualquer telemetria armazenada no local original será perdida.
  • Em Web Apps do Azure no Windows, o local de armazenamento em disco padrão é D:\local\LocalAppData. Este local não é persistente. Ela é apagada em reinicializações de aplicativos, expansões e outras operações semelhantes e isso gera a perda de qualquer telemetria armazenada nela. Você pode substituir o padrão e especificar o armazenamento em um local persistente como D:\home. No entanto, esses locais persistentes são servidos por armazenamento remoto e, portanto, podem ser lentos.

Mesmo sendo improvável, também é possível que o canal possa causar itens de telemetria duplicados. Esse comportamento ocorre quando ServerTelemetryChannel faz novas tentativas devido a falha de rede ou tempo limite, quando a telemetria foi entregue ao back-end, mas a resposta foi perdida devido a problemas de rede ou porque houve um tempo limite.

O ServerTelemetryChannel funciona em sistemas diferentes do Windows?

Embora o nome de seu pacote e namespace inclua "WindowsServer", este canal é compatível com sistemas diferentes do Windows, com a seguinte exceção. Em sistemas diferentes do Windows, o canal não cria uma pasta de armazenamento local por padrão. Você deve criar uma pasta de armazenamento local e configurar o canal para usá-la. Após a configuração do armazenamento local, o canal funciona da mesma maneira em todos os sistemas.

Observação

Com a versão 2.15.0-beta3 e superior, o armazenamento local agora será criado automaticamente para Linux, Mac e Windows. Para sistemas não Windows, o SDK criará automaticamente uma pasta de armazenamento local com base na seguinte lógica:

  • ${TMPDIR}: se a variável de ambiente ${TMPDIR} for definida, este local será usado.
  • /var/tmp: se o local anterior não existir, tentaremos /var/tmp.
  • /tmp: se os dois locais anteriores não existirem, tentaremos tmp.
  • Se nenhum desses locais existir, o armazenamento local não será criado e a configuração manual ainda será necessária. Para obter detalhes completos da implementação, consulte este repositório GitHub.

O SDK cria armazenamento local temporário? Os dados são criptografados no armazenamento?

O SDK armazena itens de telemetria no armazenamento local durante problemas de rede ou durante a limitação. Esses dados não são criptografados localmente.

Em sistemas Windows, o SDK cria automaticamente uma pasta local temporária no diretório %TEMP% ou %LOCALAPPDATA% e restringe o acesso apenas aos administradores e ao usuário atual.

Em sistemas diferentes do Windows, nenhum armazenamento local é criado automaticamente pelo SDK e, portanto, nenhum dado é armazenado localmente por padrão.

Observação

Com a versão 2.15.0-beta3 e superior, o armazenamento local agora será criado automaticamente para Linux, Mac e Windows.

Você mesmo pode criar um diretório de armazenamento e configurar o canal para usá-lo. Nesse caso, você é responsável por garantir que o diretório esteja protegido. Leia mais sobre proteção de dados e privacidade.

SDK do código-fonte aberto

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

Próximas etapas