Canais de telemetria no Application InsightsTelemetry channels in Application Insights

Os canais de telemetria são parte integrante dos SDKs do aplicativo Azure insights.Telemetry channels are an integral part of the Azure Application Insights SDKs. Eles gerenciam o armazenamento em buffer e a transmissão de telemetria para o serviço de Application Insights.They manage buffering and transmission of telemetry to the Application Insights service. As versões .NET e .NET Core dos SDKs têm dois canais de telemetria internos: InMemoryChannel e ServerTelemetryChannel .The .NET and .NET Core versions of the SDKs have two built-in telemetry channels: InMemoryChannel and ServerTelemetryChannel. Este artigo descreve cada canal em detalhes, incluindo como personalizar o comportamento do canal.This article describes each channel in detail, including how to customize channel behavior.

O que são canais de telemetria?What are telemetry channels?

Os canais de telemetria são responsáveis por armazenar em buffer itens de telemetria e enviá-los para o serviço de Application Insights, onde são armazenados para consulta e análise.Telemetry channels are responsible for buffering telemetry items and sending them to the Application Insights service, where they're stored for querying and analysis. Um canal de telemetria é qualquer classe que implementa a Microsoft.ApplicationInsights.ITelemetryChannel interface.A telemetry channel is any class that implements the Microsoft.ApplicationInsights.ITelemetryChannel interface.

O Send(ITelemetry item) método de um canal de telemetria é chamado depois que todos os inicializadores de telemetria e os processadores de telemetria são chamados.The Send(ITelemetry item) method of a telemetry channel is called after all telemetry initializers and telemetry processors are called. Assim, todos os itens descartados por um processador de telemetria não alcançarão o canal.So, any items dropped by a telemetry processor won't reach the channel. Send() Normalmente, o não envia os itens para o back-end instantaneamente.Send() doesn't typically send the items to the back end instantly. Normalmente, ele os armazena em buffers na memória e os envia em lotes para transmissão eficiente.Typically, it buffers them in memory and sends them in batches, for efficient transmission.

Live Metrics Stream também tem um canal personalizado que alimenta a transmissão ao vivo da telemetria.Live Metrics Stream also has a custom channel that powers the live streaming of telemetry. Esse canal é independente do canal de telemetria regular e este documento não se aplica a ele.This channel is independent of the regular telemetry channel, and this document doesn't apply to it.

Canais internos de telemetriaBuilt-in telemetry channels

Os SDKs Application Insights .NET e .NET Core são fornecidos com dois canais internos:The Application Insights .NET and .NET Core SDKs ship with two built-in channels:

  • InMemoryChannel: Um canal leve que armazena em buffer os itens na memória até que eles sejam enviados.InMemoryChannel: A lightweight channel that buffers items in memory until they're sent. 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.Items are buffered in memory and flushed once every 30 seconds, or whenever 500 items are buffered. Esse canal oferece garantias de confiabilidade mínimas porque não tenta enviar novamente a telemetria após uma falha.This channel offers minimal reliability guarantees because it doesn't retry sending telemetry after a failure. 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 (normal ou não).This channel also doesn't keep items on disk, so any unsent items are lost permanently upon application shutdown (graceful or not). Esse canal implementa um Flush() método que pode ser usado para forçar a liberação de todos os itens de telemetria na memória de forma síncrona.This channel implements a Flush() method that can be used to force-flush any in-memory telemetry items synchronously. Esse canal é adequado para aplicativos de curta execução em que uma liberação síncrona é ideal.This channel is well suited for short-running applications where a synchronous flush is ideal.

    Esse canal faz parte do pacote NuGet Microsoft. ApplicationInsights maior e é o canal padrão que o SDK usa quando nada mais está configurado.This channel is part of the larger Microsoft.ApplicationInsights NuGet package and is the default channel that the SDK uses when nothing else is configured.

  • ServerTelemetryChannel: Um canal mais avançado que tem políticas de repetição e a capacidade de armazenar dados em um disco local.ServerTelemetryChannel: A more advanced channel that has retry policies and the capability to store data on a local disk. Esse canal tentará enviar telemetria novamente se ocorrerem erros transitórios.This channel retries sending telemetry if transient errors occur. Esse canal também usa o armazenamento em disco local para manter os itens em disco durante interrupções de rede ou grandes volumes de telemetria.This channel also uses local disk storage to keep items on disk during network outages or high telemetry volumes. Devido a esses mecanismos de repetição e armazenamento de disco local, esse canal é considerado mais confiável e é recomendado para todos os cenários de produção.Because of these retry mechanisms and local disk storage, this channel is considered more reliable and is recommended for all production scenarios. Esse canal é o padrão para aplicativos ASP.net e ASP.NET Core configurados de acordo com a documentação oficial.This channel is the default for ASP.NET and ASP.NET Core applications that are configured according to the official documentation. Esse canal é otimizado para cenários de servidor com processos de execução longa.This channel is optimized for server scenarios with long-running processes. O Flush() método que é implementado por esse canal não é síncrono.The Flush() method that's implemented by this channel isn't synchronous.

    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.This channel is shipped as the Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel NuGet package and is acquired automatically when you use either the Microsoft.ApplicationInsights.Web or Microsoft.ApplicationInsights.AspNetCore NuGet package.

