Canali di telemetria in Application Insights

I canali di telemetria sono parte integrante degli SDK di Azure Application Insights. Gestiscono il buffering e la trasmissione di dati di telemetria al servizio Application Insights. Le versioni .NET e .NET Core degli SDK dispongono di due canali di telemetria predefiniti: InMemoryChannel e ServerTelemetryChannel. Questo articolo descrive in dettaglio ogni canale, tra cui come personalizzare il comportamento del canale.

Quali sono i canali di telemetria?

I canali di telemetria sono responsabili del buffering degli elementi di telemetria e li inviano al servizio Application Insights, in cui vengono archiviati per eseguire query e analisi. Un canale di telemetria è qualsiasi classe che implementa l'interfaccia Microsoft.ApplicationInsights.ITelemetryChannel .

Il Send(ITelemetry item) metodo di un canale di telemetria viene chiamato dopo che vengono chiamati tutti i inizializzatori di telemetria e i processori di telemetria. Pertanto, tutti gli elementi eliminati da un processore di telemetria non raggiungeranno il canale. Send() in genere non invia gli elementi al back-end immediatamente. In genere, li buffera in memoria e li invia in batch, per una trasmissione efficiente.

Live Metrics Stream include anche un canale personalizzato che consente lo streaming live dei dati di telemetria. Questo canale è indipendente dal canale di telemetria regolare e questo documento non viene applicato.

Canali di telemetria predefiniti

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

  • InMemoryChannel: canale leggero che buffera gli elementi in memoria finché non vengono inviati. Gli elementi vengono memorizzati nel buffer in memoria e scaricati una volta ogni 30 secondi o ogni volta che vengono memorizzati nel buffer 500 elementi. Questo canale offre garanzie di affidabilità minime perché non prova a inviare dati di telemetria dopo un errore. Questo canale non mantiene gli elementi su disco, quindi tutti gli elementi non inviati vengono persi definitivamente all'arresto dell'applicazione (con grazia o meno). Questo canale implementa un Flush() metodo che può essere usato per forzare lo scaricamento di eventuali elementi di telemetria in memoria in modo sincrono. Questo canale è adatto per le applicazioni a breve esecuzione in cui è ideale uno scaricamento sincrono.

    Questo canale fa parte del pacchetto NuGet Microsoft.ApplicationInsights più grande ed è il canale predefinito usato dall'SDK quando non è configurato altro.

  • ServerTelemetryChannel: canale più avanzato con criteri di ripetizione dei tentativi e capacità di archiviare i dati in un disco locale. Questo canale esegue il tentativo di invio dei dati di telemetria se si verificano errori temporanei. Questo canale usa anche l'archiviazione su disco locale per mantenere gli elementi su disco durante interruzioni di rete o volumi di telemetria elevati. A causa di questi meccanismi di ripetizione dei tentativi e dell'archiviazione su disco locale, questo canale è considerato più affidabile ed è consigliato per tutti gli scenari di produzione. Questo canale è il valore predefinito per le applicazioni ASP.NET e ASP.NET Core configurate in base alla documentazione ufficiale. Questo canale è ottimizzato per gli scenari del server con processi a esecuzione prolungata. Il Flush() metodo 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 NuGet.

Configurare un canale di telemetria

È possibile configurare un canale di telemetria impostandolo sulla configurazione dei dati di telemetria attiva. Per le applicazioni ASP.NET, la configurazione comporta l'impostazione dell'istanza del canale di telemetria su TelemetryConfiguration.Activeo modificando ApplicationInsights.config. Per le applicazioni core di ASP.NET, la configurazione prevede l'aggiunta del canale al contenitore di inserimento delle dipendenze.

Le sezioni seguenti mostrano esempi di configurazione dell'impostazione StorageFolder per il canale in vari tipi di applicazione. StorageFolder è solo una delle impostazioni configurabili. Per l'elenco completo delle impostazioni di configurazione, vedere la sezione impostazioni più avanti in questo articolo.

