ASP.NET Core metriky

Metriky jsou číselné měření hlášená v průběhu času. Slouží k monitorování stavu aplikace a generování výstrah. Webová služba může například sledovat, kolik:

• Počet požadavků přijatých za sekundu.
• Milisekundy, které trvá odpovědět.
• Odpovědi, které odesílá s chybou.

Nahlašte tyto metriky do monitorovacího systému v pravidelných intervalech. Nastavte řídicí panely tak, aby zobrazovaly metriky a vytvářely výstrahy pro upozorňování lidí na problémy. Pokud je webová služba určená k odpovídání na požadavky do 400 ms a začne reagovat v 600 ms, může monitorovací systém informovat provozní pracovníky, že odezva aplikace je pomalejší než normální.

Úplný seznam všech nástrojů společně s jejich atributy je popsán v ASP.NET Core předdefinovaných metrik.

Použití metrik

Použití metrik zahrnuje následující:

• Instrumentace: Kód v knihovnách .NET provádí měření a přidružuje tato měření k názvu metriky. .NET a ASP.NET Core zahrnují mnoho předdefinovaných metrik.
• Kolekce a úložiště: Aplikace .NET konfiguruje pojmenované metriky, které se mají přenášet z aplikace pro externí úložiště a analýzu. Některé nástroje můžou provádět konfiguraci mimo aplikaci pomocí konfiguračních souborů nebo nástroje uživatelského rozhraní.
• Vizualizace: Nástroj, který může zobrazit metriky v čitelné podobě člověka. Například Grafana a Prometheus.
• Upozorňování: Nástroj, který poskytuje oznámení, když metrika překročí prahovou hodnotu. Pokud například průměrná doba odezvy webové služby překročí 400 ms, může se provozním pracovníkům odeslat výstraha.
• Analýza: Nástroj, který může analyzovat metriky v průběhu času. Tento nástroj je často webový řídicí panel, který se dá přizpůsobit tak, aby zobrazoval nejdůležitější metriky pro konkrétní aplikaci.

Instrumentovaný kód může zaznamenávat číselná měření, ale k vytvoření užitečných metrik pro monitorování je potřeba agregovat, přenášet a ukládat měření. Proces agregace, přenosu a ukládání dat se nazývá shromažďování. Tento kurz ukazuje několik příkladů shromažďování a zobrazování metrik:

• Naplňování metrik v Grafaně pomocí OpenTelemetry a Prometheus.
• Zobrazení metrik v reálném čase pomocí dotnet-counters

Měření můžete také přidružit ke párům klíč-hodnota označovaným jako značky, které umožňují kategorizovat data pro analýzu. Další informace najdete v tématu Vícerozměrné metriky.

Vytvoření úvodní aplikace

Pomocí následujícího příkazu vytvořte novou aplikaci ASP.NET Core:

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

Obsah Program.cs nahraďte následujícím kódem:

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

Zobrazení metrik pomocí nástroje dotnet-counters

dotnet-counters je nástroj příkazového řádku, který může zobrazit živé metriky pro aplikace .NET na vyžádání. Nevyžaduje nastavení, což je užitečné pro ad hoc šetření nebo ověření, že instrumentace metrik funguje. Funguje jak s rozhraními API založenými na System.Diagnostics.Metrics, tak s EventCounters.

Pokud nástroj dotnet-counters není nainstalovaný, spusťte následující příkaz:

dotnet tool update -g dotnet-counters

Zatímco je testovací aplikace spuštěná, spusťte dotnet-counters. Následující příkaz ukazuje příklad dotnet-counters monitorování všech metrik z měřičeMicrosoft.AspNetCore.Hosting.

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

Zobrazí se výstup podobný následujícímu:

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

Další informace najdete v tématu dotnet-counters.

Rozšíření metriky požadavků ASP.NET Core

ASP.NET Core má mnoho předdefinovaných metrik. Metrika http.server.request.duration :