Configurar um canal de telemetriaConfigure a telemetry channel

Configure um canal de telemetria definindo-o como a configuração de telemetria ativa.You configure a telemetry channel by setting it to the active telemetry configuration. Para aplicativos ASP.NET, a configuração envolve definir a instância de canal de telemetria para TelemetryConfiguration.Active ou modificando ApplicationInsights.config .For ASP.NET applications, configuration involves setting the telemetry channel instance to TelemetryConfiguration.Active, or by modifying ApplicationInsights.config. Para aplicativos ASP.NET Core, a configuração envolve adicionar o canal ao contêiner de injeção de dependência.For ASP.NET Core applications, configuration involves adding the channel to the Dependency Injection Container.

As seções a seguir mostram exemplos de como definir a StorageFolder configuração para o canal em vários tipos de aplicativos.The following sections show examples of configuring the StorageFolder setting for the channel in various application types. StorageFolder é apenas uma das configurações configuráveis.StorageFolder is just one of the configurable settings. Para obter a lista completa de definições de configuração, consulte a seção Configurações mais adiante neste artigo.For the full list of configuration settings, see the settings section later in this article.

Configuração usando ApplicationInsights.config para aplicativos ASP.NETConfiguration by using ApplicationInsights.config for ASP.NET applications

A seção a seguir de ApplicationInsights.config mostra o ServerTelemetryChannel canal configurado com StorageFolder definido como um local personalizado:The following section from ApplicationInsights.config shows the ServerTelemetryChannel channel configured with StorageFolder set to a custom location:

    <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 no código para aplicativos ASP.NETConfiguration in code for ASP.NET applications

O código a seguir configura uma instância de ' ServerTelemetryChannel ' com StorageFolder definido como um local personalizado.The following code sets up a 'ServerTelemetryChannel' instance with StorageFolder set to a custom location. Adicione esse código no início do aplicativo, normalmente no Application_Start() método em global.aspx.cs.Add this code at the beginning of the application, typically in Application_Start() method in 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 no código para aplicativos ASP.NET CoreConfiguration in code for ASP.NET Core applications

Modifique o ConfigureServices método da Startup.cs classe, conforme mostrado aqui:Modify the ConfigureServices method of the Startup.cs class as shown here:

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

Não é recomendável configurar o canal usando o TelemetryConfiguration.Active não é recomendado para aplicativos ASP.NET Core.Configuring the channel by using TelemetryConfiguration.Active is not recommended for ASP.NET Core applications.

Configuração no código para aplicativos de console .NET/.NET CoreConfiguration in code for .NET/.NET Core console applications

Para aplicativos de console, o código é o mesmo para .NET e .NET Core:For console apps, the code is the same for both .NET and .NET Core:

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