Configurazione usando ApplicationInsights.config per le applicazioni di ASP.NET

La sezione seguente da ApplicationInsights.config mostra il ServerTelemetryChannel canale configurato con StorageFolder impostato su una posizione personalizzata:

    <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 di 'ServerTelemetryChannel' con StorageFolder impostata su una posizione personalizzata. Aggiungere questo codice all'inizio dell'applicazione, in genere nel Application_Start() metodo 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 core di ASP.NET

Modificare il ConfigureServices metodo della Startup.cs classe, 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();
}

Importante

La configurazione del canale tramite TelemetryConfiguration.Active non è supportata per le applicazioni core di ASP.NET.

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

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

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

Dettagli operativi di ServerTelemetryChannel

ServerTelemetryChannel archivia gli elementi in arrivo in un buffer in memoria. Gli elementi vengono serializzati, compressi e archiviati in un'istanza Transmission una volta ogni 30 secondi o quando sono stati memorizzati nel buffer 500 elementi. Una singola Transmission istanza contiene 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 Transmission istanze. Se i dati di telemetria arrivano a velocità più veloci o se la rete o il back-end di Application Insights è lenta, Transmission le istanze vengono archiviate in memoria. La capacità predefinita di questo buffer in memoria Transmission è di 5 MB. Quando la capacità in memoria è stata superata, Transmission le istanze vengono archiviate su disco locale fino a un limite di 50 MB. Transmission le istanze vengono archiviate sul disco locale anche quando si verificano problemi di rete. Solo gli elementi archiviati in un disco locale superino un arresto anomalo dell'applicazione. Vengono inviati ogni volta che l'applicazione viene avviata di nuovo. Se i problemi di rete persisteranno, ServerTelemetryChannel userà una logica di backoff esponenziale compresa tra 10 secondi e 1 ora prima di riprovare a inviare dati di telemetria.

Impostazioni configurabili nei canali

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

Di seguito sono riportate le impostazioni più comunemente usate per ServerTelemetryChannel:

  1. MaxTransmissionBufferCapacity: quantità massima di memoria, in byte, usata dal canale per memorizzare nel buffer le trasmissioni in memoria. Quando viene raggiunta questa capacità, i nuovi elementi vengono archiviati direttamente sul disco locale. Il valore predefinito è 5 MB. L'impostazione di un valore superiore comporta un utilizzo minore del disco, ma tenere presente che gli elementi in memoria verranno persi se l'applicazione si arresta in modo anomalo.

  2. MaxTransmissionSenderCapacity: numero massimo di Transmission istanze che verranno inviate a Application Insights contemporaneamente. Il valore predefinito è 10. Questa impostazione può essere configurata in un numero maggiore, consigliato quando viene generato un volume enorme di dati di telemetria. Il volume elevato si verifica in genere durante i test di carico o quando il campionamento viene disattivato.

  3. StorageFolder: cartella usata dal canale per archiviare gli elementi su disco in base alle esigenze. In Windows, %LOCALAPPDATA% o %TEMP% viene usato se non viene specificato in modo esplicito alcun altro percorso. Negli ambienti diversi da Windows, è necessario specificare una posizione valida o i dati di telemetria non verranno archiviati nel disco locale.

Quale canale è consigliabile usare?

ServerTelemetryChannel è consigliato per la maggior parte degli scenari di produzione che coinvolgono applicazioni a esecuzione prolungata. Il Flush() metodo implementato da ServerTelemetryChannel non è sincrono e non garantisce anche l'invio di tutti gli elementi in sospeso dalla memoria o dal disco. Se si usa questo canale negli scenari in cui l'applicazione sta per arrestare, è consigliabile introdurre un ritardo dopo la chiamata Flush(). La quantità esatta di ritardo che potrebbe essere necessaria non è prevedibile. Dipende da fattori come il numero di elementi o Transmission istanze in memoria, quanti sono su disco, quanti vengono trasmessi al back-end e se il canale si trova al centro di scenari di back-off esponenziali.

