Usare OpenTelemetry con OTLP e la dashboard Aspire

Questo articolo illustra come instrumentare un'API Web .NET con OpenTelemetry e inviare i log, le metriche e le tracce al Aspire dashboard usando OTLP. È possibile aggiungere i pacchetti OpenTelemetry, configurare metriche e tracce personalizzate e visualizzare i risultati nel dashboard.

Il Aspire dashboard è una parte standard di Aspire, ma è disponibile anche come contenitore Docker autonomo che fornisce un endpoint OTLP per l'invio dei dati di telemetria. Il dashboard visualizza i log, le metriche e le tracce. L'utilizzo del dashboard in questo modo non dipende da Aspire e consente di visualizzare la telemetria proveniente da qualsiasi app che la invia tramite OTLP. Funziona altrettanto bene per le app scritte in Java, Go o Python, purché possano inviare i dati di telemetria a un endpoint OTLP.

Il Aspire dashboard richiede meno operazioni di configurazione e meno passaggi di installazione rispetto a soluzioni open source come Prometheus, Grafana e Jaeger. A differenza di questi strumenti, il Aspire dashboard è uno strumento di visualizzazione per sviluppatori, non uno strumento di monitoraggio della produzione.

1. Creare il progetto

Creare un semplice progetto API Web tramite il modello ASP.NET Core Empty in Visual Studio o tramite il seguente comando .NET CLI:

dotnet new web

2. Fare riferimento ai pacchetti OpenTelemetry

Per aggiungere i pacchetti OpenTelemetry, usare il Gestione pacchetti NuGet oppure eseguire i comandi seguentidotnet add package:

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

In alternativa, aggiungere gli elementi seguenti PackageReference direttamente al file di progetto:

<ItemGroup>
  <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.19.1" />
  <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.19.1" />
  <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.19.0" />
  <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.19.0" />
</ItemGroup>

Nota

Poiché le API OTel sono in continua evoluzione, usare le versioni più recenti.

3. Aggiungere direttive di using

Aggiungere le direttive seguenti using all'inizio del file:

using System.Diagnostics;
using System.Diagnostics.Metrics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

4. Aggiungere metriche e definizioni di attività

Il codice seguente definisce una nuova metrica (greetings.count) che conta quante volte un client chiama l'API e una nuova origine attività (Otel.Example). Inserire questo codice prima di builder.Build:

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

5. Configurare OpenTelemetry con i provider corretti

Inserire il codice seguente prima di builder.Build:

// Configure the shared OTLP connection used by logs, metrics, and traces.
var otlpEndpoint = new Uri(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]!);
Action<OtlpExporterOptions> configureOtlp = options =>
{
    options.Endpoint = otlpEndpoint;
    options.Protocol = OtlpExportProtocol.Grpc;
    options.Headers = builder.Configuration["OTEL_EXPORTER_OTLP_HEADERS"]; // To secure endpoint (not in this example)
};

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
    logging.AddOtlpExporter(configureOtlp);
});

var otel = builder.Services.AddOpenTelemetry();

// Identify this application as a single service in the Aspire dashboard.
otel.ConfigureResource(resource => resource.AddService(builder.Configuration["OTEL_SERVICE_NAME"]!));

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();

    // Our custom metrics
    metrics.AddMeter(greeterMeter.Name);

    // Metrics provided by ASP.NET Core in .NET
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");

    // Export the metrics via OTLP
    metrics.AddOtlpExporter(configureOtlp);
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
    tracing.AddOtlpExporter(configureOtlp);
});

Questo codice configura OpenTelemetry con le diverse origini di telemetria:

• Aggiunge un provider OTel a ILogger per raccogliere i record di log.
• Configura le metriche, registrando provider di strumentazione e contatori per ASP.NET e il contatore personalizzato.
• Configura il tracciamento e registra i provider di instrumentazione e il componente personalizzato ActivitySource.

Registra quindi l'esportatore OTLP, utilizzando le variabili d'ambiente per la sua configurazione.

6. Configurare le impostazioni OTLP

È possibile configurare l'utilità di esportazione OTLP tramite API nel codice, nelle variabili di ambiente o nella configurazione dell'applicazione. Per questo esempio, aggiungere le impostazioni OTLP alla radice di appsettings.Development.json, dopo la Logging sezione :

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
  "OTEL_SERVICE_NAME": "OTLP-Example"
}

Aggiungi altre impostazioni per l'esportatore OTLP .NET o impostazioni OTel comuni come OTEL_RESOURCE_ATTRIBUTES per definire gli attributi della risorsa.

Nota

ASP.NET Core carica sia appsettings.json che appsettings.Development.json. Le impostazioni in appsettings.Development.json sostituiscono le impostazioni duplicate in appsettings.json quando si esegue l'app nell'ambiente di sviluppo.

7. Creare un endpoint API

