Partilhar via

Canais de telemetria no Application Insights

  • Artigo

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.

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 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.

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 de 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 ConfigureServices Startup.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 usará 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. O Flush() método implementado por ServerTelemetryChannel não é síncrono. Também não garante o envio de todos os itens pendentes da memória ou do disco.

Se você usar esse canal em cenários em que o aplicativo está prestes a ser encerrado, introduza algum atraso após a chamada Flush(). A quantidade exata de atraso que você pode precisar não é previsível. Depende de fatores como quantos itens ou Transmission instâncias 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 descarga síncrona, use InMemoryChannel.

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

O canal do Application Insights garante a entrega da 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 transação de entrega de telemetria para o back-end. ServerTelemetryChannel é mais avançado em comparação com InMemoryChannel uma 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:

  • Itens na memória são perdidos quando o aplicativo falha.
  • A telemetria é perdida durante longos períodos de problemas de rede. A telemetria é armazenada no disco local durante interrupções de 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.
  • Nos Aplicativos Web do Azure no Windows, o local de armazenamento em disco padrão é D:\local\LocalAppData. Esta localização não é persistente. Ele é eliminado em reinicializações de aplicativos, scale-outs e outras operações semelhantes, o que leva à perda de qualquer telemetria armazenada lá. Você pode substituir o padrão e especificar o armazenamento para um local persistente como D:\home. No entanto, esses locais persistentes são servidos por armazenamento remoto e, portanto, podem ser lentos.

Embora menos provável, também é possível que o canal possa causar itens de telemetria duplicados. Esse comportamento ocorre quando ServerTelemetryChannel 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 houve um tempo limite.

O ServerTelemetryChannel funciona em sistemas diferentes do Windows?

Embora o nome de seu pacote e namespace inclua "WindowsServer", esse canal é suportado em 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 forma em todos os sistemas.

Nota

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

  • ${TMPDIR}: Se a ${TMPDIR} variável de ambiente estiver definida, este local será usado.
  • /var/tmp: Se o local anterior não existir, tentamos /var/tmp.
  • /tmp: Se ambos os locais anteriores não existirem, tentamos 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.

Para 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.

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

Nota

Com a versão 2.15.0-beta3 e superior, o armazenamento local agora é 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 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