Detalhes operacionais do ServerTelemetryChannelOperational details of ServerTelemetryChannel

ServerTelemetryChannel armazena itens de chegada em um buffer na memória.ServerTelemetryChannel stores arriving items in an in-memory buffer. Os itens são serializados, compactados e armazenados em uma Transmission instância uma vez a cada 30 segundos ou quando 500 itens tiverem sido colocados em buffer.The items are serialized, compressed, and stored into a Transmission instance once every 30 seconds, or when 500 items have been buffered. Uma única Transmission instância contém até 500 itens e representa um lote de telemetria enviado por uma única chamada HTTPS para o serviço Application insights.A single Transmission instance contains up to 500 items and represents a batch of telemetry that's sent over a single HTTPS call to the Application Insights service.

Por padrão, um máximo de 10 Transmission instâncias pode ser enviado em paralelo.By default, a maximum of 10 Transmission instances can be sent in parallel. Se a telemetria estiver chegando a taxas mais rápidas ou se a rede ou o back-end de Application Insights estiver lento, as Transmission instâncias serão armazenadas na memória.If telemetry is arriving at faster rates, or if the network or the Application Insights back end is slow, Transmission instances are stored in memory. A capacidade padrão desse buffer na memória Transmission é de 5 MB.The default capacity of this in-memory Transmission buffer is 5 MB. Quando a capacidade na memória for excedida, as Transmission instâncias serão armazenadas no disco local até um limite de 50 MB.When the in-memory capacity has been exceeded, Transmission instances are stored on local disk up to a limit of 50 MB. Transmission as instâncias são armazenadas no disco local também quando há problemas de rede.Transmission instances are stored on local disk also when there are network problems. Somente os itens que são armazenados em um disco local sobrevivem a uma falha do aplicativo.Only those items that are stored on a local disk survive an application crash. Eles são enviados sempre que o aplicativo é iniciado novamente.They're sent whenever the application starts again.

Configurações configuráveis em canaisConfigurable settings in channels

Para obter a lista completa de configurações configuráveis para cada canal, consulte:For the full list of configurable settings for each channel, see:

Aqui estão as configurações mais comumente usadas para ServerTelemetryChannel :Here are the most commonly used settings for ServerTelemetryChannel:

  1. MaxTransmissionBufferCapacity: A quantidade máxima de memória, em bytes, usada pelo canal para transmissões de buffer na memória.MaxTransmissionBufferCapacity: The maximum amount of memory, in bytes, used by the channel to buffer transmissions in memory. Quando essa capacidade é atingida, novos itens são armazenados diretamente no disco local.When this capacity is reached, new items are stored directly to local disk. O valor padrão é 5 MB.The default value is 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.Setting a higher value leads to less disk usage, but remember that items in memory will be lost if the application crashes.

  2. MaxTransmissionSenderCapacity: O número máximo de Transmission instâncias que serão enviadas para Application insights ao mesmo tempo.MaxTransmissionSenderCapacity: The maximum number of Transmission instances that will be sent to Application Insights at the same time. O valor padrão é 10.The default value is 10. Essa configuração pode ser configurada para um número mais alto, que é recomendado quando um grande volume de telemetria é gerado.This setting can be configured to a higher number, which is recommended when a huge volume of telemetry is generated. O alto volume geralmente ocorre durante o teste de carga ou quando a amostragem está desativada.High volume typically occurs during load testing or when sampling is turned off.

  3. StorageFolder: A pasta usada pelo canal para armazenar itens no disco, conforme necessário.StorageFolder: The folder that's used by the channel to store items to disk as needed. No Windows, o% LOCALAPPDATA% ou% TEMP% será usado se nenhum outro caminho for especificado explicitamente.In Windows, either %LOCALAPPDATA% or %TEMP% is used if no other path is specified explicitly. Em ambientes diferentes do Windows, você deve especificar um local válido ou a telemetria não será armazenada no disco local.In environments other than Windows, you must specify a valid location or telemetry won't be stored to local disk.