Se è necessario eseguire uno scaricamento sincrono, è consigliabile usare InMemoryChannel.

Domande frequenti

Il canale Application Insights garantisce il recapito dei dati di telemetria? In caso contrario, quali sono gli scenari in cui i dati di telemetria possono essere persi?

La risposta breve è che nessuno dei canali predefiniti offre una garanzia di tipo transazione di recapito dei dati di telemetria al back-end. ServerTelemetryChannel è più avanzato rispetto InMemoryChannel al recapito affidabile, ma rende anche solo un tentativo ottimale di inviare dati di telemetria. I dati di telemetria possono comunque essere persi in diverse situazioni, inclusi questi scenari comuni:

  1. Gli elementi in memoria vengono persi quando l'applicazione si arresta in modo anomalo.

  2. I dati di telemetria si perdono durante periodi estesi di problemi di rete. I dati di telemetria vengono archiviati su disco locale durante interruzioni di rete o quando si verificano problemi con il back-end di Application Insights. Tuttavia, gli elementi precedenti a 48 ore vengono eliminati.

  3. I percorsi predefiniti dei dischi per l'archiviazione dei dati di telemetria in Windows sono %LOCALAPPDATA% o %TEMP%. Queste posizioni sono in genere locali nel computer. Se l'applicazione esegue la migrazione fisicamente da una posizione a un'altra, i dati di telemetria archiviati nella posizione originale vengono persi.

  4. In App Web di Azure in Windows, il percorso predefinito di archiviazione su disco è D:\local\LocalAppData. Questa posizione non è persistente. Viene cancellata nei riavvii dell'app, nelle scalabilità orizzontale e in altre operazioni, causando la perdita di dati di telemetria archiviati. È possibile eseguire l'override dell'impostazione predefinita e specificare l'archiviazione in una posizione persistente come D:\home. Tuttavia, tali posizioni persistenti vengono gestite dall'archiviazione remota e quindi possono essere lente.

Anche se meno probabile, è anche possibile che il canale possa causare elementi di telemetria duplicati. Ciò si verifica quando ServerTelemetryChannel si verificano tentativi a causa di errori di rete/timeout, quando i dati di telemetria sono stati effettivamente recapitati al back-end, ma la risposta è stata persa a causa di problemi di rete o si è verificato un timeout.

ServerTelemetryChannel funziona su sistemi diversi da Windows?

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

Nota

Con la versione 2.15.0-beta3 e una maggiore risorsa di archiviazione locale viene ora creata automaticamente per Linux, Mac e Windows. Per i sistemi non Windows, l'SDK creerà automaticamente una cartella di archiviazione locale in base alla logica seguente:

  • ${TMPDIR} - se ${TMPDIR} la variabile di ambiente è impostata, viene usata questa posizione.
  • /var/tmp - se la posizione precedente non esiste si prova /var/tmp.
  • /tmp - se entrambe le posizioni precedenti non esistono, si prova tmp.
  • Se nessuna di queste posizioni esiste spazio di archiviazione locale non viene creato e la configurazione manuale è ancora necessaria. Per informazioni dettagliate sull'implementazione.

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

L'SDK archivia gli elementi di telemetria nell'archiviazione locale durante i problemi di rete o durante la limitazione. Questi dati non vengono crittografati in locale.

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, nessuna risorsa di archiviazione locale viene creata automaticamente dall'SDK e quindi nessun dato viene archiviato localmente per impostazione predefinita.

Nota

Con la versione 2.15.0-beta3 e una maggiore risorsa di archiviazione locale viene ora creata automaticamente per Linux, Mac e Windows.

È possibile creare una directory di archiviazione autonomamente e configurare il canale per usarlo. In questo caso, si è responsabili della sicurezza della directory. Altre informazioni sulla protezione dei dati e sulla privacy.

SDK open source

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

Passaggi successivi