Osservabilità di .NET con OpenTelemetry

Articolo
10/25/2024

Quando si esegue un'applicazione, si vuole sapere quanto questa sia efficace e rilevare potenziali problemi prima che si amplifichino. A tale scopo, è possibile generare dati di telemetria, ad esempio log o metriche dall'app, quindi monitorare e analizzare tali dati.

Che cos'è l'osservabilità?

L'osservabilità nel contesto di un sistema distribuito è la possibilità di monitorare e analizzare i dati di telemetria sullo stato di ciascun componente, di poter osservare le modifiche nelle prestazioni e di diagnosticare il motivo per cui si verificano tali modifiche. A differenza del debug, che è invasivo e può influire sul funzionamento dell'applicazione, l'osservabilità è progettata per essere trasparente per l'operazione primaria e avere un impatto sufficientemente ridotto sulle prestazioni, tanto che può essere usata in modo continuato.

L'osservabilità viene in genere eseguita usando una combinazione di:

Log, che registrano singole operazioni, ad esempio una richiesta in ingresso, un errore in un componente specifico o un ordine da effettuare.
Metriche, che misurano contatori e misuratori, ad esempio il numero di richieste completate, le richieste attive, i widget venduti o un istogramma della latenza della richiesta.
Traccia distribuita, che tiene traccia delle richieste e delle attività tra i componenti in un sistema distribuito, in modo da poter vedere dove viene impiegato il tempo e tenere traccia di errori specifici.

Insieme, log, metriche e traccia distribuita sono talvolta noti come i tre pilastri dell'osservabilità.

Ogni pilastro può includere dati di telemetria da:

Runtime .NET, come Garbage Collector o il compilatore JIT.
Librerie, ad esempio da Kestrel (il server Web ASP.NET) e HttpClient.
Telemetria specifica dell'applicazione generata dal codice.

Approcci di osservabilità in .NET

Esistono diversi modi per ottenere l'osservabilità nelle applicazioni .NET:

In modo esplicito nel codice, facendo riferimento a e usando una libreria come OpenTelemetry. Se si ha accesso al codice sorgente ed è possibile ricompilare l'app, questo è il meccanismo più potente e configurabile.
Out-of-process attraverso l’utilizzo di EventPipe. Strumenti come dotnet-monitor possono “ascoltare” i log e le metriche e quindi elaborarli senza influire sul codice.
Usando un hook di avvio, gli assembly possono essere inseriti nel processo che può quindi raccogliere la strumentazione. Un esempio di tale approccio è OpenTelemetry .NET Automatic Instrumentation.

Che cos'è OpenTelemetry?

OpenTelemetry (OTel) è uno standard multipiattaforma aperto per la raccolta e la generazione di dati di telemetria. OpenTelemetry include:

API per le librerie utilizzabili per registrare i dati di telemetria durante l'esecuzione del codice.
API che gli sviluppatori di applicazioni usano per configurare la parte dei dati registrati che verranno inviati in rete, dove verranno inviati e come potranno essere filtrati, memorizzati nel buffer, arricchiti e trasformati.
Le convenzioni semantiche forniscono indicazioni sulla denominazione e sul contenuto dei dati di telemetria. È importante che le app che producono dati di telemetria e gli strumenti che ricevono tali dati concordino sul significato dei diversi tipi di dati e su quali tipi di dati sono utili, in modo che gli strumenti possano fornire un'analisi efficace.
Interfaccia per gli esportatori. Gli esportatori sono plug-in che consentono la trasmissione dei dati di telemetria in formati specifici a back-end di telemetria diversi.
Il protocollo di collegamento OTLP è un'opzione di protocollo di rete indipendente dal fornitore finalizzato alla trasmissione dei dati di telemetria. Alcuni strumenti e fornitori supportano questo protocollo oltre ai protocolli proprietari preesistenti di cui potrebbero essere dotati.

L'impiego di OTel consente l'uso di un'ampia gamma di sistemi APM, tra cui sistemi open source come Prometheus e Grafana, Monitoraggio di Azure, il prodotto APM di Microsoft in Azure o dei numerosi fornitori di APM che collaborano con OpenTelemetry.

Sono disponibili implementazioni di OpenTelemetry per la maggior parte dei linguaggi e delle piattaforme, tra cui .NET.

Implementazione .NET di OpenTelemetry

L'implementazione di .NET di OpenTelemetry è leggermente diversa da altre piattaforme, perché .NET fornisce le API di registrazione, di metriche e attività nel framework. Ciò significa che OTel non deve fornire API che gli autori di librerie sono tenuti a utilizzare. L'implementazione OTel di .NET usa queste API della piattaforma per la strumentazione:

Architettura OTel di .NET

OTel entra in gioco nel momento in cui raccoglie i dati di telemetria da tali API e da altre origini (tramite librerie di strumentazione) per poi esportarli in un sistema di monitoraggio delle prestazioni dell'applicazione (APM) per archiviazione e analisi. Il vantaggio offerto da OTel come standard di settore è un meccanismo comune per la raccolta, gli schemi comuni e la semantica per i dati di telemetria e un'API per il modo in cui le API possono integrarsi con OTel. L'uso di OTel significa che le applicazioni non devono usare API o strutture di dati specifiche di APM, ma funzionano secondo lo standard OTel. Le API possono indifferentemente implementare un componente di esportazione specifico di APM o usare OTLP, un nuovo standard di trasmissione per l'esportazione dei dati di telemetria nei sistemi APM.

