Registro do cliente HTTP no .NET

Quando você cria aplicativos que fazem solicitações HTTP, o log estruturado ajuda você a monitorar, solucionar problemas e analisar o tráfego de saída. A extensão AddExtendedHttpClientLogging fornece registro em log aprimorado para todos os clientes HTTP criados com IHttpClientFactory, com suporte interno para:

• Log configurável – Controle o que é registrado (cabeçalhos, corpo, parâmetros de consulta, parâmetros de rota)
• Redação de dados – Aplicar políticas de classificação e redação de dados para privacidade e conformidade
• Enriquecimento de log – Adicionar contexto personalizado aos logs de solicitação HTTP
• Sobrecarga mínima – recursos de aceitação com padrões conscientes do desempenho

Habilite o registro em log avançado do cliente HTTP chamando o método de extensão AddExtendedHttpClientLogging. Isso substitui o logger padrão do cliente HTTP com um logger estendido que dá suporte a recursos detalhados de configuração e conformidade de dados.

Adicionar o pacote

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

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

Para obter mais informações, consulte dotnet package add ou Gerenciar dependências de pacotes em aplicativos .NET.

Habilitar o registro em log do cliente HTTP

Para adicionar o registro avançado de cliente HTTP ao seu aplicativo, chame o método de extensão AddExtendedHttpClientLogging ao configurar seus serviços:

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

Este registro adiciona um registrador aprimorado a todos os clientes HTTP criados através de IHttpClientFactory, substituindo o registrador padrão por um que dá suporte à configuração avançada.

Aplicar o registro em log a clientes HTTP específicos

Você também pode aplicar logging aprimorado a clientes HTTP específicos, nomeados ou tipados, usando os métodos de extensão 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();    

Ao usar as sobrecargas IHttpClientBuilder, o logging é aplicado somente a esse cliente específico, não globalmente.

Exibindo dados de log enriquecidos

O registro em log avançado do cliente HTTP adiciona informações aos logs usando enriquecimento, o que significa que os dados são adicionados como marcas a logs estruturados e não à mensagem do console. Para exibir as informações enriquecidas, use um provedor de log que dê suporte a logs estruturados.

Para testes rápidos, use AddJsonConsole para imprimir logs estruturados no terminal.

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

Para cenários de produção, considere o uso de provedores de log estruturados, como Application Insights, Seq ou Elasticsearch, que podem consultar e visualizar os dados de marca enriquecidos.

Configurar opções de registo

Você configura o registro em log do cliente HTTP por meio da LoggingOptions classe usando o padrão de opções padrão. Você pode configurar opções no código ou associá-las da configuração (por exemplo, appsettings.json).

Configurar com um delegado

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

Configurar a partir de 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"));

Opções de configuração

A LoggingOptions classe fornece as seguintes opções de configuração:

Opções básicas de registro em log

Registro de cabeçalhos e parâmetros de consulta

Registro em log de parâmetros de caminho e rota

Adicionar enriquecedores de registros

Os enriquecidores de log do cliente HTTP permitem adicionar informações contextuais personalizadas aos logs de cliente HTTP com base na solicitação, resposta e quaisquer exceções. Ao contrário dos enriquecedores de log de uso geral, os enriquecedores do cliente HTTP são especificamente voltados para solicitações HTTP de saída e têm acesso ao contexto específico de HTTP.

Aqui está um exemplo rápido:

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

Para obter informações detalhadas sobre como criar e usar enriquecidores de log de cliente HTTP, incluindo práticas recomendadas e cenários avançados, consulte o enriquecidor de log do cliente HTTP.

Classificação e redação de dados

O log do cliente HTTP integra-se aos recursos de redação de dados e classificação de dados para proteger informações confidenciais. Quando você especifica um DataClassification para cabeçalhos, parâmetros de consulta ou parâmetros de rota, o sistema de redação aplica a redação apropriada com base em seus refatoradores configurados.

Exemplo: Redigir cabeçalhos confidenciais

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

Para obter mais informações sobre como configurar redatores, consulte Redação de dados no .NET.

Redação de parâmetros de caminho e rota

Por padrão, o registro de logs do cliente HTTP oculta os caminhos de solicitação e resposta para proteger a privacidade. Ao registrar caminhos de solicitação HTTP, você pode controlar como os parâmetros de rota são redigidos usando a opção RequestPathParameterRedactionMode :

A RequestPathLoggingMode opção controla o formato do caminho registrado:

Exemplo: Desabilitar a redação do caminho

Para registrar caminhos completos e não redigidos (por exemplo, em ambientes de desenvolvimento), defina RequestPathParameterRedactionMode como None:

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

Considerações sobre desempenho

O registro em log de cliente HTTP aprimorado foi projetado focando no desempenho, mas há balanceamentos a serem considerados:

• Registro do corpo: A ativação de LogBody adiciona sobrecarga para o buffer e a leitura do corpo da solicitação/resposta. Use BodySizeLimit e BodyReadTimeout para controlar o uso de recursos.
• Registro de cabeçalho: Registre somente os cabeçalhos necessários. O processo de esvaziar RequestHeadersDataClasses e ResponseHeadersDataClasses evita a sobrecarga de processamento de cabeçalho.
• Enriquecedores: cada enriquecedor registrado é chamado em cada solicitação. Mantenha a lógica de enriquecimento leve.
• Redação: a classificação e a redação de dados adicionam sobrecarga mínima, mas dimensionam com o número de itens classificados.

Consulte também

• Fábrica de clientes HTTP no .NET
• Enriquecidor de log do cliente HTTP
• Monitorar e analisar o desempenho do cliente HTTP
• Redação de dados no .NET
• Classificação de dados no .NET
• Registro em log no .NET