• Zaznamenává dobu trvání požadavků HTTP na serveru.
• Zaznamenává informace o požadavcích ve značkách, jako je odpovídající směrovací kód a stavový kód odpovědi.

Metrika http.server.request.duration podporuje rozšiřování značek pomocí IHttpMetricsTagsFeature. Obohacení nastává, když knihovna nebo aplikace přidá k metrice vlastní štítky. Tato funkce je užitečná, pokud aplikace chce přidat vlastní kategorizaci na řídicí panely nebo výstrahy vytvořené pomocí metrik.

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

Předchozí příklad:

• Přidá middleware pro obohacení metriky požadavků v ASP.NET Core.
• Získá IHttpMetricsTagsFeature z HttpContext. Tato funkce se nachází v kontextu pouze v případě, že někdo naslouchá metrikě. Před použitím ověřte, že IHttpMetricsTagsFeature není null.
• Přidá do metriky http.server.request.duration vlastní značku obsahující marketingový zdroj požadavku.
  • Značka má název mkt_medium a hodnotu odvozenou od hodnoty parametru řetězce dotazu utm_medium. Hodnota utm_medium je vyhodnocena na známý rozsah hodnot.
  • Značka umožňuje kategorizaci požadavků podle marketingového média, což může být užitečné při analýze provozu webové aplikace.

Poznámka:

Při obohacování pomocí vlastních značek dodržujte osvědčené postupy pro vícerozměrné metriky. Značky, které jsou příliš velké nebo mají nevázaný rozsah, vytvářejí mnoho kombinací značek, což vede k vysokým dimenzím. Nástroje kolekce mají omezení podporovaných dimenzí pro čítač a můžou filtrovat výsledky, aby se zabránilo nadměrnému využití paměti.

Odhlášení z metrik HTTP u určitých koncových bodů a požadavků

Odhlášení z zaznamenávání metrik je výhodné pro koncové body často volané automatizovanými systémy, jako jsou kontroly stavu. Zaznamenávání metrik pro tyto požadavky je obecně zbytečné. Nežádoucí telemetrie využívá prostředky ke shromažďování a ukládání a může zkreslovat výsledky zobrazené na řídicím panelu telemetrie.

Požadavky HTTP na koncový bod můžete vyloučit z metrik přidáním metadat s atributem DisableHttpMetrics nebo metodou DisableHttpMetrics :

• Přidejte atribut DisableHttpMetrics do kontroleru webového rozhraní API, SignalR centra nebo služby gRPC.
• Zavolejte DisableHttpMetrics při mapování endpointů během spouštění aplikace:

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

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

Alternativně byla vlastnost přidána IHttpMetricsTagsFeature.MetricsDisabled pro:

• Pokročilé scénáře, kdy požadavek není směrován na endpoint.
• Dynamické zakazování shromažďování metrik pro konkrétní požadavky HTTP

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

Vytvoření vlastních metrik

Metriky vytvoříte pomocí rozhraní API v oboru názvů System.Diagnostics.Metrics. Informace najdete v tématu Vytvoření vlastních metrik.

Vytváření metrik v aplikacích ASP.NET Core pomocí IMeterFactory

Vytváření instancí Meter v aplikacích ASP.NET Core pomocí IMeterFactory.

ASP.NET Core ve výchozím nastavení registruje IMeterFactory do injektáže závislostí (DI). Továrna měřičů integruje metriky s DI, což usnadňuje oddělování a shromažďování metrik. IMeterFactory je zvlášť užitečná pro testování. Umožňuje souběžné spuštění více testů a shromažďuje pouze hodnoty metrik, které jsou zaznamenány v testu.

Pokud chcete použít IMeterFactory v aplikaci, vytvořte typ, který používá IMeterFactory k vytvoření vlastních metrik aplikace:

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

Zaregistrujte typ metriky pomocí DI v Program.cs:

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