Pacchetti OpenTelemetry

OpenTelemetry in .NET viene implementato come una serie di pacchetti NuGet che formano un paio di categorie:

API Core
Strumentazione: questi pacchetti raccolgono la strumentazione dal runtime e dalle librerie comuni.
Utilità di esportazione: queste si interfacciano con sistemi APM come Prometheus, Jaeger e OTLP.

Nella tabella seguente vengono descritti i pacchetti principali.

Nome pacchetto	Descrizione
OpenTelemetry	Libreria principale che fornisce la funzionalità OTEL di base
OpenTelemetry.Instrumentation.AspNetCore	Strumentazione per ASP.NET Core e Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Strumentazione per il client gRPC per tenere traccia delle chiamate gRPC in uscita
OpenTelemetry.Instrumentation.Http	Strumentazione per `HttpWebRequest` e `HttpClient` finalizzata a tenere traccia delle chiamate HTTP in uscita
OpenTelemetry.Instrumentation.SqlClient	Strumentazione per il `SqlClient` utilizzato per tracciare le operazioni del database
OpenTelemetry.Exporter.Console	Utilità di esportazione per la console, comunemente usata per diagnosticare i dati di telemetria da esportare
OpenTelemetry.Exporter.OpenTelemetryProtocol	Esportazione tramite il protocollo OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore	Utilità di esportazione per Prometheus implementata con un endpoint ASP.NET Core
OpenTelemetry.Exporter.Zipkin	Utilità di esportazione per la traccia Zipkin

Esempi

Questo argomento è continuato con un paio di procedure dettagliate di esempio per l'uso di OpenTelemetry in .NET:

OpenTelemetry in .NET Aspira

.NET Aspire è un set di estensioni per .NET per semplificare la creazione e l'uso di applicazioni distribuite. Uno dei vantaggi dell'uso di .NET Aspire è che i dati di telemetria sono incorporati, usando le librerie OpenTelemetry per .NET. I modelli di progetto predefiniti per .NET Aspire contengono un ServiceDefaults progetto, parte di cui configurare e configurare OTel. Il progetto Service Defaults viene fatto riferimento e inizializzato da ogni servizio in una soluzione .NET Aspire.

Il modello di progetto Service Defaults include i pacchetti OTel SDK, ASP.NET, HttpClient e Strumentazione runtime e quelli configurati nel Extensions.cs file. Per l'esportazione dei dati di telemetria .NET Aspire include l'utilità di esportazione OTLP per impostazione predefinita, in modo che possa fornire la visualizzazione dei dati di telemetria usando il dashboard Di aspirare.

Il dashboard aspiratore è progettato per portare l'osservazione dei dati di telemetria al ciclo di debug locale, che consente agli sviluppatori non solo di garantire che le applicazioni producano dati di telemetria, ma anche di usare tali dati di telemetria per diagnosticare tali applicazioni localmente. Essere in grado di osservare le chiamate tra i servizi sta dimostrando di essere altrettanto utile in fase di debug come nell'ambiente di produzione. Il dashboard .NET Aspire viene avviato automaticamente quando si f5 il AppHost progetto da Visual Studio o dotnet run il AppHost progetto.

Per altri dettagli su .NET Aspire, vedere:

Riutilizzo del progetto Service Defaults senza .NET Aspire Orchestration

Probabilmente il modo più semplice per configurare OTel per i progetti ASP.NET consiste nell'usare il progetto aspirare le impostazioni predefinite del servizio aspirare, anche se non si usa il resto di .NET Aspire, ad esempio AppHost per l'orchestrazione. Il progetto Service Defaults è disponibile come modello di progetto tramite Visual Studio o dotnet new. Configura OTel e configura l'utilità di esportazione OTLP. È quindi possibile usare le variabili di ambiente OTel per configurare l'endpoint OTLP a cui inviare dati di telemetria e fornire le proprietà delle risorse per l'applicazione.

I passaggi per usare ServiceDefaults all'esterno di .NET Aspire sono:

Aggiungere il progetto ServiceDefaults alla soluzione usando Aggiungi nuovo progetto in Visual Studio oppure usare dotnet new aspire-servicedefaults --output ServiceDefaults
Fare riferimento al progetto ServiceDefaults dall'applicazione ASP.NET. In Visual Studio usare "Aggiungi -> Riferimento al progetto" e selezionare il progetto ServiceDefaults "
Chiamare la funzione di installazione di OpenTelemetry come parte dell'inizializzazione del generatore di applicazioni.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Le impostazioni predefinite del servizio possono configurare le funzionalità aggiuntive seguenti, se necessario tramite AddServiceDefaults() o le funzioni specifiche:

Controlli di integrità con /health gli endpoint e /alive
Individuazione dei servizi che sarà un no-op senza il resto di .NET Aspira
Configurazione della resilienza per HttpClient che ritenta la richiesta in caso di errori

Condividi tramite