Inserire il codice seguente tra builder.Build e app.Run():

app.MapGet("/", SendGreeting);

Inserire la seguente funzione in fondo al file:

async Task<string> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

Nota

La definizione dell'endpoint non usa elementi specifici di OpenTelemetry. Usa le API .NET per l'osservabilità.

8. Avviare il Aspire contenitore Dashboard

Usare docker per scaricare ed eseguire il contenitore del dashboard.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

I dati visualizzati nella dashboard possono essere sensibili. Per impostazione predefinita, il dashboard richiede un token di autenticazione per l'accesso. Il contenitore visualizza questo token nell'output.

Copiare l'URL, sostituire 0.0.0.0 con localhost, ad esempio , http://localhost:18888/login?t=123456780abcdef123456780e aprirlo nel browser. In alternativa, incollare la chiave dopo /login?t= nella finestra di dialogo di accesso. Il token cambia ogni volta che si avvia il contenitore.

9. Eseguire il progetto

Eseguire il progetto con dotnet run. L'output della console visualizza gli URL su cui l'app è in ascolto, ad esempio:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5086

Usare la porta mostrata nell'output della console, perché potrebbe essere diversa dagli esempi descritti in questo articolo. Usare un browser o curl per accedere all'API su tale porta:

curl -k http://localhost:5086

Ogni volta che si richiede la pagina, aumenta il numero di messaggi di saluto.

9.1 Output del log

Il codice registra le istruzioni utilizzando ILogger. Per impostazione predefinita, .NET abilita il provider di console, che indirizza l'output alla console.

È possibile esportare i log da .NET in diversi modi:

• Sistemi di container come stdout reindirizzano l'output di stderr e nei file di log.
• Usare le librerie di registrazione che si integrano con ILogger, ad esempio Serilog e NLog.
• Usare provider di registrazione per OTel, ad esempio OTLP. La sezione di registrazione del codice nel passaggio 5 aggiunge il provider OTel.

Il dashboard mostra i log come log strutturati. Tutte le proprietà impostate nel messaggio di log diventano campi nel record di log.

9.2 Visualizzazione metriche

Il Aspire dashboard mostra le metriche per ogni risorsa. Una risorsa è il termine usato in OTel per indicare una fonte di telemetria, ad esempio un processo. Quando si seleziona una risorsa, il dashboard elenca ogni metrica inviata dalla risorsa all'endpoint OTLP. L'elenco delle metriche è dinamico e viene aggiornato man mano che il dashboard riceve nuove metriche.

La visualizzazione delle metriche dipende dal tipo di metrica usato:

• Il dashboard mostra direttamente i contatori.
• Per gli istogrammi che registrano un valore per richiesta, ad esempio una durata o i byte inviati per richiesta, la dashboard raccoglie i valori in una serie di bucket e rappresenta graficamente i percentili P50, P90 e P99. I risultati dell'istogramma possono includere esemplari, che sono singoli punti dati insieme all'ID di traccia/intervallo per tale richiesta. Il dashboard mostra questi elementi come puntini nel grafico. Selezionare uno per passare alla rispettiva traccia, in modo da visualizzare il valore causato. Questa funzionalità aiuta a individuare gli outlier.
• Le metriche possono includere dimensioni, ovvero coppie chiave/valore associate ai singoli valori. Il dashboard aggrega i valori per dimensione. Usa i menu a discesa nella vista per filtrare i risultati in base a dimensioni specifiche, ad esempio solo GET richieste, oppure un percorso URL specifico in ASP.NET.

9.3 Vista di tracciamento

La vista di tracciamento elenca le tracce. Ogni traccia è un set di attività che condividono lo stesso ID traccia. Gli span tengono traccia del lavoro e ogni span rappresenta un'unità di lavoro. L'elaborazione di una richiesta ASP.NET crea un intervallo. L'esecuzione di una richiesta HttpClient è un intervallo. Tenendo traccia dell'elemento padre di ogni intervallo, si crea una gerarchia di intervalli che è possibile visualizzare. Quando si raccolgono intervalli da ogni risorsa (processo), è possibile tenere traccia del lavoro in una serie di servizi. Le richieste HTTP includono un'intestazione che passa l'ID di traccia e l'ID dello span padre al servizio successivo. Ogni risorsa deve raccogliere i dati di telemetria e inviarli allo stesso agente di raccolta, che quindi aggrega e presenta una gerarchia degli intervalli.

Il dashboard mostra un elenco di tracce con informazioni di riepilogo. Ogni volta che il dashboard rileva intervalli con un nuovo ID di traccia, aggiunge una riga alla tabella. Selezionare Visualizza per visualizzare tutti gli intervalli nella traccia.

Selezionare un intervallo per visualizzarne i dettagli, incluse le proprietà nell'intervallo, ad esempio il greeting tag impostato nel passaggio 7.