Telemetri latensi klien HTTP di .NET

Saat Anda membangun aplikasi yang berkomunikasi melalui HTTP, penting untuk mengamati karakteristik performa permintaan. Ekstensi ini AddHttpClientLatencyTelemetry memungkinkan pengumpulan informasi waktu terperinci untuk panggilan HTTP keluar tanpa perubahan pada kode panggilan. Ini dicolokkan ke pipa yang ada HttpClientFactory untuk menangkap waktu setiap tahap di seluruh siklus hidup permintaan, merekam detail protokol HTTP, mengukur dampak pengumpulan sampah ketika runtime menyediakan data tersebut, dan menghasilkan bentuk telemetri yang seragam yang cocok untuk analisis dan penyetelan performa. Aktifkan telemetri ini dengan memanggil AddHttpClientLatencyTelemetry() metode ekstensi. Handler bawaan membuat ILatencyContext untuk setiap permintaan keluar dan mengisi pengukuran pada saat alur dalam selesai. Konsumsi data setelah await base.SendAsync(...) pada handler delegasi berikutnya (ditambahkan setelah telemetri) dan ekspor ke platform backend metrik Anda. Contoh:

Daftarkan metode ekstensi:

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

Akses konteks:

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

Menambahkan paket

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

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

Untuk informasi selengkapnya, lihat menambahkan paket dotnet atau Mengelola dependensi paket di aplikasi .NET.

Mendaftarkan telemetri latensi klien HTTP

Untuk menambahkan telemetri latensi klien HTTP ke aplikasi Anda, panggil AddHttpClientLatencyTelemetry metode ekstensi saat mengonfigurasi layanan Anda:

var builder = WebApplication.CreateBuilder(args);

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

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

Pendaftaran ini menambahkan DelegatingHandler ke semua klien HTTP yang dibuat melalui IHttpClientFactory, mengumpulkan informasi latensi terperinci untuk setiap permintaan.

Mengonfigurasi opsi telemetri

Anda mengonfigurasi pengumpulan telemetri melalui HttpClientLatencyTelemetryOptions (pola opsi standar). Anda dapat menyediakan nilai baik dengan delegate atau dengan cara mengikat konfigurasi (misalnya, appsettings.json). Instans opsi diselesaikan sekali per alur handler sehingga perubahan berlaku untuk klien/handler baru.

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

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

Opsi konfigurasi

Kelas ini HttpClientLatencyTelemetryOptions menawarkan pengaturan berikut:

Data telemetri yang dikumpulkan

Ketika telemetri latensi klien HTTP diaktifkan, ia menangkap tanda waktu fase, ukuran yang dipilih (jika didukung), dan atribut protokol yang digunakan untuk analisis performa.

Titik pemeriksaan waktu

Tanda waktu direkam untuk tahap kunci siklus hidup permintaan HTTP:

Pengukuran (bergantung pada platform)

Pengukuran mengkuantifikasi faktor penyumbang latensi yang tidak dapat dijangkau oleh titik pemeriksaan fase mentah (seperti tumpang tindih jeda GC, churn koneksi, jumlah atau durasi akumulasi lainnya). Mereka dikumpulkan dalam konteks latensi dalam memori yang dibuat saat Anda memanggil AddHttpClientLatencyTelemetry(). Tidak ada yang dipancarkan secara otomatis: konteks hanya mengumpulkan titik pemeriksaan, ukuran, dan tag hingga permintaan selesai. Jika Anda juga mengaktifkan pengayaan pengelogan klien HTTP dengan AddExtendedHttpClientLogging(), konteks yang selesai diratakan ke dalam satu bidang log terstruktur bernama LatencyInfo (penanda versi, nama server jika tersedia, lalu tandai, titik pemeriksaan, dan ukur urutan nama/nilai).

Bidang log tersebut adalah satu-satunya artefak output tertanam; tidak ada metrik atau pelacakan yang diproduksi kecuali Anda menambahkan pengekspor Anda sendiri. Untuk menjadikannya metrik, baca konteks setelah alur permintaan selesai dan kemudian rekam, misalnya, tumpang tindih jeda GC ke dalam histogram dan inisiasi koneksi ke penghitung, dan opsional dapat didimensikan berdasarkan versi protokol.

Tagar

Gunakan tag untuk melampirkan dimensi kategoris yang stabil ke setiap permintaan sehingga Anda dapat membuat segmentasi, memfilter, dan mengagregasi metrik dan log tanpa memproses ulang data mentah. Mereka adalah label klasifikasi dengan kardinalitas rendah (bukan waktu) yang diambil dalam konteks latensi dan, jika pengayaan log klien HTTP diaktifkan, diserialisasikan menjadi satu bidang log LatencyInfo. Aktifkan pengayaan di startup aplikasi dengan menambahkan ekstensi pengelogan (untuk semua klien atau per klien) bersama dengan telemetri latensi, misalnya:

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

Setelah ini, permintaan keluar yang dicatat melalui alur pengelogan terstruktur akan mencakup LatencyInfo properti yang berisi tag, titik pemeriksaan, dan ukuran yang diratakan. Tidak ada metrik atau traces yang dihasilkan secara otomatis untuk tag; ekspor sendiri (misalnya, ubah nilai tag menjadi dimensi metrik atau Activity tag) jika Anda membutuhkannya di luar catatan log.

Contoh penggunaan

Komponen-komponen ini memungkinkan pelacakan dan pelaporan latensi pemrosesan permintaan klien HTTP.

Anda dapat mendaftarkan layanan menggunakan metode berikut:

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

Contohnya:

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

Pertimbangan platform

Telemetri latensi klien HTTP berjalan pada semua target yang didukung (.NET 9, .NET 8, .NET Standard 2.0, dan .NET Framework 4.6.2). Titik pemeriksaan waktu penting selalu dicatat. Metrik jeda GC (Http.GCPauseTime) hanya dipancarkan saat berjalan pada .NET 8 atau .NET 9. Implementasi mendeteksi kemampuan platform pada runtime dan mengaktifkan apa yang didukung tanpa konfigurasi tambahan.