Guida passo dopo passo al tracciamento delle transazioni distribuite in microservizi .NET con OpenTelemetry e Lescopr

Laptop with some program code in python
Scopri come configurare il tracciamento end-to-end delle transazioni distribuite in .NET con OpenTelemetry e Lescopr, per ottenere visibilità completa sui tuoi microservizi.

Il passaggio da architetture monolitiche a microservizi in .NET introduce complessità significative nella gestione delle transazioni distribuite. Senza un sistema di tracciamento efficiente, diventa impossibile identificare colli di bottiglia, errori o latenze che attraversano più servizi. OpenTelemetry offre uno standard aperto per la raccolta di dati di telemetria, mentre Lescopr fornisce la piattaforma per visualizzarli, analizzarli e agire di conseguenza.

Questa guida ti accompagnerà dalla configurazione iniziale alla visualizzazione dei primi tracciati, con un approccio pratico e senza presupporre competenze pregresse.

Cos’è il tracciamento distribuito e perché è essenziale in .NET

Il tracciamento distribuito (o distributed tracing) è una tecnica che consente di seguire il percorso di una richiesta attraverso tutti i microservizi coinvolti in una transazione. Ogni richiesta riceve un ID univoco (trace ID) che viene propagato tra i servizi, permettendo di correlare log, metriche e errori in un’unica vista.

In un ambiente .NET, dove i microservizi comunicano tramite HTTP, gRPC o message broker, il tracciamento distribuito risponde a domande critiche:

  • Dove si verifica un errore in un flusso che attraversa 5 servizi?
  • Quale microservizio introduce una latenza eccessiva?
  • Come si comporta una transazione sotto carico?

Senza tracciamento distribuito, i team SRE e backend devono analizzare log isolati, perdendo il contesto globale e allungando il MTTR (Mean Time To Repair).

Prerequisiti: cosa serve prima di iniziare

Prima di configurare il tracciamento, assicurati di avere:

  • Un’applicazione .NET (Core 3.1+ o .NET 5+) suddivisa in almeno due microservizi.
  • Accesso a un ambiente di sviluppo locale o a un cluster Kubernetes/containerizzato.
  • OpenTelemetry .NET SDK installato (versione 1.5+ consigliata).
  • Un account Lescopr (la versione free tier è sufficiente per testare).

Se non hai ancora un progetto .NET, puoi creare un esempio minimo con:

 dotnet new webapi -n OrderService
 dotnet new webapi -n PaymentService

Passo 1: Configurare OpenTelemetry nei microservizi .NET

OpenTelemetry è lo standard de facto per la telemetria in ambienti cloud-native. Per integrarlo in .NET, segui questi passaggi:

1.1 Aggiungere i pacchetti NuGet necessari

In ogni microservizio, installa i seguenti pacchetti via NuGet Package Manager o CLI:

 dotnet add package OpenTelemetry
 dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
 dotnet add package OpenTelemetry.Extensions.Hosting
 dotnet add package OpenTelemetry.Instrumentation.AspNetCore
 dotnet add package OpenTelemetry.Instrumentation.Http

Questi pacchetti abilitano:

  • La raccolta automatica di span (unità di tracciamento) per le richieste HTTP.
  • L’esportazione dei dati tramite OTLP (OpenTelemetry Protocol), il protocollo standard per l’invio a backend come Lescopr.

1.2 Configurare OpenTelemetry nel Program.cs

Modifica il file Program.cs di ogni microservizio per inizializzare OpenTelemetry. Ecco un esempio minimo:

using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Configura OpenTelemetry con il nome del servizio
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddService(serviceName: builder.Environment.ApplicationName))
    .WithTracing(tracerProviderBuilder => tracerProviderBuilder
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("https://otlp.lescopr.com/v1/traces");
            options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;
        }));

var app = builder.Build();
app.Run();

Nota importante:

  • Sostituisci https://otlp.lescopr.com/v1/traces con l’endpoint OTLP fornito da Lescopr (disponibile nella dashboard sotto Settings > Data Ingestion).
  • Il serviceName deve essere univoco per ogni microservizio (es. OrderService, PaymentService).

1.3 Abilitare la propagazione del contesto

Per garantire che il trace ID e il span ID vengano propagati tra i servizi, assicurati che le chiamate HTTP tra microservizi includano gli header OpenTelemetry. Con il pacchetto OpenTelemetry.Instrumentation.Http, questa propagazione è automatica per le richieste uscenti.

Se usi gRPC, installa anche:

 dotnet add package OpenTelemetry.Instrumentation.GrpcNetClient

Passo 2: Configurare Lescopr per ricevere i dati OpenTelemetry

Lescopr è una piattaforma APM che supporta nativamente OpenTelemetry. Per ricevere i dati dai tuoi microservizi:

2.1 Creare un progetto in Lescopr

  1. Accedi alla dashboard Lescopr.
  2. Clicca su Nuovo Progetto e seleziona OpenTelemetry.
  3. Assegna un nome al progetto (es. ECommerce-Microservices).
  4. Copia l’endpoint OTLP e la chiave API generati automaticamente.

2.2 Configurare l’autenticazione

Nel codice del passo 1.2, aggiorna la configurazione di OtlpExporter per includere la chiave API:

.AddOtlpExporter(options =>
{
    options.Endpoint = new Uri("https://otlp.lescopr.com/v1/traces");
    options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;
    options.Headers = "Authorization=Bearer TUA_CHIAVE_API";
})

Sostituisci TUA_CHIAVE_API con il valore copiato da Lescopr.

Passo 3: Generare e visualizzare i primi tracciati

3.1 Avviare i microservizi

Esegui i tuoi microservizi localmente o in un ambiente di test:

 dotnet run --project OrderService
 dotnet run --project PaymentService

3.2 Inviare una richiesta di test

Usa un tool come Postman o curl per inviare una richiesta che attraversi più servizi. Ad esempio:

curl -X POST http://localhost:5000/orders -H "Content-Type: application/json" -d '{"productId": 123}'

3.3 Visualizzare i tracciati in Lescopr

  1. Accedi alla dashboard Lescopr.
  2. Seleziona il progetto creato in precedenza.
  3. Vai alla sezione Traces (Tracciati).
  4. Dovresti vedere una lista di trace con:
    • Trace ID: l’ID univoco della transazione.
    • Durata: il tempo totale della richiesta.
    • Servizi coinvolti: i microservizi attraversati.

Clicca su una trace per visualizzare:

  • Il waterfall chart che mostra la sequenza delle chiamate.
  • Gli span dettagliati per ogni operazione (es. GET /products, POST /payments).
  • Gli errori e le latenze associati a ogni span.

Passo 4: Ottimizzare la configurazione

4.1 Configurare il sampling

Il tracciamento distribuito può generare un volume elevato di dati. Per evitare costi eccessivi e impatti sulle prestazioni, configura il sampling:

.WithTracing(tracerProviderBuilder => tracerProviderBuilder
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .SetSampler(new AlwaysOnSampler()) // Traccia tutto (sconsigliato in produzione)
    // Oppure:
    .SetSampler(new TraceIdRatioBasedSampler(0.1)) // Traccia il 10% delle richieste
)

In produzione, usa un sampler adattivo (es. ParentBasedTraceIdRatio) per tracciare solo le richieste con errori o latenze anomale.

4.2 Aggiungere attributi personalizzati

Per arricchire i tracciati con dati specifici del tuo dominio, aggiungi attributi personalizzati agli span:

var activity = Activity.Current;
if (activity != null)
{
    activity.SetTag("user.id", userId);
    activity.SetTag("order.value", orderValue);
}

Questi attributi saranno visibili in Lescopr e potranno essere usati per filtrare o aggregare i dati.

4.3 Monitorare gli SLA

In Lescopr, puoi configurare SLA dashboard per monitorare:

  • Il tasso di successo delle transazioni.
  • La latenza media e il 95° percentile.
  • Il tasso di errore per servizio.

Vai su Dashboards > Nuovo Dashboard e aggiungi widget per:

  • Error Rate (tasso di errore).
  • Latency (latenza).
  • Throughput (numero di richieste al secondo).

Passo 5: Risolvere problemi comuni

5.1 Trace ID non propagati

Problema: Gli span non sono correlati tra loro.

Soluzione:

  • Verifica che tutti i microservizi usino la stessa versione di OpenTelemetry.
  • Assicurati che le chiamate HTTP includano gli header traceparent e tracestate.
  • Se usi un API Gateway (es. NGINX, Traefik), configura la propagazione degli header.

5.2 Dati non visibili in Lescopr

Problema: I tracciati non appaiono nella dashboard.

Soluzione:

  • Controlla che l’endpoint OTLP sia corretto.
  • Verifica che la chiave API sia valida e non scaduta.
  • Usa un tool come OpenTelemetry Collector per debuggare l’invio dei dati.

5.3 Impatto sulle prestazioni

Problema: Aumento della latenza dopo l’aggiunta di OpenTelemetry.

Soluzione:

  • Ridurre il sampling rate (es. dal 100% al 10%).
  • Usare batch processing per l’esportazione:
    .AddOtlpExporter(options =>
{
    options.BatchSize = 100;
    options.ExportTimeoutMilliseconds = 5000;
})
  • Disabilitare l’instrumentazione automatica per librerie non critiche.

Best practice per il tracciamento distribuito in .NET

Per massimizzare il valore del tracciamento distribuito, segui queste best practice:

  • Nomenclatura coerente: Usa nomi descrittivi per i servizi (es. OrderService invece di Service1).
  • Attributi standardizzati: Adotta convenzioni per gli attributi (es. http.method, http.status_code).
  • Aggiornamenti regolari: Mantieni aggiornati i pacchetti OpenTelemetry per beneficiare delle ultime ottimizzazioni.
  • Integrazione con i log: Correla i tracciati con i log usando il trace ID come chiave.
  • Allerte proattive: Configura allerte in Lescopr per errori ricorrenti o aumenti di latenza.

Conclusione

Il tracciamento distribuito è fondamentale per garantire osservabilità e affidabilità in architetture microservizi .NET. Con OpenTelemetry come standard e Lescopr come piattaforma di monitoraggio, puoi ottenere una visibilità completa sulle tue transazioni, riducendo il tempo necessario per identificare e risolvere i problemi.

Per approfondire, la documentazione di Lescopr descrive la configurazione passo dopo passo.