Registrazione cliente HTTP in .NET

Quando si creano applicazioni che effettuano richieste HTTP, la registrazione strutturata consente di monitorare, risolvere i problemi e analizzare il traffico in uscita. L'estensione AddExtendedHttpClientLogging fornisce la registrazione avanzata per tutti i client HTTP creati con IHttpClientFactory, con il supporto predefinito per:

• Registrazione configurabile : controllare cosa viene registrato (intestazioni, corpo, parametri di query, parametri di route)
• Redazione dei dati - Applicare politiche di classificazione e redazione dei dati per la privacy e la conformità
• Arricchimento dei log - Aggiungere un contesto personalizzato ai log delle richieste HTTP
• Overhead minimo - Funzionalità opzionali con impostazioni predefinite ottimizzate per le prestazioni

Abilita la registrazione avanzata per il client HTTP chiamando il metodo di estensione AddExtendedHttpClientLogging. Questo sostituisce il logger client HTTP predefinito con un logger esteso che supporta funzionalità di configurazione e conformità dei dati con granularità fine.

Aggiungere il pacchetto

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

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

Per altre informazioni, vedere dotnet package add or Manage package dependencies in .NET applications (Aggiungere o gestire le dipendenze dei pacchetti nelle applicazioni .NET).

Abilitare la registrazione client HTTP

Per aggiungere la registrazione avanzata del client HTTP all'applicazione, chiamare il metodo di estensione AddExtendedHttpClientLogging al momento della configurazione dei servizi:

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

Questa registrazione aggiunge un logger avanzato a tutti i client HTTP creati tramite IHttpClientFactory, sostituendo il logger predefinito con uno che supporta la configurazione avanzata.

Applicare il logging a un client HTTP specifico

È anche possibile applicare il logging avanzato a client HTTP specifici denominati o tipizzati utilizzando i metodi di estensione IHttpClientBuilder.

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

Quando si utilizzano gli IHttpClientBuilder overload, la registrazione viene applicata solo a quel client specifico, non a livello globale.

Visualizzazione dei dati di log arricchiti

La registrazione avanzata del client HTTP aggiunge informazioni ai log usando l'arricchimento, il che significa che i dati vengono aggiunti come tag ai log strutturati anziché al messaggio della console. Per visualizzare le informazioni arricchite, usare un provider di registrazione che supporta i log strutturati.

Per i test rapidi, usare AddJsonConsole per stampare i log strutturati nella console:

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

Per gli scenari di produzione, è consigliabile usare provider di registrazione strutturati come Application Insights, Seq o Elasticsearch in grado di eseguire query e visualizzare i dati dei tag arricchiti.

Configurare le opzioni di registrazione

Si può configurare la registrazione del client HTTP tramite la classe usando il modello di opzioni standard . È possibile configurare le opzioni nel codice o associarle dalla configurazione , ad esempio appsettings.json.

Configurare con un delegato

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

Configurare tramite il file 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"));

Opzioni di configurazione

La LoggingOptions classe fornisce le opzioni di configurazione seguenti:

Opzioni di registrazione di base

Registrazione dei parametri di intestazione e query

Registrazione dei parametri di percorso e rotta

Aggiungere gli arricchimenti dei log

Gli arricchimenti dei log client HTTP consentono di aggiungere informazioni contestuali personalizzate ai log client HTTP in base alla richiesta, alla risposta e alle eccezioni. A differenza degli enricher di log per uso generico, gli enricher client HTTP sono specificamente destinati alle richieste HTTP in uscita e hanno accesso a contesti specifici per HTTP.

Ecco un rapido esempio:

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

Per informazioni dettagliate sulla creazione e l'uso di arricchimenti dei log client HTTP, incluse le procedure consigliate e gli scenari avanzati, vedere Arricchimento dei log client HTTP.

Classificazione e redazione dei dati

La registrazione client HTTP si integra con le funzionalità di redaction e classificazione dei dati per proteggere le informazioni riservate. Quando si specifica un DataClassification per le intestazioni, i parametri di query o i parametri di route, il sistema di redaction applica una redaction appropriata in base ai censuratori configurati.

Esempio: Oscuramento di intestazioni sensibili

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

Per ulteriori informazioni sulla configurazione dei redattori, vedere La Redazione dei Dati in .NET.

Redazione del parametro percorso e rotta

Per impostazione predefinita, la registrazione del client HTTP oscura i percorsi delle richieste e delle risposte per proteggere la privacy. Quando si registrano i percorsi delle richieste HTTP, è possibile controllare il modo in cui i parametri di route vengono elaborati usando l'opzione RequestPathParameterRedactionMode :

L'opzione RequestPathLoggingMode controlla il formato del percorso registrato:

Esempio: Disabilitare l'oscuramento del percorso

Per registrare percorsi completi e non mascherati (ad esempio, negli ambienti di sviluppo), impostare RequestPathParameterRedactionMode su None:

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

Considerazioni sulle prestazioni

La registrazione avanzata dei client HTTP è progettata tenendo presente le prestazioni, ma esistono compromessi da considerare:

• Registrazione del corpo: l'abilitazione di questa funzione comporta un overhead per il buffering e la lettura dei corpi delle richieste/risposte. Usare BodySizeLimit e BodyReadTimeout per controllare l'utilizzo delle risorse.
• Registrazione degli header: Registra solo gli header di cui hai bisogno. Vuoti RequestHeadersDataClasses e ResponseHeadersDataClasses evitano il sovraccarico di elaborazione delle intestazioni.
• Arricchitori: ogni arricchitore registrato viene chiamato per ciascuna richiesta. Mantenere leggera la logica di arricchimento.
• Redazione: la classificazione e la redazione dei dati aggiungono un sovraccarico minimo, ma scalano con il numero di elementi classificati.

Vedere anche

• Factory di client HTTP in .NET
• Arricchimento del log del client HTTP
• Monitorare e analizzare le prestazioni del client HTTP
• Redaction dei dati in .NET
• Classificazione dei dati in .NET
• Registrazione in .NET