Metriche di ASP.NET Core

Le metriche sono misurazioni numeriche segnalate nel tempo. Usarli per monitorare l'integrità di un'app e generare avvisi. Ad esempio, un servizio Web potrebbe tenere traccia del numero di:

• Richiede che riceva al secondo.
• Millisecondi necessari per rispondere.
• Risposte che invia con un errore.

Segnalare queste metriche a un sistema di monitoraggio a intervalli regolari. Configurare i dashboard per visualizzare le metriche e creare avvisi per notificare agli utenti problemi. Se il servizio Web è destinato a rispondere alle richieste entro 400 ms e inizia a rispondere in 600 ms, il sistema di monitoraggio può notificare al personale operativo che la risposta dell'app è più lenta del normale.

L'elenco completo di tutti gli strumenti insieme ai relativi attributi è descritto in ASP.NET Core metriche predefinite.

Usare le metriche

L'uso delle metriche prevede quanto segue:

• Strumentazione: il codice nelle librerie .NET accetta misure e associa queste misurazioni a un nome di metrica. .NET e ASP.NET Core includono molte metriche predefinite.
• Raccolta e archiviazione: Un'app .NET configura le metriche denominate da trasmettere dall'app per l'archiviazione e l'analisi esterne. Alcuni strumenti possono eseguire la configurazione all'esterno dell'app usando file di configurazione o uno strumento dell'interfaccia utente.
• Visualizzazione: Strumento che può visualizzare le metriche in un formato leggibile. Ad esempio, il Aspire dashboard, Grafana e Prometheus.
• Avvisi: Strumento che fornisce notifiche quando una metrica supera una soglia. Ad esempio, se il tempo medio di risposta per un servizio Web supera i 400 ms, è possibile inviare un avviso al personale operativo.
• Analisi: Strumento che consente di analizzare le metriche nel tempo. Questo strumento è spesso un dashboard basato sul Web che può essere personalizzato per mostrare le metriche più importanti per un'app specifica.

Il codice instrumentato può registrare misurazioni numeriche, ma per creare metriche utili per il monitoraggio, è necessario aggregare, trasmettere e archiviare le misurazioni. Il processo di aggregazione, trasmissione e archiviazione dei dati viene chiamato raccolta. Questa esercitazione illustra diversi esempi di raccolta e visualizzazione delle metriche:

• Popolamento delle metriche in Grafana con OpenTelemetry e Prometheus.
• Visualizzare le metriche in tempo reale con dotnet-counters.

Per un'altra opzione di visualizzazione, vedere la panoramica del Aspire dashboard.

È anche possibile associare le misurazioni alle coppie chiave-valore denominate tag che consentono di classificare i dati per l'analisi. Per altre informazioni, vedere Metriche multidimensionali.

Creare l'app iniziale

Creare una nuova app ASP.NET Core con il comando seguente:

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

Sostituire il contenuto di Program.cs con il codice seguente:

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

Visualizza le metriche con dotnet-counters

dotnet-counters è uno strumento da riga di comando in grado di visualizzare le metriche in tempo reale per le app .NET su richiesta. Non richiede la configurazione, rendendola utile per le ricerche ad hoc o per verificare che la strumentazione delle metriche funzioni. Funziona sia con le API basate su System.Diagnostics.Metrics che EventCounters.

Se lo strumento dotnet-counters non è installato, eseguire il comando seguente:

dotnet tool update -g dotnet-counters

Durante l'esecuzione dell'app di test, avviare dotnet-counters. Il comando seguente mostra un esempio di come dotnet-counters monitorare tutte le metriche dal Microsoft.AspNetCore.Hosting contatore.

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

Viene visualizzato output simile al seguente:

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

Per ulteriori informazioni, consultare dotnet-counters.

Arricchire la metrica delle richieste di ASP.NET Core

ASP.NET Core include molte metriche predefinite. Metrica http.server.request.duration :

