Compartir a través de

Métricas de ASP.NET Core

Las métricas son medidas numéricas que se comunican a lo largo del tiempo. Normalmente se usan para supervisar el estado de una aplicación y generar alertas. Por ejemplo, un servicio web podría realizar un seguimiento de:

  • El número de solicitudes ha recibido por segundo.
  • Los milisegundos que tardó en responder.
  • Las respuestas enviaron un error.

Estas métricas se pueden comunicar a un sistema de supervisión a intervalos regulares. Se pueden configurar paneles para ver las métricas y las alertas creadas para notificar problemas. Si el servicio web está pensado para responder a solicitudes en un plazo de 400 ms y comienza a responder en 600 ms, el sistema de supervisión puede notificar al personal de operaciones que la respuesta de la aplicación es más lenta de lo normal.

Consulte Métricas de ASP.NET Core para obtener una lista completa de todos los instrumentos junto con sus atributos.

Usar métricas

El uso de métricas implica lo siguiente:

  • Instrumentación: el código de las bibliotecas .NET toma medidas y las asocia a un nombre de métrica. .NET y ASP.NET Core incluyen muchas métricas integradas.
  • Colección y almacenamiento: una aplicaciones .NET configura métricas con nombre para que se transmitan desde la aplicación para el almacenamiento y el análisis externos. Algunas herramientas pueden realizar la configuración fuera de la aplicación mediante archivos de configuración o una herramienta de interfaz de usuario.
  • Visualización: Una herramienta que puede mostrar las métricas en un formato legible por humanos. Por ejemplo, Grafana y Prometheus.
  • Alertas: Una herramienta que proporciona notificaciones cuando una métrica supera un umbral. Por ejemplo, si el tiempo medio de respuesta de un servicio web supera los 400 ms, se puede enviar una alerta al personal de operaciones.
  • Análisis: Una herramienta que puede analizar las métricas a lo largo del tiempo. Suele tratarse de un panel de control basado en web que puede personalizarse para mostrar las métricas más importantes de una aplicación específica.

El código instrumentado puede registrar medidas numéricas, pero las medidas deben agregarse, transmitirse y almacenarse para crear métricas útiles para la supervisión. Este proceso de agregación, transmisión y almacenamiento de los datos se denomina "colección". Este tutorial muestra varios ejemplos de recopilación y visualización de métricas:

Las medidas también se pueden asociar a pares clave-valor denominados etiquetas que permiten clasificar los datos para analizarlos. Para obtener más información, consulte Métricas con múltiples dimensiones.

Crear la aplicación de inicio

Crear una aplicación ASP.NET Core con el siguiente comando:

dotnet new web -o WebMetric
cd WebMetric
dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --prerelease
dotnet add package OpenTelemetry.Extensions.Hosting

Reemplace el contenido de Program.cs por el código siguiente:

using OpenTelemetry.Metrics;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithMetrics(builder =>
    {
        builder.AddPrometheusExporter();

        builder.AddMeter("Microsoft.AspNetCore.Hosting",
                         "Microsoft.AspNetCore.Server.Kestrel");
        builder.AddView("http.server.request.duration",
            new ExplicitBucketHistogramConfiguration
            {
                Boundaries = new double[] { 0, 0.005, 0.01, 0.025, 0.05,
                       0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 }
            });
    });
var app = builder.Build();

app.MapPrometheusScrapingEndpoint();

app.MapGet("/", () => "Hello OpenTelemetry! ticks:"
                     + DateTime.Now.Ticks.ToString()[^3..]);

app.Run();

Visualización de métricas con dotnet-counters

dotnet-counters es una herramienta de línea de comandos que puede mostrar las métricas en directo de cualquier aplicación de .NET Core a petición. No requiere ninguna configuración, lo que la hace útil para investigaciones ad hoc o para comprobar que la instrumentación de métricas funciona. Funciona tanto con API basadas en System.Diagnostics.Metrics como con EventCounters.

Si la herramienta dotnet-counters no está instalada, ejecute el siguiente comando:

dotnet tool update -g dotnet-counters

