Canali di telemetria in Application Insights

I canali di telemetria costituiscono parte integrante degli SDK di Application Insights. Essi gestiscono il buffering e la trasmissione dei dati di telemetria al servizio Application Insights. Le versioni .NET e .NET Core degli SDK hanno due canali di telemetria predefiniti: InMemoryChannel e ServerTelemetryChannel. Nel presente articolo sono descritti i singoli canali, inoltre si spiega come personalizzare il comportamento del canale.

Che cosa sono i canali di telemetria?

I canali di telemetria sono responsabili del buffering degli elementi di telemetria e del loro invio al servizio Application Insights, dove vengono archiviati per l'esecuzione di query e l'analisi. Un canale di telemetria è una qualsiasi classe che implementa l'interfaccia Microsoft.ApplicationInsights.ITelemetryChannel.

Il metodo Send(ITelemetry item) di un canale di telemetria viene chiamato dopo aver chiamato tutti gli inizializzatori e i processori di telemetria. Di conseguenza, tutti gli elementi rimossi da un processore di telemetria non raggiungeranno il canale. Solitamente, il metodo Send() non invia istantaneamente gli elementi al back-end. In genere, li memorizza nel buffer nella memoria e li invia in batch per una trasmissione più efficiente.

Live Metrics Stream include anche un canale personalizzato che supporta lo streaming live dei dati di telemetria. Questo canale è indipendente dal canale di telemetria normale, quindi il presente documento non è applicabile.

Canali di telemetria predefiniti

Gli SDK .NET e .NET Core di Application Insights vengono forniti con due canali predefiniti:

• InMemoryChannel: un canale leggero che inserisce gli elementi nel buffer di memoria finché non vengono inviati. Gli elementi vengono memorizzati nel buffer di memoria e scaricati una volta ogni 30 secondi, oppure ogni volta che vengono inseriti 500 elementi nel buffer. Questo canale offre garanzie di affidabilità minime perché non riprova a inviare i dati di telemetria in seguito a un errore. Inoltre, questo canale non conserva gli elementi su disco. Pertanto, gli eventuali elementi non inviati vengono persi in modo permanente all'arresto dell'applicazione, che si un arresto normale o meno. Questo canale implementa un metodo Flush() che può essere usato per forzare lo scaricamento sincrono di tutti gli elementi di telemetria in memoria. Questo canale è ideale per le applicazioni a esecuzione breve per le quali è ideale lo scaricamento sincrono.

  Il canale fa parte del pacchetto più esteso NuGet Microsoft.ApplicationInsights ed è il canale predefinito che l'SDK utilizza in assenza di altre opzioni di configurazione.

• ServerTelemetryChannel: canale più avanzato con criteri di ripetizione dei tentativi e la capacità di archiviare i dati su un disco locale. Questo canale ritenta l'invio dei dati di telemetria in caso di errori temporanei. Inoltre, questo canale si avvale dell'archiviazione su disco locale per mantenere gli elementi su disco durante interruzioni di rete o in presenza di volumi di telemetria elevati. A causa di questi meccanismi di ripetizione dei tentativi e dell'archiviazione su disco locale, questo è il canale ritenuto più affidabile. È consigliabile per tutti gli scenari di produzione. Questo è il canale predefinito per le applicazioni ASP.NET e ASP.NET Core configurate in base alla documentazione ufficiale. Il canale è ottimizzato per scenari server con processi a esecuzione prolungata. Il metodo Flush() implementato da questo canale non è sincrono.

  Questo canale viene fornito come pacchetto NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel e viene acquisito automaticamente quando si usa il pacchetto NuGet Microsoft.ApplicationInsights.Web o Microsoft.ApplicationInsights.AspNetCore.

Configurare un canale di telemetria

Un canale di telemetria si configura impostandolo sulla configurazione di telemetria attiva. Per le applicazioni ASP.NET, la configurazione comporta l'impostazione dell'istanza del canale di telemetria su TelemetryConfiguration.Active oppure la modifica di ApplicationInsights.config. Per le applicazioni ASP.NET Core, la configurazione comporta l'aggiunta del canale al contenitore di inserimento delle dipendenze.

Nelle sezioni seguenti sono riportati degli esempi di configurazione dell'impostazione StorageFolder per il canale, in diversi tipi di applicazioni. StorageFolder è solo una delle impostazioni configurabili. Per l'elenco completo delle impostazioni di configurazione, vedere la sezioneImpostazioni configurabili nei canali, più avanti nel presente articolo.

