Rejestrowanie klienta HTTP na platformie .NET

Podczas tworzenia aplikacji, które wysyłają żądania HTTP, rejestrowanie ustrukturyzowane ułatwia monitorowanie, rozwiązywanie problemów i analizowanie ruchu wychodzącego. Rozszerzenie AddExtendedHttpClientLogging zapewnia rozszerzone rejestrowanie dla wszystkich klientów HTTP utworzonych za pomocą IHttpClientFactory, z wbudowaną obsługą dla:

• Rejestrowanie konfigurowalne — kontrolowanie rejestrowanych elementów (nagłówki, treść, parametry zapytania, parametry trasy)
• Redaction danych — stosowanie zasad klasyfikacji i redakcji danych w celu zachowania prywatności i zgodności
• Wzbogacanie dzienników — dodawanie kontekstu niestandardowego do dzienników żądań HTTP
• Minimalne obciążenie — funkcje, które można włączyć, z ustawieniami domyślnymi zoptymalizowanymi pod kątem wydajności

Włącz rozszerzone rejestrowanie klienta HTTP przez wywołanie AddExtendedHttpClientLogging metody rozszerzenia. Spowoduje to zastąpienie domyślnego rejestratora klienta HTTP rozszerzonym rejestratorem obsługującym szczegółowe funkcje konfiguracji i zgodności danych.

Dodawanie pakietu

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

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

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

Włącz rejestrowanie klienta HTTP

Aby dodać ulepszone rejestrowanie klienta HTTP w aplikacji, wywołaj metodę rozszerzenia AddExtendedHttpClientLogging podczas konfigurowania usług.

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

Ta rejestracja dodaje rozszerzony rejestrator do wszystkich klientów HTTP utworzonych za pomocą metody IHttpClientFactory, zastępując domyślny rejestrator takim, który wspiera zaawansowaną konfigurację.

Stosowanie rejestrowania do określonych klientów HTTP

Rozszerzone rejestrowanie można również zastosować do określonych klientów HTTP nazwanych lub o określonym typie przy użyciu IHttpClientBuilder metod rozszerzenia.

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

W przypadku korzystania z IHttpClientBuilder przeciążeń rejestrowanie jest stosowane tylko do tego konkretnego klienta, a nie globalnie.

Wyświetlanie wzbogaconych danych dziennika

Ulepszone rejestrowanie klienta HTTP dodaje informacje do dzienników przy użyciu wzbogacania, co oznacza, że dane są dodawane jako tagi do dzienników strukturalnych, a nie do komunikatu konsoli. Aby wyświetlić wzbogacone informacje, użyj dostawcy rejestrowania obsługującego dzienniki ustrukturyzowane.

Aby przeprowadzić szybkie testowanie, użyj polecenia AddJsonConsole , aby wydrukować dzienniki ustrukturyzowane w konsoli:

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

W przypadku scenariuszy produkcyjnych rozważ użycie dostawców rejestrowania strukturalnego, takich jak Application Insights, Seq lub Elasticsearch, które mogą wykonywać zapytania i wizualizować wzbogacone dane tagów.

Konfigurowanie opcji rejestrowania

Konfigurujesz rejestrowanie klienta HTTP za pomocą klasy przy użyciu wzorca opcji standardowych . Opcje można skonfigurować w kodzie lub powiązać z konfiguracją (na przykład appsettings.json).

Konfiguracja z delegatem

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

Konfigurowanie z poziomu 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"));

Opcje konfiguracji

Klasa LoggingOptions udostępnia następujące opcje konfiguracji:

Opcje rejestrowania podstawowego

Rejestrowanie parametrów nagłówka i zapytania

Rejestrowanie parametrów ścieżki i trasy

Dodaj wzbogacacze logów

Wzbogacacze dzienników klienta HTTP umożliwiają dodawanie niestandardowych informacji kontekstowych do dzienników klienta HTTP na podstawie żądania, odpowiedzi i wszelkich wyjątków. W przeciwieństwie do ogólnych wzbogacaczy logów, wzbogacacze klientów HTTP są specjalnie przeznaczone dla wychodzących żądań HTTP i mają dostęp do kontekstu specyficznego dla HTTP.

Oto szybki przykład:

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

Aby uzyskać szczegółowe informacje na temat tworzenia i używania wzbogacaczy dzienników klienta HTTP, w tym dobre praktyki i zaawansowane scenariusze, zobacz Wzbogacacz dzienników klienta HTTP.

Klasyfikacja i redaction danych

Rejestrowanie klienta HTTP integruje się z funkcjami redakcji danych i klasyfikacji danych w celu ochrony poufnych informacji. Po określeniu DataClassification dla nagłówków, parametrów zapytania lub parametrów trasy, system redagowania stosuje odpowiednie redagowanie na podstawie skonfigurowanych narzędzi redagujących.

Przykład: redagowanie poufnych nagłówków

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

Aby uzyskać więcej informacji na temat konfigurowania redaktorów, zobacz Redakcja danych w .NET.

Redakcja parametru ścieżki i parametru trasy

Domyślnie rejestrowanie klienta HTTP usuwa ścieżki żądań i odpowiedzi w celu ochrony prywatności. Podczas rejestrowania ścieżek żądań HTTP można kontrolować sposób redagowania parametrów trasy przy użyciu RequestPathParameterRedactionMode opcji :

Opcja RequestPathLoggingMode steruje formatem zarejestrowanej ścieżki:

Przykład: wyłączenie redagowania ścieżki

Aby zarejestrować pełne, nieredagowane ścieżki (na przykład w środowiskach deweloperskich), ustaw wartość RequestPathParameterRedactionModeNone:

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

Zagadnienia dotyczące wydajności

Ulepszone rejestrowanie klienta HTTP zostało zaprojektowane z myślą o wydajności, ale należy wziąć pod uwagę następujące kompromisy:

• Rejestrowanie treści: włączenie LogBody dodaje nakład pracy na potrzeby buforowania i odczytywania treści żądań/odpowiedzi. Użyj funkcji BodySizeLimit i BodyReadTimeout , aby kontrolować użycie zasobów.
• Rejestrowanie nagłówków: Rejestruj tylko te nagłówki, które są potrzebne. Puste RequestHeadersDataClasses i ResponseHeadersDataClasses unikają obciążenia przetwarzania nagłówka.
• Wzbogacacze: każdy zarejestrowany wzbogacacz jest wywoływany dla każdego żądania. Zachowaj lekką logikę wzbogacania.
• Redakcja: Klasyfikacja danych i redakcja dodaje minimalne obciążenie, ale skalują się w zależności od liczby sklasyfikowanych elementów.

Zobacz także

• Fabryka klienta HTTP na platformie .NET
• Wzbogacacz dziennika klienta HTTP
• Monitorowanie i analizowanie wydajności klienta HTTP
• Redaction danych na platformie .NET
• Klasyfikacja danych na platformie .NET
• Rejestrowanie na platformie .NET