Compartir a través de

Registro de cliente HTTP en .NET

Al compilar aplicaciones que realizan solicitudes HTTP, el registro estructurado le ayuda a supervisar, solucionar problemas y analizar el tráfico saliente. La AddExtendedHttpClientLogging extensión proporciona un registro mejorado para todos los clientes HTTP creados con IHttpClientFactory, con compatibilidad integrada para:

  • Registro configurable : control de lo que se registra (encabezados, cuerpo, parámetros de consulta, parámetros de ruta)
  • Redacción de datos: aplicación de políticas de clasificación y redacción de datos para la privacidad y el cumplimiento
  • Enriquecimiento de registros : adición de contexto personalizado a los registros de solicitudes HTTP
  • Sobrecarga mínima - funciones opcionales con valores predeterminados optimizados para el rendimiento

Habilite el registro mejorado del cliente HTTP llamando al método de extensión AddExtendedHttpClientLogging. Esto reemplaza el registrador de cliente HTTP predeterminado por un registrador extendido que admite características específicas de configuración y cumplimiento de datos.

Agregar el paquete

dotnet add package Microsoft.Extensions.Http.Diagnostics

O bien, si usa el SDK de .NET 10+:

dotnet package add Microsoft.Extensions.Http.Diagnostics

Para obtener más información, consulte Dotnet Package add or Manage package dependencies in .NET applications (Agregar o administrar dependencias de paquetes en aplicaciones .NET).

Habilitación del registro de cliente HTTP

Para añadir un registro avanzado del cliente HTTP a tu aplicación, invoca el método de extensión AddExtendedHttpClientLogging al configurar tus servicios.

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 agrega un registrador mejorado a todos los clientes HTTP creados a través IHttpClientFactoryde , reemplazando el registrador predeterminado por uno que admita la configuración avanzada.

Importante

AddExtendedHttpClientLogging() quita todos los demás registradores, incluido el predeterminado registrado por medio de AddDefaultLogger(). Esto garantiza un comportamiento de registro coherente en todos los clientes HTTP.

Importante

Debe registrar los servicios de redacción llamando AddRedaction del paquete Microsoft.Extensions.Compliance.Redaction. La característica de registro de cliente HTTP redacta información confidencial de forma predeterminada (como parámetros de ruta) y requiere un proveedor de redactores en el contenedor de inserción de dependencias.

Aplicación del registro a clientes HTTP específicos

También puede aplicar el registro mejorado a clientes HTTP específicos o tipados mediante los métodos de extensión 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();

Al usar las sobrecargas de IHttpClientBuilder, el registro de eventos solo se aplica a ese cliente específico, no de manera global.

Visualización de datos de registro enriquecidos

El registro mejorado de cliente HTTP agrega información a los registros mediante el enriquecimiento, lo que significa que los datos se agregan como etiquetas a los registros estructurados en lugar de al mensaje de la consola. Para ver la información enriquecida, use un proveedor de registro que admita registros estructurados.

Para realizar pruebas rápidas, use AddJsonConsole para imprimir registros estructurados en la consola:

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

En escenarios de producción, considere la posibilidad de usar proveedores de registro estructurados como Application Insights, Seq o Elasticsearch que pueden consultar y visualizar los datos de etiquetas enriquecidos.

Configuración de las opciones de registro

Configure el registro de cliente HTTP mediante la clase LoggingOptions usando el patrón de opciones estándar. Puede configurar opciones en el código o enlazarlas desde la configuración (por ejemplo, appsettings.json).

Configura con 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 desde 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"));

Opciones de configuración

La LoggingOptions clase proporciona las siguientes opciones de configuración:

Opciones básicas de registro

Opción Tipo Predeterminado Description
LogRequestStart bool false Cuando true, registra la solicitud antes de que se inicie el procesamiento. Cuando false, registra una única entrada con datos de solicitud y respuesta.
LogBody bool false Habilita el registro de cuerpos de solicitud y respuesta HTTP. Advertencia: evite habilitar en producción, ya que podría filtrar información confidencial.
BodySizeLimit int 32.768 (≈32 KB) Número máximo de bytes que se van a leer desde el cuerpo de la solicitud o la respuesta. Mantenga por debajo de 85 000 bytes para evitar la asignación de montón de objetos grandes .
BodyReadTimeout TimeSpan 1 segundo Tiempo máximo de espera al leer el cuerpo de la solicitud o la respuesta. Debe estar entre 1 milisegundos y 1 minuto.
RequestBodyContentTypes ISet<string> Vacío Tipos de contenido de solicitud HTTP considerados texto y aptos para la serialización.
ResponseBodyContentTypes ISet<string> Vacío Tipos de contenido de respuesta HTTP considerados texto y aptos para la serialización.

Registro de parámetros de encabezado y consulta