Configurazione utilizzando le applicazioni ASP.NET ApplicationInsights.config

Nella sezione seguente di ApplicationInsights.config viene mostrato il canale ServerTelemetryChannel configurato con StorageFolder impostato su un percorso personalizzato:

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

Configurazione nel codice per le applicazioni ASP.NET

Il codice seguente configura un'istanza ServerTelemetryChannel con StorageFolder impostato su un percorso personalizzato. Aggiungere questo codice all'inizio dell'applicazione, in genere nel metodo Application_Start() 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;
}

Configurazione nel codice per le applicazioni ASP.NET Core

Modificare il metodo ConfigureServices della classe Startup.cs come illustrato di seguito:

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();
}

Configurazione nel codice per le app console .NET/.NET Core

Per le app console, il codice è il medesimo per .NET e .NET Core:

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

Dettagli sul funzionamento di ServerTelemetryChannel

ServerTelemetryChannel archivia gli elementi in arrivo in un buffer di memoria. Gli elementi vengono serializzati, compressi e archiviati in un'istanza Transmission una volta ogni 30 secondi, oppure quando nel buffer sono stati inseriti 500 elementi. Una singola istanza Transmission può contenere fino a 500 elementi e rappresenta un batch di dati di telemetria inviati tramite una singola chiamata HTTPS al servizio Application Insights.

Per impostazione predefinita, è possibile inviare in parallelo un massimo di 10 istanze Transmission. Se i dati di telemetria arrivano a velocità più elevate o se la rete o il back-end di Application Insights sono lenti, le istanze Transmission vengono archiviate in memoria. La capacità predefinita di questo buffer di memoria Transmission è di 5 MB. Quando si supera la capacità di memoria, le istanze Transmission vengono archiviate sul disco locale fino a un limite di 50 MB.

Le istanze Transmission vengono archiviate sul disco locale anche in caso di problemi di rete. Solo gli elementi archiviati su un disco locale non subiscono conseguenze dopo un arresto anomalo dell'applicazione. Essi vengono inviati ogni volta che si riavvia l'applicazione. Se i problemi di rete persistono, ServerTelemetryChannel userà una logica di backoff esponenziale in un periodo compreso tra 10 secondi e 1 ora prima di ritentare l'invio dei dati di telemetria.

Impostazioni configurabili nei canali

Per l'elenco completo delle impostazioni configurabili per ciascun canale, vedere:

• InMemoryChannel
• ServerTelemetryChannel

Di seguito sono riportate le impostazioni comunemente usate per ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: quantità massima di memoria, in byte, utilizzata dal canale per inserire le trasmissioni nel buffer di memoria. Quando la capacità massima viene raggiunta, i nuovi elementi vengono archiviati direttamente sul disco locale. Il valore predefinito è 5 MB. L'impostazione di un valore superiore comporta un minor utilizzo del disco, tuttavia si deve ricordare che gli elementi in memoria andranno persi in caso di arresto anomalo dell'applicazione.
• MaxTransmissionSenderCapacity: numero massimo di istanze Transmission che verranno inviate contemporaneamente ad Application Insights. Il valore predefinito è 10. Questa impostazione si può configurare con un numero maggiore; operazione consigliabile quando viene generato un enorme volume di dati di telemetria. Generalmente, un volume elevato si verifica durante i test di carico o quando il campionamento è disattivato.
• StorageFolder: la cartella usata dal canale per archiviare gli elementi su disco in base alle esigenze. In Windows si utilizza %LOCALAPPDATA% o %TEMP% se non viene esplicitamente specificato un altro percorso. In ambienti diversi da Windows, è necessario specificare una posizione valida, altrimenti i dati di telemetria non verranno archiviati sul disco locale.

Quale canale è consigliabile usare?

Si consiglia ServerTelemetryChannel per la maggior parte degli scenari di produzione che coinvolgano applicazioni a esecuzione prolungata. Il metodo Flush() implementato da ServerTelemetryChannel non è sincrono. Inoltre, non garantisce l'invio dalla memoria o dal disco di tutti gli elementi in sospeso.

