Telemetria opóźnienia klienta HTTP na platformie .NET

Podczas tworzenia aplikacji komunikujących się za pośrednictwem protokołu HTTP ważne jest, aby obserwować charakterystykę wydajności żądań. AddHttpClientLatencyTelemetry Rozszerzenie umożliwia zbieranie szczegółowych informacji o czasie wykonania dla wychodzących wywołań HTTP bez zmian w kodzie wywołującym. Podłącza się do istniejącego potoku HttpClientFactory, aby przechwytywać czas trwania etapów w całym cyklu życia żądania, rejestrować szczegóły protokołu HTTP, mierzyć wpływ mechanizmu odzyskiwania pamięci (garbage collection), gdy środowisko uruchomieniowe udostępnia te dane, i emitować jednolitą strukturę telemetrii odpowiednią do analizy i optymalizacji wydajności. Aby włączyć tę telemetrię, wywołaj metodę rozszerzenia AddHttpClientLatencyTelemetry(). Wbudowana procedura obsługi tworzy żądanie ruchu wychodzącego ILatencyContext i wypełnia miary w czasie ukończenia potoku wewnętrznego. Korzystaj z nich po await base.SendAsync(...) w późniejszym delegującym handlerze (dodanym po telemetrii) i wyeksportuj je do systemu zarządzania metrykami. Przykład:

Metoda rejestrowania rozszerzenia:

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

Uzyskaj dostęp do kontekstu:

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

Dodawanie pakietu

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

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

Aby uzyskać więcej informacji, zobacz dotnet package add or Manage package dependencies in .NET applications (Dodawanie pakietów dotnet lub zarządzanie zależnościami pakietów w aplikacjach platformy .NET).

Rejestrowanie telemetrii opóźnień klienta HTTP

Aby dodać telemetrię opóźnienia klienta HTTP do aplikacji, wywołaj metodę AddHttpClientLatencyTelemetry rozszerzenia podczas konfigurowania usług:

var builder = WebApplication.CreateBuilder(args);

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

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

Ta rejestracja dodaje element DelegatingHandler do wszystkich klientów HTTP utworzonych za pomocą IHttpClientFactorymetody , zbierając szczegółowe informacje o opóźnieniu dla każdego żądania.

Konfigurowanie opcji telemetrii

Zbieranie danych telemetrycznych można skonfigurować za pomocą standardowego HttpClientLatencyTelemetryOptionswzorca opcji. Wartości można podać za pomocą delegata lub przez konfigurację wiązań (na przykład appsettings.json). Wystąpienie opcji jest rozpoznawane raz w potoku obsługi, więc zmiany mają zastosowanie do nowych klientów/obsług.

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

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

Opcje konfiguracji

Klasa HttpClientLatencyTelemetryOptions oferuje następujące ustawienia:

Zebrane dane telemetryczne

Po włączeniu telemetrii opóźnień klienta HTTP przechwytywane są znaczniki czasu faz, wybrane pomiary (tam, gdzie są obsługiwane) oraz atrybuty protokołu używane do analizy wydajności.

Punkty kontrolne chronometrażu

Znaczniki czasu są rejestrowane dla kluczowych etapów cyklu życia żądania HTTP:

Miary (zależne od platformy)

Miary kwantyfikują czynniki opóźnienia, których surowe punkty kontrolne fazy nie mogą zmierzyć (nakładanie się przestojów GC, zmiany w połączeniach, inne skumulowane liczby lub czasy trwania). Są one zbierane w kontekście opóźnienia w pamięci utworzonym podczas wywoływania metody AddHttpClientLatencyTelemetry(). Nic nie jest emitowane automatycznie: kontekst po prostu gromadzi punkty kontrolne, miary i tagi do momentu zakończenia żądania. Jeśli włączysz również wzbogacenie rejestrowania klienta HTTP za pomocą AddExtendedHttpClientLogging(), ukończony kontekst zostanie spłaszczony do pojedynczego pola dziennika strukturalnego o nazwie LatencyInfo (znacznik wersji, nazwa serwera, jeśli jest dostępna, a następnie tag, punkt kontrolny i sekwencje nazwy/wartości miary).

To pole dziennika jest jedynym wbudowanym artefaktem wyjściowym; nie są generowane żadne metryki ani ślady, chyba że dodajesz własnego eksportera. Aby wyświetlić je jako metryki, przeczytaj kontekst po powrocie potoku żądań i zarejestruj (na przykład) nakładanie się pauz GC na histogram oraz inicjacje połączeń do licznika, opcjonalnie z podziałem według wersji protokołu.

Etykiety

Użyj tagów, aby dołączyć stabilne wymiary kategorii do każdego żądania, aby można było segmentować, filtrować i agregować metryki i dzienniki bez ponownego przetwarzania danych pierwotnych. Są to etykiety klasyfikacji o niskiej kardynalności (nie pomiary czasu) przechwycone w kontekście opóźnienia i, jeśli włączono wzbogacanie logów klienta HTTP, serializowane w pojedynczym polu loga LatencyInfo. Aktywuj wzbogacanie podczas uruchamiania aplikacji, dodając rozszerzenie logowania (dla wszystkich klientów lub poszczególnych klientów) wraz z telemetrią opóźnień, na przykład:

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

Następnie żądania wychodzące rejestrowane za pośrednictwem potoku rejestrowania ustrukturyzowanego będą zawierać właściwość LatencyInfo z zawartymi uproszczonymi tagami, punktami kontrolnymi i miarami. Żadne metryki ani trasowanie nie są generowane automatycznie dla tagów; wyeksportuj je samodzielnie (np. zamień wartości tagów w wymiary metryk lub określenia Activity tagów), jeśli będą potrzebne poza dziennikami.

Przykład użycia

Te składniki umożliwiają śledzenie i raportowanie opóźnienia przetwarzania żądań klienta HTTP.

Usługi można zarejestrować przy użyciu następujących metod:

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

Przykład:

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

Zagadnienia dotyczące platformy

Telemetria opóźnienia klienta HTTP jest uruchamiana we wszystkich obsługiwanych miejscach docelowych (.NET 9, .NET 8, .NET Standard 2.0 i .NET Framework 4.6.2). Podstawowe punkty kontrolne chronometrażu są zawsze zbierane. Metryka zatrzymania GC (Http.GCPauseTime) jest emitowana tylko podczas pracy na platformie .NET 8 lub .NET 9. Implementacja wykrywa możliwości platformy w czasie wykonywania i umożliwia korzystanie z funkcji obsługiwanych bez dodatkowej konfiguracji.