• Registra la durata delle richieste HTTP nel server.
• Acquisisce le informazioni sulle richieste nei tag, ad esempio la route corrispondente e il codice di stato della risposta.

La metrica http.server.request.duration supporta l'arricchimento dei tag tramite IHttpMetricsTagsFeature. L'arricchimento è quando una libreria o un'app aggiunge tag a una metrica. Questa funzionalità è utile se un'app vuole aggiungere una categorizzazione personalizzata ai dashboard o agli avvisi compilati con le metriche.

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

L'esempio precedente:

• Aggiunge un middleware per arricchire le metriche delle richieste in ASP.NET Core.
• Ottiene il IHttpMetricsTagsFeature da HttpContext. La funzionalità è presente nel contesto solo se un utente è in ascolto della metrica. Verificare che IHttpMetricsTagsFeature non sia null prima di usarlo.
• Aggiunge un tag personalizzato contenente l'origine marketing della richiesta alla http.server.request.duration metrica.
  • Il tag ha il nome mkt_medium e un valore in base al valore della stringa di query utm_medium . Il utm_medium valore viene risolto in un intervallo noto di valori.
  • Il tag consente di classificare le richieste in base al tipo di supporto marketing, che può essere utile durante l'analisi del traffico dell'app Web.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();

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

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

Creare metriche personalizzate

Si creano metriche usando le API nel namespace System.Diagnostics.Metrics. Per informazioni, vedere Creare metriche personalizzate.

Creazione di metriche nelle app ASP.NET Core con IMeterFactory

Creare Meter istanze nelle app ASP.NET Core con IMeterFactory.

ASP.NET Core registra IMeterFactory nell'inserimento delle dipendenze (DI) per impostazione predefinita. La fabbrica dei contatori integra le metriche con l'Iniezione delle Dipendenze, facilitando l'isolamento e la raccolta delle metriche. IMeterFactory è particolarmente utile per i test. Consente l'esecuzione side-by-side di più test e raccoglie solo i valori delle metriche registrati in un test.

Per usare IMeterFactory in un'app, creare un tipo che usa IMeterFactory per creare le metriche personalizzate dell'app:

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

Registrare il tipo di metrica con l'inserimento delle dipendenze in Program.cs:

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

Inserisci il tipo di metriche e registra i valori, se necessario. Poiché il tipo di metrica è registrato nella dependency injection, può essere usato con controller MVC, API minimali o qualsiasi altro tipo creato tramite dependency injection:

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

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

Per monitorare il contatore "Contoso.Web", usare il comando dotnet-counters seguente.

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

Viene visualizzato output simile al seguente:

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    

Osservare le metriche in Grafana usando OpenTelemetry e Prometheus

Panoramica

OpenTelemetry:

• Progetto open source indipendente dal fornitore supportato da Cloud Native Computing Foundation.
• Standardizza la generazione e la raccolta dei dati di telemetria per il software nativo del cloud.
• Funziona con .NET usando le API delle metriche .NET.
• È approvato da Monitoraggio di Azure e da molti fornitori di APM.

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("Microsoft.AspNetCore")
        .AddSource("MyApp"));

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData", true);

Questa esercitazione illustra una delle integrazioni disponibili per le metriche OpenTelemetry usando i progetti OSS Prometheus e Grafana. Flusso di dati delle metriche:

1. Le API della metrica core ASP.NET registrano le misurazioni dall'app di esempio.

2. La libreria .NET OpenTelemetry in esecuzione nell'app aggrega le misurazioni.

3. La libreria di esportazione Prometheus rende disponibili i dati aggregati tramite un endpoint delle metriche HTTP. 'Exporter' è ciò che OpenTelemetry chiama le librerie che trasmettono dati di telemetria a back-end specifici del fornitore.

4. Un server Prometheus:

   • Interroga l'endpoint delle metriche.
   • Legge i dati.
   • Archivia i dati in un database per la persistenza a lungo termine. Prometheus si riferisce alla lettura e all'archiviazione dei dati come all'estrazione da un endpoint.
   • Può essere eseguito in un computer diverso.