Se si usa questo canale in scenari dove l'applicazione sta per arrestarsi, introdurre un ritardo dopo la chiamata a Flush(). L'esatta entità del ritardo necessario non è prevedibile. Essa dipende da fattori come il numero di elementi o di istanze Transmission in memoria, il numero di dischi, la quantità di dati trasmessi al back-end e se il canale si trova al centro di scenari di backoff esponenziali.

Se fosse necessario eseguire uno scaricamento sincrono, usare InMemoryChannel.

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

Il canale di Application Insights garantisce il recapito dei dati di telemetria? Altrimenti, quali sono gli scenari in cui si potrebbero perdere i dati di telemetria?

La risposta breve è che nessuno dei canali predefiniti offre una garanzia di tipo transazionale della consegna dei dati di telemetria al back-end. ServerTelemetryChannel è più avanzato rispetto a InMemoryChannel rispetto alla consegna affidabile, tuttavia il primo esegue solo un tentativo di invio dei dati di telemetria. I dati di telemetria si possono perdere anche in altre situazioni, inclusi questi scenari comuni:

• Gli elementi in memoria vanno persi in caso di arresto anomalo dell'applicazione.
• I dati di telemetria si perdono durante periodi prolungati con problemi di rete. I dati di telemetria vengono archiviati sul disco locale durante le interruzioni di rete o in caso di problemi con il back-end di Application Insights. Tuttavia, gli elementi più vecchi di 48 ore vengono eliminati.
• Le posizioni predefinite su disco per l'archiviazione dei dati di telemetria in Windows sono %LOCALAPPDATA% o %TEMP%. Solitamente queste posizioni nel computer sono locali. Se l'applicazione esegue fisicamente la migrazione da una posizione a un'altra, tutti i dati di telemetria archiviati nella posizione originale andranno persi.
• In App Web di Azure in Windows la posizione predefinita di archiviazione su disco è D:\local\LocalAppData. Questa posizione non è persistente. Infatti viene cancellata al riavvio dell'app, nelle operazioni di scalabilità e altre operazioni simili e, i dati di telemetria archiviati in tale posizione andranno persi. È possibile eseguire l'override dell'impostazione predefinita e specificare lo spazio di archiviazione in una posizione persistente, ad esempio D:\home. Tuttavia, tali posizioni persistenti vengono gestite dall'archiviazione remota e potrebbero essere lente.

Sebbene sia meno probabile, il canale potrebbe generare dei duplicati degli elementi di telemetria. Questo comportamento si verifica se ServerTelemetryChannel ritenta l'operazione a causa di un errore di rete o di timeout, quando i dati di telemetria sono stati recapitati al back-end, ma la risposta è andata perduta a causa di problemi di rete o di timeout.

ServerTelemetryChannel funziona su sistemi diversi da Windows?

Anche se il nome del pacchetto e dello spazio dei nomi include "WindowsServer", questo canale è supportato anche in sistemi diversi da Windows, con la seguente eccezione. Nei sistemi diversi da Windows, per impostazione predefinita, il canale non crea una cartella di archiviazione locale. È necessario creare una cartella di archiviazione locale e configurare il canale per utilizzarlo. Dopo aver configurato l'archiviazione locale, il canale funzionerà allo stesso modo in tutti i sistemi.

L'SDK crea una risorsa di archiviazione locale temporanea? I dati vengono crittografati nella risorsa di archiviazione?

L'SDK archivia gli elementi di telemetria nell'archiviazione locale se si verificano problemi di rete o in caso di limitazione della larghezza di banda della rete. Questi dati non vengono crittografati localmente.

Per i sistemi Windows, l'SDK crea automaticamente una cartella locale temporanea nella directory %TEMP% o %LOCALAPPDATA% e limita l'accesso agli amministratori e all'utente corrente.

Per i sistemi diversi da Windows, l'SDK non crea automaticamente alcuna risorsa di archiviazione locale, quindi per impostazione predefinita, i dati non vengono archiviati in locale.

È possibile creare manualmente una directory di archiviazione e configurare il canale per utilizzarlo. In questo caso, è fondamentale assicurarsi che la directory sia protetta. Altre informazioni sulla protezione e la privacy dei dati.

SDK open source

Come ogni SDK per Application Insights, i canali sono open source. Leggere e contribuire al codice o segnalare i problemi nel repository GitHub ufficiale.

Passaggi successivi

• Campionamento
• Risoluzione dei problemi SDK