Mientras se ejecuta la aplicación de prueba, inicie dotnet-counters. El comando siguiente muestra un ejemplo de cómo dotnet-counters supervisa todas las métricas del medidor de Microsoft.AspNetCore.Hosting.

dotnet-counters monitor -n WebMetric --counters Microsoft.AspNetCore.Hosting

Esto genera una salida similar a la siguiente:

Press p to pause, r to resume, q to quit.
    Status: Running

[Microsoft.AspNetCore.Hosting]
    http-server-current-requests
        host=localhost,method=GET,port=5045,scheme=http                    0
    http-server-request-duration (s)
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0

Para obtener más información, vea dotnet-counters.

Enriquecer la métrica de solicitud de ASP.NET Core

ASP.NET Core tiene muchas métricas integradas. La métrica http.server.request.duration:

  • Registra la duración de las solicitudes HTTP en el servidor.
  • Captura la información de solicitud en etiquetas, como el código de estado de respuesta y la ruta coincidente.

La métrica http.server.request.duration admite el enriquecimiento de etiquetas con IHttpMetricsTagsFeature. El enriquecimiento se produce cuando una biblioteca o aplicación agrega sus propias etiquetas a una métrica. Esto resulta útil si una aplicación quiere agregar una categorización personalizada a paneles o alertas compiladas con métricas.

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Use(async (context, next) =>
{
    var tagsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (tagsFeature != null)
    {
        var source = context.Request.Query["utm_medium"].ToString() switch
        {
            "" => "none",
            "social" => "social",
            "email" => "email",
            "organic" => "organic",
            _ => "other"
        };
        tagsFeature.Tags.Add(new KeyValuePair<string, object?>("mkt_medium", source));
    }

    await next.Invoke();
});

app.MapGet("/", () => "Hello World!");

app.Run();

El ejemplo de procedimiento:

  • Agrega middleware para enriquecer la métrica de solicitud de ASP.NET Core.
  • Obtiene el elemento IHttpMetricsTagsFeature desde HttpContext. La característica solo está presente en el contexto si alguien escucha la métrica. Compruebe que el valor de IHttpMetricsTagsFeature no sea null antes de usarlo.
  • Agrega una etiqueta personalizada que contiene el origen de marketing de la solicitud a la métrica http.server.request.duration.
    • La etiqueta tiene el nombre mkt_medium y un valor basado en el valor de la cadena de consulta utm_medium. El valor utm_medium se resuelve en un intervalo de valores conocidos.
    • La etiqueta permite clasificar las solicitudes por categoría según el tipo de medio de marketing, lo que podría ser útil al analizar el tráfico de la aplicación web.

Nota:

Siga los procedimientos recomendados de métricas multidimensionales al aplicar el enriquecimiento con etiquetas personalizadas. Las etiquetas demasiado numerosas o con un intervalo sin límites crean muchas combinaciones de etiquetas, lo que da lugar a dimensiones elevadas. Las herramientas de recopilación tienen límites en las dimensiones admitidas para un contador y pueden filtrar los resultados para evitar un uso excesivo de memoria.

No participar en métricas HTTP en determinados puntos de conexión y solicitudes

Excluirse del registro de métricas es beneficioso para los puntos de conexión a los que llaman con frecuencia los sistemas automatizados, como las comprobaciones de estado. El registro de métricas para estas solicitudes es generalmente innecesario. La telemetría no deseada utiliza recursos para recopilar y almacenar, y puede distorsionar los resultados mostrados en un panel de telemetría.

Las peticiones HTTP a un punto de conexión pueden excluirse de las métricas añadiendo metadatos, ya sea con el atributo DisableHttpMetrics o con el método DisableHttpMetrics:

  • Añada el atributo DisableHttpMetrics al controlador de la API Web, hub SignalR o servicio gRPC.
  • Llame a DisableHttpMetrics al asignar puntos finales en el inicio de la aplicación:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();

var app = builder.Build();
app.MapHealthChecks("/healthz").DisableHttpMetrics();
app.Run();

Alternativamente, se ha añadido la propiedad IHttpMetricsTagsFeature.MetricsDisabled para:

  • Escenarios avanzados en los que una solicitud no se asigna a un punto de conexión.
  • Deshabilitar dinámicamente la recopilación de métricas para peticiones HTTP específicas.
