Telemetria della latenza del client HTTP in .NET

Quando si creano applicazioni che comunicano tramite HTTP, è importante osservare le caratteristiche delle prestazioni delle richieste. L'estensione AddHttpClientLatencyTelemetry consente la raccolta di informazioni dettagliate sulla tempistica per le chiamate HTTP in uscita senza modifiche al codice chiamante. Si collega alla pipeline esistente HttpClientFactory per acquisire i tempi delle fasi nell'intero ciclo di vita delle richieste, registrare i dettagli del protocollo HTTP, misurare l'impatto della raccolta dei rifiuti laddove il runtime espone tali dati e generare una telemetria uniforme adatta per l'analisi e il miglioramento delle prestazioni. Abilita la telemetria chiamando il metodo di estensione AddHttpClientLatencyTelemetry(). Il gestore predefinito crea un ILatencyContext per ciascuna richiesta in uscita e popola le misure al completamento della pipeline interna. Usarli dopo await base.SendAsync(...) in un gestore di delega successivo (aggiunto dopo la telemetria) ed esportarli nel back-end delle metriche. Esempio:

Registra metodo di estensione:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Http.Diagnostics;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// An example of some accessor that is able to read latency context
builder.Services.AddSingleton<ILatencyContextAccessor, LatencyContextAccessor>();

// Register HTTP client latency telemetry first so its delegating handler runs earlier.
builder.Services.AddHttpClientLatencyTelemetry();

// Register export handler (runs after telemetry; sees finalized ILatencyContext).
builder.Services.AddTransient<HttpLatencyExportHandler>();

// Register an HttpClient that will emit and export latency measures.
builder.Services
    .AddHttpClient("observed")
    .AddHttpMessageHandler<HttpLatencyExportHandler>();

var host = builder.Build();
await host.RunAsync();

Accedere al contesto:

public sealed class HttpLatencyExportHandler : DelegatingHandler
{
    // ILatencyContextAccessor is just an example of some accessor that is able to read latency context
    private readonly ILatencyContextAccessor _latency;

    public HttpLatencyExportHandler(ILatencyContextAccessor latency) => _latency = latency;

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
    {
        var rsp = await base.SendAsync(request, ct).ConfigureAwait(false);

        var ctx = _latency.Current;
        if (ctx != null)
        {
            var data = ctx.LatencyData;
            // Record/export gc and conn with version as a dimension here.
        }
        return rsp;
    }
}

Aggiungere il pacchetto

dotnet add package Microsoft.Extensions.Http.Diagnostics --version 9.10.0

<PackageReference Include="Microsoft.Extensions.Http.Diagnostics" Version="9.10.0" />

Per altre informazioni, vedere dotnet package add or Manage package dependencies in .NET applications (Aggiungere o gestire le dipendenze dei pacchetti nelle applicazioni .NET).

Registrare i dati di telemetria della latenza del client HTTP

Per aggiungere la telemetria della latenza client HTTP alla tua applicazione, chiama il metodo di estensione AddHttpClientLatencyTelemetry quando configuri i tuoi servizi:

var builder = WebApplication.CreateBuilder(args);

// Add HTTP client factory
builder.Services.AddHttpClient();

// Add HTTP client latency telemetry
builder.Services.AddHttpClientLatencyTelemetry();

Questa registrazione aggiunge DelegatingHandler a tutti i client HTTP creati tramite IHttpClientFactory, raccogliendo informazioni dettagliate sulla latenza per ogni richiesta.

Configurare le opzioni di telemetria

È possibile configurare la raccolta di dati di telemetria tramite il HttpClientLatencyTelemetryOptions(modello di opzioni standard). È possibile specificare valori con un delegato o tramite la configurazione di binding, ad esempio appsettings.json. L'istanza delle opzioni viene risolta una volta per ogni pipeline del gestore, in modo che le modifiche vengano applicate ai nuovi client/gestori.

// Configure with delegate
builder.Services.AddHttpClientLatencyTelemetry(options =>
{
    options.EnableDetailedLatencyBreakdown = true;
});

// Or configure from configuration
builder.Services.AddHttpClientLatencyTelemetry(
builder.Configuration.GetSection("HttpClientTelemetry"));