Qual canal devo usar?Which channel should I use?

ServerTelemetryChannel é recomendado para a maioria dos cenários de produção que envolvem aplicativos de execução longa.ServerTelemetryChannel is recommended for most production scenarios involving long-running applications. O Flush() método implementado por ServerTelemetryChannel não é síncrono e também não garante o envio de todos os itens pendentes da memória ou do disco.The Flush() method implemented by ServerTelemetryChannel isn't synchronous, and it also doesn't guarantee sending all pending items from memory or disk. Se você usar esse canal em cenários em que o aplicativo está prestes a ser desligado, recomendamos que você introduza algum atraso após a chamada Flush() .If you use this channel in scenarios where the application is about to shut down, we recommend that you introduce some delay after calling Flush(). A quantidade exata de atraso que você pode exigir não é previsível.The exact amount of delay that you might require isn't predictable. Depende de fatores como quantos itens ou Transmission instâncias estão na memória, quantas estão no disco, quantos estão sendo transmitidos para o back-end e se o canal está no meio dos cenários de retirada exponencial.It depends on factors like how many items or Transmission instances are in memory, how many are on disk, how many are being transmitted to the back end, and whether the channel is in the middle of exponential back-off scenarios.

Se você precisar fazer uma liberação síncrona, recomendamos o uso do InMemoryChannel .If you need to do a synchronous flush, we recommend that you use InMemoryChannel.

Perguntas frequentesFrequently asked questions

O canal Application Insights garante a entrega de telemetria?Does the Application Insights channel guarantee telemetry delivery? Caso contrário, quais são os cenários em que a telemetria pode ser perdida?If not, what are the scenarios in which telemetry can be lost?

A resposta curta é que nenhum dos canais internos oferece uma garantia de tipo de transação de entrega de telemetria para o back-end.The short answer is that none of the built-in channels offer a transaction-type guarantee of telemetry delivery to the back end. ServerTelemetryChannel é mais avançado em comparação com a InMemoryChannel entrega confiável, mas também faz apenas uma tentativa de envio de telemetria por um melhor esforço.ServerTelemetryChannel is more advanced compared with InMemoryChannel for reliable delivery, but it also makes only a best-effort attempt to send telemetry. A telemetria ainda pode ser perdida em várias situações, incluindo estes cenários comuns:Telemetry can still be lost in several situations, including these common scenarios:

  1. Os itens na memória são perdidos quando o aplicativo falha.Items in memory are lost when the application crashes.

  2. A telemetria é perdida durante períodos estendidos de problemas de rede.Telemetry is lost during extended periods of network problems. A telemetria é armazenada no disco local durante interrupções de rede ou quando ocorrem problemas com o back-end de Application Insights.Telemetry is stored to local disk during network outages or when problems occur with the Application Insights back end. No entanto, itens com mais de 48 horas são descartados.However, items older than 48 hours are discarded.

  3. Os locais de disco padrão para armazenar telemetria no Windows são% LOCALAPPDATA% ou% TEMP%.The default disk locations for storing telemetry in Windows are %LOCALAPPDATA% or %TEMP%. Esses locais normalmente são locais para o computador.These locations are typically local to the machine. Se o aplicativo migrar fisicamente de um local para outro, qualquer telemetria armazenada no local original será perdida.If the application migrates physically from one location to another, any telemetry stored in the original location is lost.

  4. Em aplicativos Web no Windows, o local de armazenamento de disco padrão é D:\local\LocalAppData.In Web Apps on Windows, the default disk-storage location is D:\local\LocalAppData. Esse local não é persistente.This location isn't persisted. Ele é apagado em reinicializações de aplicativo, escalações e outras operações, levando à perda de qualquer telemetria armazenada lá.It's wiped out in app restarts, scale-outs, and other such operations, leading to loss of any telemetry stored there. Você pode substituir o padrão e especificar o armazenamento para um local persistente, como D:\home.You can override the default and specify storage to a persisted location like D:\home. No entanto, esses locais persistentes são atendidos pelo armazenamento remoto e, portanto, podem ser lentos.However, such persisted locations are served by remote storage and so can be slow.