// Middleware that conditionally opts-out HTTP requests.
app.Use(async (context, next) =>
{
    var metricsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (metricsFeature != null &&
        context.Request.Headers.ContainsKey("x-disable-metrics"))
    {
        metricsFeature.MetricsDisabled = true;
    }

    await next(context);
});

Crear métricas personalizadas

Las métricas se crean utilizando las API del espacio de nombres System.Diagnostics.Metrics. Consulte Crear métricas personalizadas para obtener información sobre cómo crear métricas personalizadas.

Creación de métricas en aplicaciones ASP.NET Core con IMeterFactory

Recomendamos crear Meter instancias en aplicaciones ASP.NET Core con IMeterFactory.

ASP.NET Core se registra IMeterFactory en inserción de dependencias (DI) por defecto. La fábrica de contadores integra métricas con DI, lo que facilita el aislamiento y la recopilación de métricas. IMeterFactory es especialmente útil para realizar pruebas. Permite ejecutar varias pruebas en paralelo y recopilar únicamente los valores de las métricas que se registran en una prueba.

Para utilizar IMeterFactory en una aplicación, cree un tipo que utilice IMeterFactory para crear las métricas personalizadas de la aplicación:

public class ContosoMetrics
{
    private readonly Counter<int> _productSoldCounter;

    public ContosoMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("Contoso.Web");
        _productSoldCounter = meter.CreateCounter<int>("contoso.product.sold");
    }

    public void ProductSold(string productName, int quantity)
    {
        _productSoldCounter.Add(quantity,
            new KeyValuePair<string, object?>("contoso.product.name", productName));
    }
}

Registre el tipo de métrica con DI en Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ContosoMetrics>();

Inserte el tipo de métrica y registre los valores donde sea necesario. Dado que el tipo de métrica está registrado en DI, puede utilizarse con controladores MVC, API mínimas o cualquier otro tipo creado por DI:

app.MapPost("/complete-sale", (SaleModel model, ContosoMetrics metrics) =>
{
    // ... business logic such as saving the sale to a database ...

    metrics.ProductSold(model.ProductName, model.QuantitySold);
});

Para supervisar el medidor "Contoso.Web", use el siguiente comando dotnet-counters.

dotnet-counters monitor -n WebMetric --counters Contoso.Web

Esto genera una salida similar a la siguiente:

Press p to pause, r to resume, q to quit.
    Status: Running

[Contoso.Web]
    contoso.product.sold (Count / 1 sec)
        contoso.product.name=Eggs            12    
        contoso.product.name=Milk            0

Visualización de métricas en Grafana con OpenTelemetry y Prometheus

Información general

OpenTelemetry:

  • Es un proyecto de código abierto independiente del proveedor administrado por Cloud Native Computing Foundation.
  • Pretende estandarizar la generación y la recopilación de telemetría para software nativo de nube.
  • Funciona con .NET mediante las API de métricas de .NET.
  • Está aprobado por Azure Monitor y muchos proveedores de APM.

Este tutorial muestra una de las integraciones que hay disponibles para las métricas de OpenTelemetry mediante los proyectos de OSS Prometheus y Grafana. El flujo de datos de métricas:

  1. Las API de métricas de ASP.NET Core registran medidas de la aplicación de ejemplo.

  2. La biblioteca de .NET de OpenTelemetry que se ejecuta en la aplicación agrega las medidas.

  3. La biblioteca exportadora de Prometheus hace que los datos agregados estén disponibles a través de un punto de conexión de métricas HTTP. "Exportador" es el término que OpenTelemetry usa para denominar a las bibliotecas que transmiten telemetría a back-ends específicos del proveedor.

  4. Un servidor de Prometheus:

    • Sondea el punto de conexión de métricas
    • Lee los datos
    • Almacena los datos en una base de datos para la persistencia a largo plazo. Prometheus hace referencia a la lectura y el almacenamiento de datos como extracción de un punto de conexión.
    • Se puede ejecutar en una máquina diferente

  5. El servidor de Grafana:

    • Consulta los datos almacenados en Prometheus y los muestra en un panel de supervisión basado en web.
    • Se puede ejecutar en una máquina diferente.

