Metryki systemu ASP.NET Core

Metryki to pomiary liczbowe zgłaszane z biegiem czasu. Służy do monitorowania kondycji aplikacji i generowania alertów. Na przykład usługa internetowa może śledzić liczbę:

• Liczba żądań otrzymywanych na sekundę.
• Liczba milisekund potrzebnych na odpowiedź.
• Odpowiedzi wysyłane z błędem.

Zgłoś te metryki do systemu monitorowania w regularnych odstępach czasu. Skonfiguruj pulpity nawigacyjne, aby wyświetlać metryki i tworzyć alerty w celu powiadamiania osób o problemach. Jeśli usługa internetowa ma odpowiadać na żądania w ciągu 400 ms i zaczyna odpowiadać w 600 ms, system monitorowania może powiadomić pracowników operacyjnych, że odpowiedź aplikacji jest wolniejsza niż zwykle.

Pełną listę instrumentów wraz z ich atrybutami opisano w artykule Wbudowane metryki platformy ASP.NET Core.

Używanie metryk

Korzystanie z metryk obejmuje następujące elementy:

• Instrumentacja: kod w bibliotekach platformy .NET wykonuje pomiary i kojarzy te miary z nazwą metryki. Platforma .NET i ASP.NET Core zawierają wiele wbudowanych metryk.
• Zbieranie i przechowywanie: Aplikacja .NET konfiguruje przesyłanie nazwanych metryk do zewnętrznego przechowywania i analizy. Niektóre narzędzia mogą wykonywać konfigurację poza aplikacją przy użyciu plików konfiguracji lub narzędzia interfejsu użytkownika.
• Wizualizacja: Narzędzie, które może wyświetlać metryki w formacie czytelnym dla człowieka. Na przykład Grafana i Prometheus.
• Ostrzegania: Narzędzie, które dostarcza powiadomienia, gdy metryka przekracza próg. Jeśli na przykład średni czas odpowiedzi dla usługi internetowej przekracza 400 ms, alert można wysłać do personelu operacyjnego.
• Analiza: Narzędzie, które może analizować metryki w czasie. To narzędzie jest często internetowym pulpitem nawigacyjnym, który można dostosować, aby wyświetlić najważniejsze metryki dla określonej aplikacji.

Instrumentowany kod może rejestrować miary liczbowe, ale aby utworzyć przydatne metryki do monitorowania, należy agregować, przesyłać i przechowywać miary. Proces agregowania, przesyłania i przechowywania danych jest nazywany kolekcją. W tym samouczku przedstawiono kilka przykładów zbierania i wyświetlania metryk:

• Wypełnianie metryk w narzędziu Grafana za pomocą OpenTelemetry i Prometheus.
• Wyświetlanie metryk w czasie rzeczywistym za pomocą polecenia dotnet-counters

Można również skojarzyć miary z parami klucz-wartość nazywanymi tagami, które umożliwiają kategoryzowanie danych na potrzeby analizy. Aby uzyskać więcej informacji, zobacz Metryki wielowymiarowe.

Tworzenie aplikacji startowej

Utwórz nową aplikację ASP.NET Core za pomocą następującego polecenia:

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

Zastąp zawartość Program.cs następującym kodem:

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

Wyświetlanie metryk za pomocą dotnet-counters

dotnet-counters to narzędzie wiersza polecenia, które może wyświetlać metryki na żywo dla aplikacji platformy .NET na żądanie. Nie wymaga konfiguracji, co ułatwia badania doraźne lub weryfikację działania instrumentacji metryk. Działa zarówno z interfejsami API opartymi na System.Diagnostics.Metrics jak i EventCounters.

Jeśli narzędzie dotnet-counters nie jest zainstalowane, uruchom następujące polecenie:

dotnet tool update -g dotnet-counters

Gdy aplikacja testowa jest uruchomiona, uruchom dotnet-counters. Poniższe polecenie przedstawia przykład dotnet-counters monitorowania wszystkich metryk z miernikaMicrosoft.AspNetCore.Hosting.

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

Wyświetlane są dane wyjściowe podobne do następujących:

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

Aby uzyskać więcej informacji, zobacz dotnet-counters.

Wzbogać metrykę żądania ASP.NET Core

ASP.NET Core ma wiele wbudowanych metryk. Metryka http.server.request.duration :

