Pengelogan klien HTTP di .NET

Saat Anda membuat aplikasi yang membuat permintaan HTTP, pengelogan terstruktur membantu Anda memantau, memecahkan masalah, dan menganalisis lalu lintas keluar. Ekstensi ini AddExtendedHttpClientLogging menyediakan pengelogan yang ditingkatkan untuk semua klien HTTP yang dibuat dengan IHttpClientFactory, dengan dukungan bawaan untuk:

• Pengelogan yang dapat dikonfigurasi - Mengontrol apa yang dicatat (header, isi, parameter kueri, parameter rute)
• Redaksi data - Menerapkan klasifikasi data dan kebijakan penyensoran untuk privasi dan kepatuhan
• Peningkatan log - Tambahkan konteks khusus ke log permintaan HTTP
• Overhead minimal - Fitur opsional dengan default yang memperhatikan kinerja

Aktifkan pengelogan klien HTTP yang ditingkatkan dengan memanggil AddExtendedHttpClientLogging metode ekstensi. Ini menggantikan pencatat klien HTTP default dengan pencatat yang diperluas yang mendukung fitur konfigurasi dan kepatuhan data yang halus.

Menambahkan paket

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

<PackageReference Include="Microsoft.Extensions.Http.Diagnostics"
                  Version="*" /> <!-- Adjust version -->

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

Aktifkan pengelogan klien HTTP

Untuk menambahkan pencatatan klien HTTP yang ditingkatkan ke aplikasi Anda, panggil AddExtendedHttpClientLogging metode ekstensi saat mengonfigurasi layanan Anda:

using Microsoft.Extensions.DependencyInjection;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

// Add enhanced HTTP client logging
builder.Services.AddExtendedHttpClientLogging();

// Add your HTTP clients
builder.Services.AddHttpClient<MyApiClient>();

using IHost host = builder.Build();

await host.RunAsync();

Pendaftaran ini menambahkan pencatat yang ditingkatkan ke semua klien HTTP yang dibuat melalui IHttpClientFactory, mengganti pencatat default dengan yang mendukung konfigurasi tingkat lanjut.

Menerapkan pengelogan ke klien HTTP tertentu

Anda juga dapat menerapkan pengelogan yang ditingkatkan ke klien HTTP bernama atau yang ditik tertentu menggunakan IHttpClientBuilder metode ekstensi:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

// Apply to a named client
builder.Services.AddHttpClient("MyNamedClient")
    .AddExtendedHttpClientLogging();

// Apply to a typed client with configuration
builder.Services.AddHttpClient<MyApiClient>()
    .AddExtendedHttpClientLogging(options =>
    {
        options.LogBody = true;
        options.ResponseBodyContentTypes.Add("application/json");
    });

using IHost host = builder.Build();

await host.RunAsync();    

Saat menggunakan IHttpClientBuilder overload, pencatatan hanya diterapkan pada klien tersebut, dan bukan secara global.

Menampilkan data log yang diperkaya

Pencatatan klien HTTP yang ditingkatkan menambahkan informasi ke log menggunakan pengayaan, yang berarti data ditambahkan sebagai tag ke log terstruktur daripada ke pesan konsol. Untuk melihat informasi yang diperkaya, gunakan penyedia pengelogan yang mendukung log terstruktur.

Untuk pengujian cepat, gunakan AddJsonConsole untuk mencetak log terstruktur ke konsol:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddJsonConsole();

builder.Services.AddRedaction();

builder.Services.AddHttpClient("MyClient")
    .AddExtendedHttpClientLogging(options =>
    {
        options.LogBody = true;
        options.ResponseBodyContentTypes.Add("application/json");
    });

Untuk skenario produksi, pertimbangkan untuk menggunakan penyedia pengelogan terstruktur seperti Application Insights, Seq, atau Elasticsearch yang dapat mengkueri dan memvisualisasikan data tag yang diperkaya.

Mengonfigurasi opsi pengelogan

Anda mengonfigurasi pencatatan klien HTTP melalui kelas LoggingOptions menggunakan pola opsi standar. Anda dapat mengonfigurasi opsi dalam kode atau mengikatnya dari konfigurasi (misalnya, appsettings.json).

Mengonfigurasi dengan delegasi

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Log request headers with data classification
    options.RequestHeadersDataClasses.Add("User-Agent", DataClassification.None);
    options.RequestHeadersDataClasses.Add("Authorization", DataClassification.Unknown);

    // Log response headers
    options.ResponseHeadersDataClasses.Add("Content-Type", DataClassification.None);

    // Enable request/response body logging (use carefully in production)
    options.LogBody = true;
    options.BodySizeLimit = 4096; // Limit to 4KB
    options.RequestBodyContentTypes.Add("application/json");
    options.ResponseBodyContentTypes.Add("application/json");
});

Konfigurasi dari appsettings.json