Tam, kde je to potřeba, zadejte typ metriky a poznamenejte si hodnoty. Vzhledem k tomu, že je typ metrik zaregistrovaný v DI, lze ho použít s řadiči MVC, minimálními rozhraními API nebo jakýmkoli jiným typem, který je vytvořen pomocí 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);
});

Pokud chcete monitorovat měřič Contoso.Web, použijte následující příkaz dotnet-counters .

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

Zobrazí se výstup podobný následujícímu:

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    

Zobrazte metriky v Grafaně pomocí OpenTelemetry a Prometheus

Overview

OpenTelemetry:

• Je dodavatelově neutrální opensourcový projekt podporovaný foundationm Cloud Native Computing Foundation.
• Standardizuje generování a shromažďování telemetrie pro nativní cloudový software.
• Pracuje s .NET pomocí rozhraní API pro metriky .NET.
• Podporují jej Azure Monitor a mnoho dodavatelů APM.

Tento kurz ukazuje jednu z integrací dostupných pro metriky OpenTelemetry pomocí projektů OSS Prometheus a Grafana . Tok dat o metrikách:

1. Rozhraní API pro metriky v ASP.NET Core zaznamenávají naměřené hodnoty z ukázkové aplikace.

2. Knihovna OpenTelemetry .NET spuštěná v aplikaci agreguje měření.

3. Knihovna exportéru Prometheus zpřístupňuje agregovaná data prostřednictvím koncového bodu metrik HTTP. „Exportér“ je označení, které OpenTelemetry používá pro knihovny, jež odesílají telemetrii do backendů konkrétních dodavatelů.

4. Server Prometheus:

   • Pravidelně se dotazuje koncového bodu pro metriky.
   • Čte data.
   • Ukládá data do databáze pro dlouhodobou trvalost. V systému Prometheus se čtení a ukládání dat označuje jako sběr dat z koncového bodu.
   • Může běžet na jiném počítači.

5. Server Grafana:

   • Dotazuje data uložená v systému Prometheus a zobrazí je na webovém řídicím panelu monitorování.
   • Může běžet na jiném počítači.

Zobrazení metrik z ukázkové aplikace

Přejděte do ukázkové aplikace. Prohlížeč ukazuje Hello OpenTelemetry! ticks:<3digits> , kde 3digits jsou poslední tři číslice aktuálního dateTime.Ticks.

Přidejte /metrics na konec adresy URL, abyste zobrazili koncový bod metrik. Prohlížeč zobrazí shromažďované metriky:

Nastavit a nakonfigurovat Prometheus

Postupujte podle Prvních kroků v Prometheu, nastavte server Prometheus a ověřte, že funguje.

Upravte konfigurační soubor prometheus.yml tak, aby Nástroj Prometheus sešrotuje koncový bod metrik, který ukázková aplikace zveřejňuje. Do oddílu scrape_configs přidejte následující zvýrazněný text:

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

V předchozím zvýrazněném YAML nahraďte 5045 číslem portu, které ukázková aplikace používá.

Spustit Prometheus

1. Znovu načtěte konfiguraci nebo restartujte server Prometheus.
2. Ověřte, že OpenTelemetryTest je ve stavu UP na stránce Status>Targets ve webovém portálu Prometheus.

Výběrem ikony Otevřít průzkumníka metrik zobrazíte dostupné metriky:

Zadejte kategorii čítače, například http_ do vstupního pole Výraz , abyste viděli dostupné metriky:

Případně zadejte do vstupního pole Výraz kategorii čítače, například kestrel, chcete-li zobrazit dostupné metriky:

Zobrazení metrik na řídicím panelu Grafana

• Postupujte podle pokynů k instalaci Grafany a připojte ho ke zdroji dat Prometheus.

• Postupujte podle Vytvoření grafu Prometheus. Alternativně jsou k dispozici předem připravené řídicí panely pro metriky .NET ke stažení na týmových řídicích panelech .NET @ grafana.com. Stažený kód JSON řídicího panelu je možné importovat do Grafany.