5. Server Grafana:

   • Esegue una query sui dati archiviati in Prometheus e li visualizza in una dashboard di monitoraggio basata sul Web.
   • Può essere eseguito in un computer diverso.

Visualizzare le metriche dall'app di esempio

Passare all'app di esempio. Il browser mostra Hello OpenTelemetry! ticks:<3digits> dove 3digits sono le ultime tre cifre dell'oggetto DateTime.Ticks corrente.

Aggiungere /metrics all'URL per visualizzare l'endpoint delle metriche. Il browser visualizza le metriche raccolte:

Impostare e configurare Prometheus

Seguire i primi passaggi di Prometheus per configurare un server Prometheus e verificare che funzioni.

Modificare il file di configurazione prometheus.yml in modo che Prometheus raccolga le metriche dall'endpoint esposto dall'app di esempio. Aggiungere il testo evidenziato seguente nella sezione 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.

Nel codice YAML evidenziato precedente sostituire 5045 con il numero di porta usato dall'app di esempio.

Avvia Prometheus

1. Ricaricare la configurazione o riavviare il server Prometheus.
2. Verificare che OpenTelemetryTest sia nello stato UP nella pagina Stato> Destinazioni del portale Web Prometheus.

Selezionare l'icona Apri Esplora metriche per visualizzare le metriche disponibili:

Immettere una categoria di contatori, ad http_ esempio nella casella di input Espressione per visualizzare le metriche disponibili:

In alternativa, immettere una categoria di contatori, ad kestrel esempio nella casella di input Espressione per visualizzare le metriche disponibili:

Visualizzare le metriche in una dashboard di Grafana

• Seguire le istruzioni di installazione per installare Grafana e connetterlo a un'origine dati Prometheus.

• Seguire Creazione di un grafico Prometheus. In alternativa, i dashboard predefiniti per le metriche .NET sono disponibili per il download nei dashboard del team .NET @ grafana.com. Il file JSON del dashboard scaricato può essere importato in Grafana.

Testare le metriche nelle app ASP.NET Core

È possibile testare le metriche nelle app ASP.NET Core. Un modo per eseguire questa operazione consiste nel raccogliere ed asserire i valori delle metriche nei test di integrazione ASP.NET Core usando 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"]);
            });
    }
}

Il test precedente:

• Avvia un'applicazione web in memoria con WebApplicationFactory<TEntryPoint>. Program nell'argomento generico della fabbrica specifica l'app Web.
• Raccoglie i valori delle metriche con MetricCollector<T>
  • Richiede un riferimento al pacchetto Microsoft.Extensions.Diagnostics.Testing.
  • Il MetricCollector<T> viene creato utilizzando l'applicazione web IMeterFactory. Ciò consente all'agente di raccolta di segnalare solo i valori delle metriche registrati dal test.
  • Includi il nome del contatore, Microsoft.AspNetCore.Hosting, e il nome dell'indicatore http.server.request.duration da raccogliere.
• Effettua una richiesta HTTP all'app Web.
• Verifica il test utilizzando i risultati del raccoglitore di metriche.

dotnet-counters monitor -n YourAppName --counters Microsoft.AspNetCore.Identity

Misuratori e contatori di ASP.NET Core

Per un elenco di misuratori e contatori di ASP.NET Core, vedi metriche di ASP.NET Core. In ASP.NET Core 11 e versioni successive, i contatori predefiniti del server HTTP (ad esempio, Microsoft.AspNetCore.Hosting e Microsoft.AspNetCore.Server.Kestrel) generano dati conformi alle parti richieste delle convenzioni semantiche del server HTTP OpenTelemetry. È possibile usare questi contatori con OpenTelemetry SDK senza il OpenTelemetry.Instrumentation.AspNetCore pacchetto.

Risorse aggiuntive

• Aspire Panoramica del dashboard
• Esplorare i Aspire dati di telemetria
• ASP.NET Core metriche predefinite