Opción Tipo Predeterminado Description
RequestHeadersDataClasses IDictionary<string, DataClassification> Vacío Encabezados de solicitud HTTP para registrar con sus clasificaciones de datos para el redactado. Si está vacío, no se registran encabezados de solicitud.
ResponseHeadersDataClasses IDictionary<string, DataClassification> Vacío Encabezados de respuesta HTTP para registrar con sus clasificaciones de datos para la redacción. Si está vacío, no se registran encabezados de respuesta.
RequestQueryParametersDataClasses IDictionary<string, DataClassification> Vacío Parámetros de consulta de solicitud HTTP para ser registrados con sus clasificaciones de datos. Si está vacío, no se registran parámetros de consulta. Característica experimental.
LogContentHeaders bool false Habilite el registro de encabezados de contenido HTTP (por ejemplo, Content-Type). Habilitar solo si los encabezados de contenido están en RequestHeadersDataClasses o ResponseHeadersDataClasses. Característica experimental.

Registro de parámetros de trayectorias y rutas

Opción Tipo Predeterminado Description
RequestPathLoggingMode OutgoingPathLoggingMode Formatted Cómo loguear la ruta de solicitud HTTP saliente. Solo se aplica cuando RequestPathParameterRedactionMode no es None.
RequestPathParameterRedactionMode HttpRouteParameterRedactionMode Strict Cómo redactar los parámetros de ruta en las solicitudes HTTP salientes.
RouteParameterDataClasses IDictionary<string, DataClassification> Vacío Rutea los parámetros para editar con sus clasificaciones de datos correspondientes.

Adición de enriquecedores de registro

Los enriquecedores de registros de cliente HTTP permiten agregar información contextual personalizada a los registros de cliente HTTP en función de la solicitud, la respuesta y las excepciones. A diferencia de los enriquecedores de registros de uso general, los enriquecedores de cliente HTTP tienen como destino específicamente las solicitudes HTTP salientes y tienen acceso al contexto específico de HTTP.

Este es un ejemplo 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 obtener información detallada sobre cómo crear y usar enriquecimientos de registros de cliente HTTP, incluidos los procedimientos recomendados y los escenarios avanzados, consulte Enriquecimiento de registros de cliente HTTP.

Clasificación y redacción de datos

El registro de cliente HTTP se integra con las características de redacción de datos y clasificación de datos para proteger la información confidencial. Al especificar un DataClassification para encabezados, parámetros de consulta o parámetros de ruta, el sistema de redacción aplica la redacción adecuada según los redactores configurados.

Ejemplo: Edición de encabezados sensibles

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 obtener más información sobre cómo configurar redactores, consulte Redacción de datos en .NET.

Redacción de parámetros de ruta y ruta

De forma predeterminada, el registro de cliente HTTP oculta las rutas de acceso de solicitud y respuesta para proteger la privacidad. Al registrar rutas de solicitud HTTP, puede controlar cómo se ocultan los parámetros de ruta mediante la opción RequestPathParameterRedactionMode.

Mode Description Example
None Sin redacción, se registra la ruta de acceso completa. /api/users/12345/orders/67890
Strict Todos los parámetros de ruta se redactan /api/users/{userId}/orders/{orderId}
Loose Solo se redactan los parámetros en RouteParameterDataClasses /api/users/12345/orders/{orderId}

La RequestPathLoggingMode opción controla el formato de la ruta de acceso registrada:

Mode Description Example
Formatted Utiliza el formato de plantilla de ruta con nombres de parámetros /api/users/{userId}/orders/{orderId}
Structured Registra la ruta de acceso y los parámetros por separado Ruta de acceso: /api/users/*/orders/*, parámetros: {userId, orderId}

Ejemplo: Deshabilitar la redacción de la ruta de acceso

Para registrar rutas completas y sin editar (por ejemplo, en entornos de desarrollo), establezca el valor en RequestPathParameterRedactionModeNone:

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

Precaución

Deshabilitar la redacción de rutas podría exponer información confidencial en los registros. Solo use HttpRouteParameterRedactionMode.None en desarrollo o cuando esté seguro de que las rutas no contienen datos confidenciales.

Consideraciones sobre el rendimiento

El registro mejorado de cliente HTTP está diseñado teniendo en cuenta el rendimiento, pero hay compensaciones que hay que considerar.

  • Registro del cuerpo: La habilitación de implica una carga adicional al almacenar en búfer y leer los cuerpos de solicitud/respuesta. Use BodySizeLimit y BodyReadTimeout para controlar el uso de recursos.
  • Registro de encabezados: Registre solo los encabezados que necesite. Vacía RequestHeadersDataClasses y ResponseHeadersDataClasses evita la sobrecarga de procesamiento de encabezados.
  • Enriquecedores: Cada enriquecedor registrado es invocado para cada solicitud. Mantenga la lógica de enriquecimiento ligera.
  • Redaction: la clasificación de datos y la redacción agregan una sobrecarga mínima, pero se escalan con el número de elementos clasificados.

Sugerencia

En entornos de producción, comience con un registro mínimo (sin cuerpo, encabezados limitados) y habilite el registro adicional solo para solucionar problemas.

Consulte también

  • Last updated on