• Rejestruje czas trwania żądań HTTP na serwerze.
• Przechwytuje informacje o żądaniu w tagach, takie jak dopasowana trasa i kod statusu odpowiedzi.

Metryka http.server.request.duration umożliwia wzbogacanie tagów za pomocą IHttpMetricsTagsFeature. Wzbogacanie polega na tym, że biblioteka lub aplikacja dodaje własne tagi do metryki. Ta funkcja jest przydatna, jeśli aplikacja chce dodać niestandardową kategoryzację do dashboardów lub alertów opartych na metrykach.

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

Powyższy przykład:

• Dodaje middleware w celu ulepszenia metryki żądania ASP.NET Core.
• Pobiera element IHttpMetricsTagsFeature z .HttpContext Funkcja jest obecna w kontekście tylko wtedy, gdy ktoś nasłuchuje metryki. Sprawdź przed użyciem, czy IHttpMetricsTagsFeature nie jest null.
• Dodaje niestandardowy tag, który zawiera źródło marketingowe żądania, do metryki http.server.request.duration.
  • Tag ma nazwę mkt_medium i wartość na podstawie wartości ciągu zapytania utm_medium . Wartość utm_medium jest przekształcana na znany zakres wartości.
  • Tag umożliwia kategoryzowanie żądań według typu medium marketingowego, co może być przydatne podczas analizowania ruchu aplikacji internetowej.

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

Tworzenie metryk niestandardowych

Metryki tworzysz za pomocą interfejsów API w przestrzeni nazw System.Diagnostics.Metrics. Aby uzyskać informacje, zobacz Tworzenie metryk niestandardowych.

Tworzenie metryk w aplikacjach ASP.NET Core za pomocą polecenia IMeterFactory

Tworzenie wystąpień Meter w aplikacjach ASP.NET Core za pomocą polecenia IMeterFactory.

ASP.NET Core domyślnie rejestruje IMeterFactory w iniekcji zależności (DI). Fabryka mierników integruje metryki z DI, co ułatwia ich izolowanie i zbieranie. IMeterFactory jest szczególnie przydatny do testowania. Umożliwia uruchamianie wielu testów obok siebie i zbieranie tylko wartości metryk zarejestrowanych w teście.

Aby użyć IMeterFactory w aplikacji, utwórz typ, który używa IMeterFactory do tworzenia niestandardowych metryk aplikacji.

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

Zarejestruj typ metryk za pomocą DI w Program.cs.

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

Należy wdrożyć typ metryk i zanotować wartości tam, gdzie to konieczne. Ponieważ typ metryk jest zarejestrowany w DI, można go używać z kontrolerami MVC, interfejsami Minimal API lub dowolnym innym typem tworzonym przez 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);
});

Aby monitorować miernik "Contoso.Web", użyj następującego polecenia dotnet-counters .

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

Wyświetlane są dane wyjściowe podobne do następujących:

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    

Wyświetlanie metryk w Grafanie z użyciem OpenTelemetry i Prometheus.

Overview

OpenTelemetry:

• Jest neutralnym dla dostawcy projektem open source obsługiwanym przez Cloud Native Computing Foundation.
• Standaryzacja generowania i zbierania danych telemetrycznych dla oprogramowania natywnego dla chmury.
• Współpracuje z platformą .NET przy użyciu interfejsów API metryk .NET.
• Jest zatwierdzony przez usługę Azure Monitor i wielu dostawców APM.

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

W tym samouczku przedstawiono jedną z integracji dostępnych dla metryk OpenTelemetry przy użyciu projektów open-source Prometheus i Grafana. Przepływ danych metryk:

1. Interfejsy API metryk ASP.NET Core rejestrują pomiary z przykładowej aplikacji.

2. Biblioteka platformy .NET OpenTelemetry uruchomiona w aplikacji agreguje miary.

3. Biblioteka eksportera Prometheus udostępnia zagregowane dane za pośrednictwem punktu końcowego metryk HTTP. W terminologii OpenTelemetry "Eksporter" to biblioteki, które przesyłają dane telemetryczne do zapleczy specyficznych dla dostawcy.

4. Serwer Prometheus

   • Odpytuje punkt końcowy metryk.
   • Odczytuje dane.
   • Przechowuje dane w bazie danych pod kątem trwałości długoterminowej. Prometheus określa odczytywanie i przechowywanie danych jako pobieranie z punktu końcowego.
   • Można uruchomić na innej maszynie.

