Compartir a través de

Telemetría de latencia de cliente HTTP en .NET

Al compilar aplicaciones que se comunican a través de HTTP, es importante observar las características de rendimiento de las solicitudes. La AddHttpClientLatencyTelemetry extensión habilita la recopilación de información detallada de tiempo para las llamadas HTTP salientes sin cambios en el código de llamada. Se conecta a la canalización existente HttpClientFactory para capturar tiempos de fase en el ciclo de vida de la solicitud, registrar detalles del protocolo HTTP, medir el impacto en la recolección de elementos no utilizados donde el tiempo de ejecución expone esos datos y emitir una forma de telemetría uniforme adecuada para el análisis y el ajuste del rendimiento. Habilite esta telemetría llamando al método de extensión AddHttpClientLatencyTelemetry(). El controlador integrado crea una ILatencyContext por cada solicitud de salida y completa las métricas en el momento en que se completa el pipeline interno. Consúmalos después de await base.SendAsync(...) en un controlador de delegación posterior (añadido después de la telemetría) y exporte al backend de métricas. Ejemplo:

Registro del método de extensión

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Http.Diagnostics;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// An example of some accessor that is able to read latency context
builder.Services.AddSingleton<ILatencyContextAccessor, LatencyContextAccessor>();

// Register HTTP client latency telemetry first so its delegating handler runs earlier.
builder.Services.AddHttpClientLatencyTelemetry();

// Register export handler (runs after telemetry; sees finalized ILatencyContext).
builder.Services.AddTransient<HttpLatencyExportHandler>();

// Register an HttpClient that will emit and export latency measures.
builder.Services
    .AddHttpClient("observed")
    .AddHttpMessageHandler<HttpLatencyExportHandler>();

var host = builder.Build();
await host.RunAsync();

Acceda al contexto:

public sealed class HttpLatencyExportHandler : DelegatingHandler
{
    // ILatencyContextAccessor is just an example of some accessor that is able to read latency context
    private readonly ILatencyContextAccessor _latency;

    public HttpLatencyExportHandler(ILatencyContextAccessor latency) => _latency = latency;

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
    {
        var rsp = await base.SendAsync(request, ct).ConfigureAwait(false);

        var ctx = _latency.Current;
        if (ctx != null)
        {
            var data = ctx.LatencyData;
            // Record/export gc and conn with version as a dimension here.
        }
        return rsp;
    }
}

Agregar el paquete

dotnet add package Microsoft.Extensions.Http.Diagnostics --version 9.10.0

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

Registro de telemetría de latencia de cliente HTTP

Para agregar telemetría de latencia de cliente HTTP a tu aplicación, llama al método de extensión AddHttpClientLatencyTelemetry al configurar tus servicios:

var builder = WebApplication.CreateBuilder(args);

// Add HTTP client factory
builder.Services.AddHttpClient();

// Add HTTP client latency telemetry
builder.Services.AddHttpClientLatencyTelemetry();

Este registro agrega un DelegatingHandler a todos los clientes HTTP creados a través de IHttpClientFactory, recopilando información detallada de latencia para cada solicitud.

Configuración de opciones de telemetría

Usted configura la recopilación de telemetría a través del patrón de opciones estándar () . Puede proporcionar valores con un delegado o mediante la configuración de enlace (por ejemplo, appsettings.json). La instancia de opciones se resuelve una vez por canalización de controlador, por lo que los cambios se aplican a los nuevos clientes o controladores.

// Configure with delegate
builder.Services.AddHttpClientLatencyTelemetry(options =>
{
    options.EnableDetailedLatencyBreakdown = true;
});

// Or configure from configuration
builder.Services.AddHttpClientLatencyTelemetry(
builder.Configuration.GetSection("HttpClientTelemetry"));

Opciones de configuración

La HttpClientLatencyTelemetryOptions clase ofrece la siguiente configuración:

Opción Tipo Predeterminado Description Cuándo deshabilitar
HabilitarDesgloseDetalladoDeLatencia Boolean true Habilita el tiempo de fase específico para cada solicitud HttpClient (por ejemplo, establecimiento de conexión, encabezados enviados, primer byte y finalización) para generar un desglose de la latencia total. Agrega un pequeño costo adicional de medición de CPU/tiempo, sin sobrecarga de red. false Establézcalo solo en escenarios de muy alto rendimiento en los que se requiera una sobrecarga mínima y donde la duración total por sí sola sea suficiente.

Datos de telemetría recopilados

Cuando la telemetría de latencia de cliente HTTP está habilitada, captura las marcas de tiempo de fase, las medidas seleccionadas (donde se admiten) y los atributos de protocolo usados para el análisis de rendimiento.

Puntos de control de tiempo

Las marcas de tiempo se registran para las fases clave del ciclo de vida de la solicitud HTTP:

Phase Evento de inicio Evento final Notas
Resolución DNS Http.NameResolutionStart Http.NameResolutionEnd Búsqueda de nombres de host (puede almacenarse en caché y omitirse).
Conexión de socket Http.SocketConnectStart Http.SocketConnectEnd CP (y protocolo de enlace TLS si se combinan mediante controlador).
Establecimiento de la conexión Http.ConexiónEstablecida Marca la conexión utilizable después del intercambio inicial.
Encabezados de solicitud Http.RequestHeadersStart Http.RequestHeadersEnd Escribir encabezados de solicitud en el cable o el búfer.
Solicitar contenido Http.RequestContentStart Http.RequestContentEnd Cuerpo de la solicitud de transmisión o almacenamiento en búfer.
Encabezados de respuesta Http.ResponseHeadersStart Http.ResponseHeadersEnd Primer byte hasta la finalización del análisis de encabezados.
Contenido de la respuesta Http.ResponseContentStart Http.ResponseContentEnd Leer el cuerpo completo de la respuesta (hasta terminar o descartar).

Medidas (dependientes de la plataforma)

Mide los factores de latencia que los puntos de control de fase sin procesar no pueden cuantificar (superposición de pausa de GC, rotación de conexiones, otros recuentos acumulados o duraciones). Se recopilan en un contexto de latencia en memoria creado al llamar a AddHttpClientLatencyTelemetry(). No se emite nada automáticamente: el contexto simplemente acumula puntos de control, medidas y etiquetas hasta que se completa la solicitud. Si también habilita el enriquecimiento de registro de cliente HTTP con AddExtendedHttpClientLogging(), el contexto completado se aplana en un único campo de registro estructurado denominado LatencyInfo (marcador de versión, nombre del servidor si está disponible, etiqueta, punto de control y secuencias de nombre y valor de medida).

Ese campo de registro es el único artefacto de salida integrado; no se generan métricas ni seguimientos a menos que agregue su propio exportador. Para exponerlos como métricas, lea el contexto después de que la canalización de solicitudes regrese y registre (por ejemplo) la superposición de la pausa de GC en un histograma y las iniciaciones de conexión en un contador, opcionalmente segmentado por versión de protocolo.

Nombre Description
Http.GCPauseTime Duración total de pausa de GC superpuesta a la solicitud.
Http.ConnectionInitiated Se genera cuando se crea una nueva conexión subyacente (no reutilización agrupada).

Etiquetas

Usa etiquetas para adjuntar dimensiones categóricas estables a cada solicitud para poder segmentar, filtrar y agregar métricas y registros sin reprocesar datos. Son etiquetas de clasificación de baja cardinalidad (no tiempos) capturadas en el contexto de latencia y, si el enriquecimiento de registros del cliente HTTP está habilitado, serializadas en un único campo de registro LatencyInfo. Habilite el enriquecimiento en el inicio de la aplicación agregando la extensión de registro (para todos los clientes o por cliente) junto con la telemetría de latencia, por ejemplo:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHttpClientLatencyTelemetry(); // enables latency context + measures/tags
builder.Services.AddExtendedHttpClientLogging();
var app = builder.Build();

Después de esto, las solicitudes salientes registradas a través de la canalización de registro estructurado incluirán la LatencyInfo propiedad que contiene las etiquetas, los puntos de control y las medidas aplanados. No se emiten métricas ni seguimientos automáticamente para las etiquetas; expórtelos usted mismo (por ejemplo, convierta los valores de etiqueta en dimensiones o Activity etiquetas de métricas) si los necesita fuera de los registros.

Etiqueta Description
Http.Version Versión del protocolo HTTP negociada o usada (por ejemplo, 1.1, 2, 3).

Ejemplo de uso

Estos componentes habilitan el seguimiento y la generación de informes de la latencia del procesamiento de solicitudes de cliente HTTP.

Puede registrar los servicios mediante los métodos siguientes:

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services);

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services,
    IConfigurationSection section);

public static IServiceCollection AddHttpClientLatencyTelemetry(
    this IServiceCollection services,
    Action<HttpClientLatencyTelemetryOptions> configure);

Por ejemplo:

var builder = Host.CreateApplicationBuilder(args);

// Register IHttpClientFactory:
builder.Services.AddHttpClient();

// Register redaction services:
builder.Services.AddRedaction();

// Register latency context services:
builder.Services.AddLatencyContext();

// Register HttpClient logging enrichment & redaction services:
builder.Services.AddExtendedHttpClientLogging();

// Register HttpClient latency telemetry services:
builder.Services.AddHttpClientLatencyTelemetry();

var host = builder.Build();

Consideraciones sobre la plataforma

La telemetría de latencia de cliente HTTP se ejecuta en todos los destinos admitidos (.NET 9, .NET 8, .NET Standard 2.0 y .NET Framework 4.6.2). Los puntos de control de sincronización esenciales siempre se recopilan. La métrica de pausa de GC (Http.GCPauseTime) solo se emite cuando se ejecuta en .NET 8 o .NET 9. La implementación detecta las funcionalidades de la plataforma en tiempo de ejecución y habilita lo que se admite sin configuración adicional.

  • Last updated on