Opzioni di configurazione

La HttpClientLatencyTelemetryOptions classe offre le impostazioni seguenti:

Dati di telemetria raccolti

Quando la telemetria della latenza client HTTP è abilitata, acquisisce i timestamp di fase, le misure selezionate (se supportate) e gli attributi del protocollo usati per l'analisi delle prestazioni.

Checkpoint di intervallo

I timestamp vengono registrati per le fasi chiave del ciclo di vita delle richieste HTTP:

Misure (dipendente dalla piattaforma)

Le misure quantificano i fattori di latenza che i checkpoint di fase grezzi non possono (sovrapposizione GC, fluttuazione della connessione, altri conteggi accumulati o durate). Vengono raccolti in un contesto di latenza in memoria creato quando si chiama AddHttpClientLatencyTelemetry(). Nulla viene emesso automaticamente: il contesto accumula semplicemente checkpoint, misure e tag fino al completamento della richiesta. Se si abilita anche l'arricchimento del log client HTTP con AddExtendedHttpClientLogging(), il contesto completato viene appiattito in un singolo campo di log strutturato denominato LatencyInfo (marcatore di versione, nome del server, se disponibile, tag, checkpoint e sequenze nome/valore delle misurazioni).

Il campo del log è l'unico artefatto di output predefinito; non vengono prodotte metriche o tracce, a meno che non si aggiunga il proprio esportatore. Per esporle come metriche, leggere il contesto dopo che la pipeline di richiesta ha completato la sua esecuzione e registrare, ad esempio, la sovrapposizione delle pause GC in un istogramma e le iniziazioni di connessione in un contatore, eventualmente categorizzate per versione del protocollo.

Etichette

Usare i tag per allegare dimensioni categoriche stabili a ogni richiesta in modo da poter segmentare, filtrare e aggregare metriche e log senza rielaborare i dati non elaborati. Sono etichette per la classificazione a bassa cardinalità (non intervalli temporali) acquisite nel contesto della latenza e, se l'arricchimento del log del client HTTP è abilitato, serializzate in un singolo campo di log LatencyInfo. Abilitare l'arricchimento all'avvio dell'applicazione aggiungendo l'estensione di logging (per tutti i client o per singolo client) insieme alla telemetria di latenza, ad esempio:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHttpClientLatencyTelemetry(); // enables latency context + measures/tags
builder.Services.AddExtendedHttpClientLogging();
var app = builder.Build();

Successivamente, le richieste in uscita registrate tramite la pipeline di logging strutturato includeranno la proprietà LatencyInfo contenente i tag appiattiti, i checkpoint e le misure. Nessuna metrica o traccia viene emessa automaticamente per i tag; si devono esportare manualmente (ad esempio, trasformare i valori dei tag in dimensioni metriche o tag Activity) se sono necessari al di fuori dei log.

Esempio di utilizzo

Questi componenti consentono di tenere traccia e segnalare la latenza dell'elaborazione delle richieste client HTTP.

È possibile registrare i servizi usando i metodi seguenti:

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services);

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services,
    IConfigurationSection section);

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services,
    Action<HttpClientLatencyTelemetryOptions> configure);

Per esempio:

var builder = Host.CreateApplicationBuilder(args);

// Register IHttpClientFactory:
builder.Services.AddHttpClient();

// Register redaction services:
builder.Services.AddRedaction();

// Register latency context services:
builder.Services.AddLatencyContext();

// Register HttpClient logging enrichment & redaction services:
builder.Services.AddExtendedHttpClientLogging();

// Register HttpClient latency telemetry services:
builder.Services.AddHttpClientLatencyTelemetry();

var host = builder.Build();

Considerazioni sulla piattaforma

La telemetria della latenza del client HTTP funziona su tutte le piattaforme supportate (.NET 9, .NET 8, .NET Standard 2.0 e .NET Framework 4.6.2). I checkpoint temporali di base vengono sempre raccolti. La metrica di sospensione GC (Http.GCPauseTime) viene generata solo quando è in esecuzione in .NET 8 o .NET 9. L'implementazione rileva le funzionalità della piattaforma in fase di esecuzione e abilita ciò che è supportato senza configurazione aggiuntiva.