5. Serwer Grafana:

   • Wykonuje zapytanie dotyczące danych przechowywanych w rozwiązaniu Prometheus i wyświetla je na internetowym pulpicie nawigacyjnym monitorowania.
   • Można uruchomić na innej maszynie.

Wyświetlanie metryk z przykładowej aplikacji

Przejdź do przykładowej aplikacji. Przeglądarka wyświetla Hello OpenTelemetry! ticks:<3digits>, gdzie 3digits to trzy ostatnie cyfry bieżącej wartości DateTime.Ticks.

Dołącz /metrics do adresu URL, aby wyświetlić punkt końcowy metryk. W przeglądarce są wyświetlane zbierane metryki:

Skonfiguruj i ustaw Prometeusza

Postępuj zgodnie z pierwszymi krokami rozwiązania Prometheus , aby skonfigurować serwer Prometheus i potwierdzić, że działa.

Zmodyfikuj plik konfiguracji prometheus.yml , tak aby rozwiązanie Prometheus zeskrobało punkt końcowy metryk, który uwidacznia przykładowa aplikacja. Dodaj następujący wyróżniony tekst w scrape_configs sekcji:

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

W wyróżnionym wcześniej fragmencie YAML zastąp 5045 numerem portu używanym przez przykładową aplikację.

Rozpocznij Prometheus

1. Załaduj ponownie konfigurację lub uruchom ponownie serwer Prometheus.
2. Upewnij się, że OpenTelemetryTest jest w stanie UP na stronie Status>Cele portalu internetowego Prometheus.

Wybierz ikonę Otwórz eksploratora metryk , aby wyświetlić dostępne metryki:

Wprowadź kategorię licznika, taką jak http_, w polu Wyrażenie, aby zobaczyć dostępne metryki:

Alternatywnie wprowadź kategorię licznika, taką jak kestrel, w polu Wyrażenie, aby zobaczyć dostępne metryki:

Wyświetlanie metryk na pulpicie Grafana

• Postępuj zgodnie z instrukcjami instalacji , aby zainstalować aplikację Grafana i połączyć ją ze źródłem danych Prometheus.

• Postępuj zgodnie z instrukcjami tworzenia grafu Prometheus. Alternatywnie, przygotowane wcześniej dashboardy dla metryk .NET są dostępne do pobrania na dashboardach zespołu .NET @ grafana.com. Pobrany kod JSON pulpitu nawigacyjnego można zaimportować do narzędzia Grafana.

Testowanie metryk w aplikacjach ASP.NET Core

Metryki można przetestować w aplikacjach ASP.NET Core. Jednym ze sposobów jest zbieranie i potwierdzanie wartości metryk w testach integracji ASP.NET Core przy użyciu polecenia 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"]);
            });
    }
}

Poprzedni test:

• Uruchamia aplikację internetową w pamięci za pomocą polecenia WebApplicationFactory<TEntryPoint>. Program w argumencie ogólnym fabryki określa aplikację internetową.
• Zbiera wartości metryk za pomocą polecenia MetricCollector<T>
  • Wymaga odwołania do pakietu Microsoft.Extensions.Diagnostics.Testing.
  • Element MetricCollector<T> jest tworzony przy użyciu aplikacji IMeterFactoryinternetowej . Dzięki temu moduł zbierający może zgłaszać tylko wartości wskaźników zarejestrowanych przez test.
  • Zawiera nazwę miernika Microsoft.AspNetCore.Hosting i nazwę licznika http.server.request.duration do zebrania danych.
• Wysyła żądanie HTTP do aplikacji internetowej.
• Potwierdza test przy użyciu wyników modułu zbierającego metryki.

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

liczniki i mierniki ASP.NET Core

Listę mierników i liczników platformy ASP.NET Core można znaleźć w artykule Metryki ASP.NET Core. W ASP.NET Core 11 i nowszych wbudowane mierniki serwera HTTP (na przykład Microsoft.AspNetCore.Hosting i Microsoft.AspNetCore.Server.Kestrel) emitują dane zgodne z wymaganymi częściami semantyki serwera HTTP OpenTelemetry. Z tych mierników można korzystać przy użyciu zestawu SDK OpenTelemetry bez pakietu OpenTelemetry.Instrumentation.AspNetCore.