Registrazione e traccia di .NET

Il codice può essere instrumentato per produrre un log, che funge da record di eventi interessanti che si sono verificati durante l'esecuzione del programma. Per comprendere il comportamento dell'applicazione, è possibile esaminare i log. La registrazione e la traccia incapsulano questa tecnica. .NET ha accumulato diverse API di registrazione nella cronologia e questo articolo consente di comprendere quali opzioni sono disponibili.

I termini "registrazione" e "traccia" sono comunemente sinonimi. La distinzione è che l'output di registrazione deve essere raccolto tutto il tempo e quindi dovrebbe avere un sovraccarico ridotto. La traccia è in genere più invasiva e raccoglie altre informazioni da parti più approfondite dell'applicazione e del runtime .NET. Viene usato per diagnosticare problemi specifici o automaticamente per brevi periodi di tempo come parte dei sistemi di analisi delle prestazioni più approfonditi.

Un altro perno sul termine di traccia è traccia distribuita. La traccia distribuita raccoglie dati di attività e di intervallo di alto livello per i sistemi basati su richieste, e correla le richieste tra i servizi per offrire una visualizzazione del modo in cui ogni richiesta viene elaborata dal sistema completo.

Differenze principali nelle API di registrazione

Registrazione strutturata

Le API di registrazione possono essere strutturate o non strutturate:

• Non strutturate: le voci di log hanno contenuto di testo in formato libero che deve essere visualizzato dagli esseri umani.
• Strutturate: le voci di log hanno uno schema ben definito e possono essere codificate in formati binari e testuali diversi. Questi log sono progettati per essere traducibili dal computer ed eseguire query in modo che sia gli esseri umani che i sistemi automatizzati possano usarli facilmente.

Le API che supportano la registrazione strutturata sono preferibili per un utilizzo non banale. Offrono maggiore funzionalità, flessibilità e prestazioni con poca differenza nell'usabilità.

Impostazione

Per casi d'uso semplici, è possibile usare le API che scrivono direttamente messaggi nella console o in un file. Ma la maggior parte dei progetti software troverà utile configurare quali eventi di log vengono registrati e come vengono salvati in modo permanente. Ad esempio, quando si esegue in un ambiente di sviluppo locale, potrebbe essere necessario restituire testo normale nella console per semplificare la leggibilità. Quindi, quando l'applicazione viene distribuita in un ambiente di produzione, è possibile passare alla visualizzazione dei log archiviati in un database dedicato o in un set di file in sequenza. Le API con opzioni di configurazione valide semplificano queste transizioni, mentre le opzioni meno configurabili richiedono l'aggiornamento del codice di strumentazione ovunque per apportare modifiche.

Sink

La maggior parte delle API di registrazione consente l'invio dei messaggi di log a destinazioni diverse denominate sink. Alcune API hanno un numero elevato di sink pre-creati, mentre altri ne hanno solo alcuni. Se non esiste alcun sink predefinito, in genere esiste un'API di estendibilità che consente di creare un sink personalizzato, anche se ciò richiede la scrittura di un po' più di codice.

API di registrazione .NET

ILogger

Per la maggior parte dei casi, se si aggiunge la registrazione a un progetto esistente o si crea un nuovo progetto, l'infrastruttura ILogger è una scelta predefinita ottimale. ILogger supporta la registrazione strutturata veloce, la configurazione flessibile e una raccolta di sink comuni inclusa la console, che è ciò che viene visualizzato quando si esegue un'app ASP.NET. Inoltre, l'interfaccia ILogger può fungere anche da facciata su molte implementazioni di registrazione di terze parti che offrono funzionalità avanzate ed estendibilità.

ILogger fornisce il brano di registrazione per l'implementazione di OpenTelemetry per .NET, che consente l'uscita dei log dall'applicazione a un'ampia gamma di sistemi APM per un'ulteriore analisi.

Eventsource

EventSource è un'API di traccia precedente e ad alte prestazioni con registrazione strutturata. Originariamente è stata progettata per integrarsi bene con Event Tracing for Windows (ETW), ma è stata successivamente estesa per supportare la traccia multipiattaforma EventPipe e EventListener per sink personalizzati. In confronto a ILogger, EventSource ha relativamente pochi sink di registrazione pre-creati e non è disponibile alcun supporto predefinito per la configurazione tramite file di configurazione separati. EventSource è eccellente se si vuole un maggiore controllo sull'integrazione ETW o EventPipe, ma per la registrazione per utilizzo generico, ILogger è più flessibile e più facile da usare.

Traccia

System.Diagnostics.Trace e System.Diagnostics.Debug sono .API di registrazione meno recenti di .NET. Queste classi hanno API di configurazione flessibili e un ampio ecosistema di sink, ma supportano solo la registrazione non strutturata. In .NET Framework, possono essere configurati tramite un file app.config, ma in .NET Core non esiste un meccanismo di configurazione integrato basato su file. Vengono in genere usati per produrre output di diagnostica per lo sviluppatore durante l'esecuzione nel debugger. Il team .NET continua a supportare queste API per scopi di compatibilità con le versioni precedenti, ma non verrà aggiunta alcuna nuova funzionalità. Queste API sono una scelta ottimale per le applicazioni che le usano già. Per le app più recenti che non hanno già eseguito il commit in un'API di registrazione, ILogger possono offrire funzionalità migliori.

API di registrazione specializzate

Console

La classe System.Console include i metodi Write e WriteLine che possono essere usati in scenari di registrazione semplici. Queste API sono molto facili da iniziare a usare, ma la soluzione non sarà flessibile come un'API di registrazione per utilizzo generico. La console consente solo la registrazione non strutturata e non è disponibile alcun supporto per la configurazione per selezionare i messaggi di log abilitati o per reindirzzare a un sink diverso. L'uso delle API ILogger o Trace con un sink della console non richiede molto lavoro aggiuntivo e mantiene la registrazione configurabile.

DiagnosticSource

System.Diagnostics.DiagnosticSource è destinato alla registrazione in cui i messaggi di log verranno analizzati in modo sincrono in-process anziché serializzati in qualsiasi risorsa di archiviazione. Ciò consente all'origine e al listener di scambiare oggetti .NET arbitrari come messaggi, mentre la maggior parte delle API di registrazione richiede che l'evento di log sia serializzabile. Questa tecnica può anche essere estremamente veloce, gestendo gli eventi di log in decine di nanosecondi se il listener viene implementato in modo efficiente. Gli strumenti che usano queste API spesso agiscono più come profiler in-process, anche se qui l'API non impone alcun vincolo.

EventLog

System.Diagnostics.EventLog è un'API di Windows che scrive i messaggi nel Registro eventi di Windows. In molti casi l'uso di ILogger con un sink EventLog facoltativo durante l'esecuzione in Windows può offrire funzionalità simili senza accoppiare strettamente l'app al sistema operativo Windows.