{
  "HttpClientLogging": {
    "LogRequestStart": false,
    "LogBody": false,
    "BodySizeLimit": 32768,
    "BodyReadTimeout": "00:00:01",
    "RequestHeadersDataClasses": {
      "User-Agent": "None",
      "Content-Type": "None"
    },
    "ResponseHeadersDataClasses": {
      "Content-Type": "None"
    },
    "RequestPathLoggingMode": "Formatted",
    "RequestPathParameterRedactionMode": "Strict"
  }
}

builder.Services.AddExtendedHttpClientLogging(
    builder.Configuration.GetSection("HttpClientLogging"));

Opsi konfigurasi

Kelas ini LoggingOptions menyediakan opsi konfigurasi berikut:

Opsi pengelogan dasar

Pencatatan header dan parameter kueri

Pembuatan log parameter jalur dan rute

Menambahkan pengaya log

Pengaya log klien HTTP memungkinkan Anda menambahkan informasi kontekstual kustom ke log klien HTTP berdasarkan permintaan, respons, dan pengecualian apa pun. Tidak seperti pengaya log tujuan umum, pengaya klien HTTP secara khusus menargetkan permintaan HTTP keluar dan memiliki akses ke konteks khusus HTTP.

Berikut adalah contoh singkatnya:

public class CustomHttpLogEnricher : IHttpClientLogEnricher
{
    public void Enrich(IEnrichmentTagCollector collector,
        HttpRequestMessage request, HttpResponseMessage? response, Exception? exception)
    {
        // Add tags based on the exception (if available)
        if (exception is not null)
        {
            collector.Add("error_type", exception.GetType().Name);
        }
    }
}

// Register the enricher
builder.Services.AddHttpClientLogEnricher<CustomHttpLogEnricher>();

Untuk informasi terperinci tentang membuat dan menggunakan pengaya log klien HTTP, termasuk praktik terbaik dan skenario tingkat lanjut, lihat pengaya log klien HTTP.

Klasifikasi dan redaksi data

Pengelogan klien HTTP terintegrasi dengan fitur redaksi data dan klasifikasi data untuk melindungi informasi sensitif. Saat Anda menentukan DataClassification untuk header, parameter kueri, atau parameter rute, sistem redaksi menerapkan redaksi yang sesuai berdasarkan redactor yang dikonfigurasi.

Contoh: Meredaksi header sensitif

using Microsoft.Extensions.Compliance.Classification;

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Public headers - no redaction
    options.RequestHeadersDataClasses.Add("User-Agent", DataClassification.None);
    options.RequestHeadersDataClasses.Add("Content-Type", DataClassification.None);

    // Sensitive headers - apply redaction
    options.RequestHeadersDataClasses.Add("Authorization", DataClassification.Unknown);
    options.RequestHeadersDataClasses.Add("X-API-Key", DataClassification.Unknown);
});

Untuk informasi selengkapnya tentang mengonfigurasi redactor, lihat Redaksi data di .NET.

Redaksi parameter jalur dan rute

Secara default, pengelogan klien HTTP meredaksi permintaan dan jalur respons untuk melindungi privasi. Saat mencatat jalur permintaan HTTP, Anda dapat mengontrol bagaimana parameter rute diredaksi menggunakan RequestPathParameterRedactionMode opsi :

Opsi RequestPathLoggingMode mengontrol format jalur yang dicatat:

Contoh: Menonaktifkan penyembunyian jalur

Untuk mencatat jalur penuh dan tidak teredaksi (misalnya, di lingkungan pengembangan), atur RequestPathParameterRedactionMode ke None:

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Disable redaction of request/response paths
    options.RequestPathParameterRedactionMode = HttpRouteParameterRedactionMode.None;
});

Pertimbangan performa

Pengelogan klien HTTP yang ditingkatkan dirancang dengan mempertimbangkan performa, tetapi ada trade-off yang perlu dipertimbangkan:

• Pencatatan isi: Mengaktifkan LogBody menambahkan overhead untuk buffering dan membaca tubuh permintaan/respons. Gunakan BodySizeLimit dan BodyReadTimeout untuk mengontrol penggunaan sumber daya.
• Pencatatan header: Hanya catat header yang Anda butuhkan. Kosongkan RequestHeadersDataClasses dan ResponseHeadersDataClasses untuk menghindari overhead pemrosesan header.
• Enrichers: Setiap enricher terdaftar akan dipanggil setiap kali ada permintaan. Jaga agar logika pengaya tetap ringan.
• Penghapusan: Klasifikasi data dan penghapusan menambahkan overhead minimal, tetapi skalanya meningkat sesuai dengan jumlah item yang diklasifikasikan.

Lihat juga

• Pabrik klien HTTP di .NET
• Pengaya log klien HTTP
• Memantau dan menganalisis performa klien HTTP
• Redaksi data di .NET
• Klasifikasi data di .NET
• Pengelogan dalam .NET