Canali di telemetria in Application Insights

  • Articolo

I canali di telemetria sono parte integrante degli SDK di Application Insights. Gestiscono il buffering e la trasmissione dei dati di telemetria al servizio Application Insights. Le versioni di .NET e .NET Core degli SDK hanno due canali di telemetria predefiniti: InMemoryChannel e ServerTelemetryChannel. Questo articolo descrive ogni canale e illustra come personalizzare il comportamento del canale.

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights consiste nel raccogliere dati usando OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java.

Che cosa sono i canali di telemetria?

I canali di telemetria sono responsabili del buffering degli elementi di telemetria e dell'invio al servizio Application Insights, in cui vengono archiviati per l'esecuzione di query e l'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 gli inizializzatori di telemetria e i processori di telemetria. Pertanto, tutti gli elementi eliminati da un processore di telemetria non raggiungeranno il canale. Il Send() metodo non invia in genere gli elementi al back-end immediatamente. In genere, li memorizza nel buffer in memoria e li invia in batch per una trasmissione 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 e questo documento non è applicabile.

Canali di telemetria predefiniti

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

  • InMemoryChannel: canale leggero che memorizza nel buffer gli elementi in memoria fino a quando 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 riprova a inviare dati di telemetria dopo un errore. Questo canale non mantiene gli elementi su disco. Pertanto, eventuali elementi non inviati vengono persi in modo permanente al termine dell'arresto dell'applicazione, indipendentemente dal fatto che sia normale o meno. Questo canale implementa un Flush() metodo che può essere usato per forzare lo scaricamento sincrono di tutti gli elementi di telemetria in memoria. Questo canale è ideale 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 viene configurato nient'altro.

  • ServerTelemetryChannel: canale più avanzato con criteri di ripetizione dei tentativi e la possibilità di archiviare i dati in un disco locale. Questo canale ritenta l'invio di 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. È consigliabile per tutti gli scenari di produzione. Questo canale è l'impostazione predefinita per le applicazioni ASP.NET e ASP.NET Core configurate in base alla documentazione ufficiale. Questo canale è ottimizzato per scenari 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.

Configurare un canale di telemetria

Per configurare un canale di telemetria, impostarlo sulla configurazione di telemetria attiva. Per le applicazioni ASP.NET, la configurazione comporta l'impostazione dell'istanza del canale di telemetria su TelemetryConfiguration.Active o modificando ApplicationInsights.config. Per ASP.NET applicazioni Core, la configurazione prevede l'aggiunta del canale al contenitore di inserimento delle dipendenze.

Le sezioni seguenti illustrano 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 configurabili nei canali più avanti in questo articolo.

Configurazione tramite ApplicationInsights.config per le applicazioni ASP.NET

La sezione seguente di ApplicationInsights.config mostra il ServerTelemetryChannel canale 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 in Application_Start() 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 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 ASP.NET Core.

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 sono lente, 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 su disco locale anche in caso di problemi di rete. Solo gli elementi archiviati in un disco locale sopravvivono a un arresto anomalo dell'applicazione. Vengono inviati ogni volta che l'applicazione viene avviata di nuovo. Se i problemi di rete persistono, ServerTelemetryChannel userà una logica di backoff esponenziale compresa tra 10 secondi e 1 ora prima di riprovare a inviare i 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ù usate per ServerTelemetryChannel:

  • 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 inferiore del disco, ma tenere presente che gli elementi in memoria andranno persi in caso di arresto anomalo dell'applicazione.
  • MaxTransmissionSenderCapacity: numero massimo di Transmission istanze che verranno inviate ad Application Insights contemporaneamente. Il valore predefinito è 10. Questa impostazione può essere configurata in un numero maggiore, che è consigliabile quando viene generato un volume enorme di dati di telemetria. Un volume elevato si verifica in genere durante i test di carico o quando il campionamento è disattivato.
  • StorageFolder: cartella usata dal canale per archiviare gli elementi su disco in base alle esigenze. In Windows viene utilizzato %LOCALAPPDATA% o %TEMP% se non viene specificato in modo esplicito alcun altro percorso. In ambienti diversi da Windows, è necessario specificare una posizione valida o i dati di telemetria non verranno archiviati nel disco locale.

Quale canale è consigliabile usare?

È consigliabile ServerTelemetryChannel per la maggior parte degli scenari di produzione che coinvolgono applicazioni a esecuzione prolungata. Il Flush() metodo implementato da ServerTelemetryChannel non è sincrono. Non garantisce anche l'invio di tutti gli elementi in sospeso dalla memoria o dal disco.

Se si usa questo canale in scenari in cui l'applicazione sta per essere arrestata, introdurre qualche ritardo dopo la chiamata Flush()a . La quantità esatta di ritardo che potrebbe essere necessaria non è prevedibile. Dipende da fattori come il numero di elementi o Transmission istanze in memoria, il numero di dischi, il numero di dati trasmessi al back-end e se il canale si trova al centro di scenari di back-off esponenziali.

Se è 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? 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 del recapito dei dati di telemetria al back-end. ServerTelemetryChannel è più avanzato rispetto InMemoryChannel a per il recapito affidabile, ma fa anche solo un tentativo di inviare dati di telemetria. I dati di telemetria possono ancora essere persi in diverse situazioni, inclusi questi scenari comuni:

  • Gli elementi in memoria vengono persi quando l'applicazione si arresta in modo anomalo.
  • La telemetria viene persa durante lunghi periodi 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.
  • I percorsi predefiniti dei dischi per l'archiviazione dei dati di telemetria in Windows sono %LOCALAPPDATA% o %TEMP%. Queste posizioni sono in genere locali per il computer. Se l'applicazione esegue la migrazione fisicamente da una posizione a un'altra, tutti i dati di telemetria archiviati nella posizione originale andranno persi.
  • In Azure App Web in Windows, il percorso di archiviazione su disco predefinito è D:\local\LocalAppData. Questa posizione non è persistente. Viene cancellato nei riavvii dell'app, nelle istanze di scalabilità orizzontale e in altre operazioni di questo tipo, che comporta la perdita di dati di telemetria archiviati in tale posizione. È possibile eseguire l'override del valore predefinito e specificare lo spazio di 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. Questo comportamento si verifica quando ServerTelemetryChannel si ritenta a causa di un errore di rete o di un timeout, quando i dati di telemetria sono stati 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 successive, l'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 la ${TMPDIR} 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, l'archiviazione locale non viene creata e la configurazione manuale è ancora necessaria. Per informazioni dettagliate sull'implementazione, vedere questo repository GitHub.

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 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, quindi per impostazione predefinita non vengono archiviati dati in locale.

Nota

Con la versione 2.15.0-beta3 e successive, l'archiviazione locale viene ora creata automaticamente per Linux, Mac e Windows.

È possibile creare manualmente una directory di archiviazione e configurare il canale per usarlo. In questo caso, è necessario 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