Telemetrie der HTTP-Clientlatenz in .NET

Wenn Sie Anwendungen erstellen, die über HTTP kommunizieren, ist es wichtig, die Leistungsmerkmale der Anforderung zu beobachten. Die AddHttpClientLatencyTelemetry Erweiterung ermöglicht die Erfassung detaillierter Timing-Informationen für ausgehende HTTP-Aufrufe, ohne Änderungen am aufrufenden Code vorzunehmen. Es wird in die vorhandene HttpClientFactory Pipeline eingebunden, um Phasenzeiten über den Anforderungslebenszyklus hinweg zu erfassen, HTTP-Protokolldetails aufzuzeichnen, die Garbage Collection-Auswirkungen zu messen, wenn die Laufzeit diese Daten bereitstellt, und eine einheitliche Telemetrieform auszugeben, die für die Leistungsanalyse und die Optimierung geeignet ist. Aktivieren Sie diese Telemetrie, indem Sie die AddHttpClientLatencyTelemetry() Erweiterungsmethode aufrufen. Der integrierte Handler erstellt für jede ausgehende Anfrage eine ILatencyContext und füllt Metriken aus, sobald die innere Pipeline abgeschlossen ist. Nutzen Sie sie nach await base.SendAsync(...) in einem späteren Delegierungshandler (der nach der Erfassung der Telemetrie hinzugefügt wurde) und exportieren Sie sie an Ihr Metrikrücksystem. Beispiel:

Registererweiterungsmethode:

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();

Zugreifen auf den Kontext:

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;
    }
}

Hinzufügen des Pakets

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

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

Weitere Informationen finden Sie unter dotnet package add or Manage package dependencies in .NET applications.

Registrierung der HTTP-Clientlatenzmessungs-Telemetrie

Um Ihrer Anwendung HTTP-Clientlatenz-Telemetrie hinzuzufügen, rufen Sie die AddHttpClientLatencyTelemetry Erweiterungsmethode beim Konfigurieren Ihrer Dienste auf:

var builder = WebApplication.CreateBuilder(args);

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

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

Diese Registrierung fügt allen HTTP-Clients, die über DelegatingHandlererstellt wurden, einen IHttpClientFactory hinzu, der detaillierte Latenzinformationen für jede Anforderung sammelt.

Konfigurieren von Telemetrieoptionen

Sie konfigurieren die Telemetriesammlung über das HttpClientLatencyTelemetryOptions (Standardoptionenmuster). Sie können Werte entweder mit einem Delegat oder durch Konfigurationsbindung angeben (z. B. appsettings.json). Die Optionsinstanz wird einmal pro Handlerpipeline aufgelöst, sodass Änderungen auf neue Clients/Handler angewendet werden.

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

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

Konfigurationsoptionen

Die HttpClientLatencyTelemetryOptions Klasse bietet die folgenden Einstellungen:

Gesammelte Telemetriedaten

Wenn die Telemetrie der HTTP-Clientlatenz aktiviert ist, erfasst sie Phasenzeitstempel, ausgewählte Maßnahmen (sofern unterstützt) und Protokollattribute, die zur Leistungsanalyse verwendet werden.

Timingprüfpunkte

Zeitstempel werden für wichtige Phasen des HTTP-Anforderungslebenszyklus aufgezeichnet:

Maßnahmen (plattformabhängig)

Misst Latenzbeiträge, die durch Rohphasen-Checkpoints nicht erfasst werden können (GC-Pause-Überlappungen, Verbindungsumschläge, andere akkumulierte Anzahlen oder Dauern). Sie werden in einem In-Memory-Latenzkontext gesammelt, der beim Aufrufen von AddHttpClientLatencyTelemetry() erstellt wird. Nichts wird automatisch ausgegeben: Der Kontext sammelt einfach Prüfpunkte, Measures und Tags, bis die Anforderung abgeschlossen ist. Wenn Sie auch die HTTP-Clientprotokollanreicherung mit AddExtendedHttpClientLogging() aktivieren, wird der fertige Kontext zu einem einzigen strukturierten Protokollfeld mit dem Namen LatencyInfo (Versionsmarkierung, Servername, falls verfügbar, dann Tag, Prüfpunkt und Messname/Wert-Sequenzen) umgewandelt.

Dieses Protokollfeld ist das einzige integrierte Ausgabeartefakt. Es werden keine Metriken oder Ablaufverfolgungen erstellt, es sei denn, Sie fügen Ihren eigenen Exporter hinzu. Um sie als Metriken anzuzeigen, lesen Sie den Kontext, nachdem die Anforderungspipeline durchgelaufen ist, und zeichnen Sie z. B. die Überlappungen von GC-Pausen in einem Histogramm und die Verbindungsinitiierungen in einem Zähler auf, optional nach Protokollversion dimensioniert.

Stichwörter

Verwenden Sie Tags, um stabile kategorisierte Dimensionen an jede Anforderung anzufügen, sodass Sie Metriken und Protokolle segmentieren, filtern und aggregieren können, ohne Rohdaten erneut zu verarbeiten. Diese sind Klassifikationsbezeichnungen mit niedriger Kardinalität (keine zeitlichen Angaben), die im Latenzkontext erfasst werden. Wenn die HTTP-Client-Protokoll-Erweiterung aktiviert ist, werden sie in ein einzelnes LatencyInfo-Protokollfeld serialisiert. Aktivieren Sie die Anreicherung beim Starten der Anwendung, indem Sie die Protokollierungserweiterung (für alle Clients oder pro Client) zusammen mit Latenztelemetrie hinzufügen, z. B.:

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

Danach werden ausgehende Anforderungen, die über die strukturierte Protokollierungs-Pipeline protokolliert werden, die Eigenschaft LatencyInfo enthalten, welche die flachen Tags, Prüfpunkte und Maßnahmen umfasst. Für Tags werden keine Metriken oder Traces automatisch ausgegeben, exportieren Sie sie selbst (z. B. indem Sie Tagwerte in Metrikdimensionen oder Activity Tags umwandeln), wenn Sie sie außerhalb von Protokollen benötigen.

Verwendungsbeispiel

Diese Komponenten ermöglichen das Nachverfolgen und Melden der Latenz der HTTP-Clientanforderungsverarbeitung.

Sie können die Dienste mithilfe der folgenden Methoden registrieren:

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);

Beispiel:

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();

Überlegungen zur Plattform

Die Telemetrie der HTTP-Clientlatenz wird für alle unterstützten Ziele (.NET 9, .NET 8, .NET Standard 2.0 und .NET Framework 4.6.2) ausgeführt. Kern-Timing-Prüfpunkte werden immer gesammelt. Die GC Pause-Metrik (Http.GCPauseTime) wird nur ausgegeben, wenn sie auf .NET 8 oder .NET 9 ausgeführt wird. Die Implementierung erkennt Plattformfunktionen zur Laufzeit und ermöglicht, was ohne zusätzliche Konfiguration unterstützt wird.