Testování metrik v aplikacích ASP.NET Core

Metriky můžete testovat v ASP.NET Core aplikacích. Jedním ze způsobů, jak to udělat, je shromažďovat a uplatňovat hodnoty metrik v ASP.NET Core integračních testech pomocí 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"]);
            });
    }
}

Předchozí test:

• Inicializuje webovou aplikaci v paměti pomocí WebApplicationFactory<TEntryPoint>. Program v obecném argumentu továrny určuje webovou aplikaci.
• Shromažďuje hodnoty metrik pomocí MetricCollector<T>
  • Vyžaduje odkaz na balíček Microsoft.Extensions.Diagnostics.Testing.
  • MetricCollector<T> se vytvoří pomocí IMeterFactory webové aplikace. To umožňuje kolektoru hlásit pouze hodnoty metrik zaznamenané testem.
  • Obsahuje název měřiče Microsoft.AspNetCore.Hosting a název čítače http.server.request.duration, které se mají shromažďovat.
• Vytvoří požadavek HTTP na webovou aplikaci.
• Ověří test na základě výsledků z kolektoru metrik.

metriky ASP.NET Core Identity

Identity ASP.NET Core pozorovatelnost pomáhá monitorovat aktivity správy uživatelů a procesy ověřování.

Metriky jsou v měřiči Microsoft.AspNetCore.Identity a jsou popsány v následujících částech.

Metriky správy uživatelů

• aspnetcore.identity.user.create.duration měří dobu trvání operací vytváření uživatelů.
• aspnetcore.identity.user.update.duration měří dobu trvání operací aktualizace uživatele.
• aspnetcore.identity.user.delete.duration měří dobu trvání operací odstranění uživatele.
• aspnetcore.identity.user.check_password_attempts počítá pokusy o ověření hesla.
• aspnetcore.identity.user.generated_tokens počítá tokeny vygenerované pro uživatele, jako jsou tokeny resetování hesla.
• aspnetcore.identity.user.verify_token_attempts počítá pokusy o ověření tokenu.

Metriky ověřování

• aspnetcore.identity.sign_in.authenticate.duration měří dobu trvání ověřovacích operací.
• aspnetcore.identity.sign_in.check_password_attempts spočítá pokusy o kontrolu hesla během přihlášení.
• aspnetcore.identity.sign_in.sign_ins počítá úspěšné přihlášení.
• aspnetcore.identity.sign_in.sign_outs počítá odhlašování.
• aspnetcore.identity.sign_in.two_factor_clients_remembered počítá pamatované dvoufaktorové klienty.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten počítá zapomenuté dvoufaktorové klienty.

Použijte tyto metriky k:

• Monitorování registrace a správy uživatelů
• Sledujte vzory ověřování a potenciální problémy se zabezpečením.
• Změřte výkon Identity operací.
• Sledujte využití dvojúrovňového ověřování.

Zobrazení Identity metrik

Umožňuje dotnet-counters zobrazit tyto metriky a monitorovat je v reálném čase. Nebo je můžete exportovat do Promethea a vizualizovat v Grafaně pomocí postupů popsaných dříve v tomto článku.

Pokud chcete například monitorovat všechny Identity metriky pomocí dotnet-counters:

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

Metriky a čítače v ASP.NET Core

Seznam ASP.NET Core měřičů a čítačů najdete v ASP.NET Core metrikách. V ASP.NET Core 11 a novějších generují integrované měřiče serveru HTTP (například Microsoft.AspNetCore.Hosting aMicrosoft.AspNetCore.Server.Kestrel) data, která odpovídají požadovaným částem sémantických konvencí serveru HTTP OpenTelemetry. Tyto měřiče můžete využívat pomocí sady OpenTelemetry SDK bez OpenTelemetry.Instrumentation.AspNetCore balíčku.