O ServerTelemetryChannel funciona em sistemas diferentes do Windows?Does ServerTelemetryChannel work on systems other than Windows?

Embora o nome de seu pacote e namespace inclua "WindowsServer", esse canal tem suporte em sistemas diferentes do Windows, com a seguinte exceção.Although the name of its package and namespace includes "WindowsServer," this channel is supported on systems other than Windows, with the following exception. Em sistemas diferentes do Windows, o canal não cria uma pasta de armazenamento local por padrão.On systems other than Windows, the channel doesn't create a local storage folder by default. Você deve criar uma pasta de armazenamento local e configurar o canal para usá-la.You must create a local storage folder and configure the channel to use it. Depois que o armazenamento local tiver sido configurado, o canal funcionará da mesma maneira em todos os sistemas.After local storage has been configured, the channel works the same way on all systems.

Observação

Com a versão 2.15.0-Beta3 e o armazenamento local superior agora são criados automaticamente para Linux, Mac e Windows.With the release 2.15.0-beta3 and greater local storage is now automatically created for Linux, Mac, and Windows. Para sistemas não Windows, o SDK criará automaticamente uma pasta de armazenamento local com base na seguinte lógica:For non Windows systems the SDK will automatically create a local storage folder based on the following logic:

  • ${TMPDIR} -Se ${TMPDIR} a variável de ambiente for definida, esse local será usado.${TMPDIR} - if ${TMPDIR} environment variable is set this location is used.
  • /var/tmp -Se o local anterior não existir, tentaremos /var/tmp ./var/tmp - if the previous location does not exist we try /var/tmp.
  • /tmp -Se os dois locais anteriores não existirem, tentaremos tmp ./tmp - if both the previous locations do not exist we try tmp.
  • Se nenhum desses locais existir, o armazenamento local não será criado e a configuração manual ainda será necessária.If none of those locations exist local storage is not created and manual configuration is still required. Para obter detalhes sobre a implementação completa.For full implementation details.

O SDK cria armazenamento local temporário?Does the SDK create temporary local storage? Os dados são criptografados no armazenamento?Is the data encrypted at storage?

O SDK armazena itens de telemetria no armazenamento local durante problemas de rede ou durante a limitação.The SDK stores telemetry items in local storage during network problems or during throttling. Esses dados não são criptografados localmente.This data isn't encrypted locally.

Para sistemas Windows, o SDK cria automaticamente uma pasta local temporária no diretório% TEMP% ou% LOCALAPPDATA% e restringe o acesso a administradores e somente ao usuário atual.For Windows systems, the SDK automatically creates a temporary local folder in the %TEMP% or %LOCALAPPDATA% directory, and restricts access to administrators and the current user only.

Para sistemas diferentes do Windows, nenhum armazenamento local é criado automaticamente pelo SDK e, portanto, nenhum dado é armazenado localmente por padrão.For systems other than Windows, no local storage is created automatically by the SDK, and so no data is stored locally by default.

Observação

Com a versão 2.15.0-Beta3 e o armazenamento local superior agora são criados automaticamente para Linux, Mac e Windows.With the release 2.15.0-beta3 and greater local storage is now automatically created for Linux, Mac, and Windows.

Você pode criar um diretório de armazenamento por conta própria e configurar o canal para usá-lo.You can create a storage directory yourself and configure the channel to use it. Nesse caso, você é responsável por garantir que o diretório esteja protegido.In this case, you're responsible for ensuring that the directory is secured. Leia mais sobre proteção e privacidade de dados.Read more about data protection and privacy.

SDK do código-fonte abertoOpen-source SDK

Assim como todos os SDK para Application Insights, os canais são de software livre.Like every SDK for Application Insights, channels are open source. Leia e contribua com o código ou relate problemas no repositório GitHub oficial.Read and contribute to the code, or report problems, at the official GitHub repo.

Próximas etapasNext steps