Visualizar métricas de una aplicación de ejemplo

Navegue hasta la aplicación de ejemplo. El explorador muestra Hello OpenTelemetry! ticks:<3digits> dónde 3digits son los últimos 3 dígitos del DateTime.Ticks actual.

Anexe /metrics a la dirección URL para ver el punto de conexión de métricas. El explorador muestra las métricas que se recopilan:

métricas 2

Configuración de Prometheus

Siga los primeros pasos de Prometheus para configurar un servidor de Prometheus y confirmar que funciona.

Modifique el archivo de configuración prometheus.yml para que Prometheus extraiga el punto de conexión de métricas que se expone en la aplicación de ejemplo. Agregue el siguiente texto resaltado en la sección scrape_configs:

# my global config
global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: "prometheus"

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
      - targets: ["localhost:9090"]

  - job_name: 'MyASPNETApp'
    scrape_interval: 5s # Poll every 5 seconds for a more responsive demo.
    static_configs:
      - targets: ["localhost:5045"]  ## Enter the HTTP port number of the demo app.

En el YAML resaltado anterior, sustituya 5045 por el número de puerto en el que se ejecuta la aplicación de ejemplo.

Inicio de Prometheus

  1. Vuelva a cargar la configuración o reinicie el servidor de Prometheus.
  2. Confirme que OpenTelemetryTest se encuentre en el estado UP en la página Estado>Objetivos del portal web de Prometheus.

Estado de Prometheus

Seleccione el icono Abrir explorador de métricas para ver las métricas disponibles:

Prometheus open_metric_exp

Escriba la categoría contador, como http_ en el cuadro entrada Expresión, para ver las métricas disponibles:

métricas disponibles

Como alternativa, escriba la categoría contador, como kestrel en el cuadro entrada Expresión, para ver las métricas disponibles:

Kestrel de Prometheus

Visualización de métricas en un panel de Grafana

dashboard-screenshot2

Probar métricas en aplicaciones de ASP.NET Core

Es posible probar las métricas en aplicaciones ASP.NET Core. Una manera de hacerlo es recopilar y declarar valores de métricas en Pruebas de integración de ASP.NET Core mediante MetricCollector<T>.

public class BasicTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    public BasicTests(WebApplicationFactory<Program> factory) => _factory = factory;

    [Fact]
    public async Task Get_RequestCounterIncreased()
    {
        // Arrange
        var client = _factory.CreateClient();
        var meterFactory = _factory.Services.GetRequiredService<IMeterFactory>();
        var collector = new MetricCollector<double>(meterFactory,
            "Microsoft.AspNetCore.Hosting", "http.server.request.duration");

        // Act
        var response = await client.GetAsync("/");

        // Assert
        Assert.Contains("Hello OpenTelemetry!", await response.Content.ReadAsStringAsync());

        await collector.WaitForMeasurementsAsync(minCount: 1).WaitAsync(TimeSpan.FromSeconds(5));
        Assert.Collection(collector.GetMeasurementSnapshot(),
            measurement =>
            {
                Assert.Equal("http", measurement.Tags["url.scheme"]);
                Assert.Equal("GET", measurement.Tags["http.request.method"]);
                Assert.Equal("/", measurement.Tags["http.route"]);
            });
    }
}

La prueba de procedimiento:

  • Arranca una aplicación web en memoria con WebApplicationFactory<TEntryPoint>. Program en el argumento genérico de la fábrica especifica la aplicación web.
  • Recopila valores de métricas con MetricCollector<T>
    • Requiere una referencia de paquete para Microsoft.Extensions.Diagnostics.Testing.
    • Se crea MetricCollector<T> mediante la aplicación web IMeterFactory. Esto permite que el recopilador informe solo de los valores de métricas registrados por prueba.
    • Incluye el nombre del medidor, Microsoft.AspNetCore.Hosting, y el nombre del contador, http.server.request.duration que se va a recopilar.
  • Realiza una solicitud HTTP a la aplicación web.
  • Confirma la prueba mediante los resultados del recopilador de métricas.

Contadores y medidores de ASP.NET Core

Consulte Métricas de ASP.NET Core para obtener una lista de contadores y medidores de ASP.NET Core.