Protokolování klienta HTTP v .NET

Při vytváření aplikací, které vytvářejí požadavky HTTP, vám strukturované protokolování pomůže monitorovat, řešit potíže a analyzovat odchozí provoz. Rozšíření AddExtendedHttpClientLogging poskytuje rozšířené protokolování pro všechny klienty HTTP vytvořené pomocí IHttpClientFactory, s integrovanou podporou pro:

• Konfigurovatelné protokolování – řízení toho, co se protokoluje (hlavičky, tělo, parametry dotazu, parametry trasy)
• Redakce dat – Použití zásad klasifikace a redigování dat kvůli ochraně soukromí a dodržování právních předpisů
• Obohacení záznamů – Přidávání vlastního kontextu do záznamů HTTP požadavků
• Minimální režie – Funkce přihlášení s výchozími nastaveními orientovanými na výkon

Povolte rozšířené protokolování HTTP klienta voláním metody rozšíření AddExtendedHttpClientLogging. Tím se nahradí výchozí protokolovací nástroj klienta HTTP rozšířeným protokolovacím nástrojem, který podporuje jemně odstupňovanou konfiguraci a funkce dodržování předpisů dat.

Přidání balíčku

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

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

Další informace naleznete v tématu dotnet package add nebo Správa závislostí balíčků v aplikacích .NET.

Zapnutí protokolování HTTP klienta

Pokud chcete do aplikace přidat rozšířené protokolování klienta HTTP, zavolejte rozšiřující metodu AddExtendedHttpClientLogging při konfiguraci služeb:

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

Tato registrace přidá vylepšený protokolovací nástroj pro všechny klienty HTTP vytvořené prostřednictvím IHttpClientFactory, který nahradí výchozí protokolovací nástroj a podporuje pokročilou konfiguraci.

Použít protokolování pro konkrétní klienty HTTP

Rozšířené protokolování můžete použít také pro konkrétní pojmenované nebo typované klienty HTTP pomocí IHttpClientBuilder rozšiřujících metod:

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

Při používání přetížení IHttpClientBuilder se protokolování aplikuje pouze na tohoto konkrétního klienta, nikoli globálně.

Zobrazení obohacených dat protokolu

Vylepšené protokolování klienta HTTP přidává informace do protokolů pomocí obohacení, což znamená, že data se přidávají jako značky do strukturovaných protokolů, nikoli do zprávy konzoly. Pokud chcete zobrazit rozšířené informace, použijte zprostředkovatele protokolování, který podporuje strukturované protokoly.

K rychlému testování použijte AddJsonConsole k tisku strukturovaných protokolů do konzoly:

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

V produkčních scénářích zvažte použití poskytovatelů strukturovaného protokolování, jako je Application Insights, Seq nebo Elasticsearch, které můžou dotazovat a vizualizovat rozšířená data značek.

Konfigurace možností protokolování

Protokolování klienta HTTP nakonfigurujete prostřednictvím LoggingOptions třídy pomocí standardního vzoru možností. Můžete nakonfigurovat možnosti v kódu nebo je svázat z konfigurace (například appsettings.json).

Konfigurace s delegátem

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

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

Možnosti konfigurace

Třída LoggingOptions poskytuje následující možnosti konfigurace:

Základní možnosti logování

Protokolování hlaviček a parametrů dotazu

Protokolování parametrů cesty a směrování

Přidání obohacovačů protokolů

Rozšíření protokolů klienta HTTP umožňují přidat vlastní kontextové informace do protokolů klienta HTTP na základě požadavku, odpovědi a jakýchkoli výjimek. Na rozdíl od rozšíření protokolů pro obecné účely cílí klientská rozšíření HTTP konkrétně na odchozí požadavky HTTP a mají přístup k kontextu specifickému pro HTTP.

Tady je rychlý příklad:

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

Podrobné informace o vytváření a používání rozšiřujících protokolů klienta HTTP, včetně osvědčených postupů a pokročilých scénářů, najdete v tématu o rozšiřování protokolů klienta HTTP.

Klasifikace a redakce dat

Protokolování klienta HTTP se integruje s redakcí dat a funkcemi klasifikace dat za účelem ochrany citlivých informací. Když zadáte DataClassification pro hlavičky, parametry dotazu nebo parametry trasy, systém redakce použije odpovídající redakce na základě vašich nakonfigurovaných redaktorů.

Příklad: Redakce citlivých záhlaví

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

Další informace o konfiguraci redaktorů naleznete v tématu Redaction v .NET.

Redaction parametru cesty a trasy

Ve výchozím nastavení klient protokolu HTTP zakrývá cesty požadavků a odpovědí k ochraně soukromí. Při protokolování cest požadavků HTTP můžete řídit, jak se parametry trasy redakčně zpracovávají, pomocí RequestPathParameterRedactionMode této možnosti:

Možnost RequestPathLoggingMode řídí formát protokolované cesty:

Příklad: Zakázání redakce cesty

Pokud chcete protokolovat úplné, nereactované cesty (například ve vývojových prostředích), nastavte RequestPathParameterRedactionMode na None:

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

Důležité informace o výkonu

Vylepšené protokolování klienta HTTP je navržené s ohledem na výkon, ale existují kompromisy, které je potřeba zvážit:

• Protokolování textu: Povolení LogBody přidává režii pro ukládání do vyrovnávací paměti a čtení těla požadavků a odpovědí. Použijte BodySizeLimit a BodyReadTimeout k řízení využití prostředků.
• Protokolování hlaviček: Potřebujete jenom hlavičky protokolu. Prázdné RequestHeadersDataClasses a ResponseHeadersDataClasses pomáhají vyhnout se režijním nákladům na zpracování hlaviček.
• Rozšiřování: Každý zaregistrovaný rozšiřující kód se volá pro každý požadavek. Udržujte logiku rozšiřování odlehčenou.
• Redakce: Klasifikace dat a redakce přidávají minimální režii, ale jejich škálování závisí na počtu klasifikovaných položek.

Viz také

• Klientská továrna HTTP v .NET
• Obohacovač logů klienta HTTP
• Monitorování a analýza výkonu klienta HTTP
• Redakování dat v .NET
• Klasifikace dat v .NET
• Logování v .NET