ASP.NET Core-Metriken

Metriken sind numerische Messungen, die im Laufe der Zeit gemeldet werden. Verwenden Sie sie, um den Status einer App zu überwachen und Warnungen zu generieren. Beispielsweise kann ein Webdienst nachverfolgen, wie viele:

• Anfragen, die pro Sekunde empfangen werden.
• Antwortzeit in Millisekunden.
• Antworten, die mit einem Fehler gesendet werden.

Melden Sie diese Metriken in regelmäßigen Abständen an ein Überwachungssystem. Richten Sie Dashboards ein, um Metriken anzuzeigen und Warnungen zu erstellen, um Personen über Probleme zu informieren. Wenn der Webdienst innerhalb von 400 ms auf Anforderungen reagieren soll und in 600 ms reagiert, kann das Überwachungssystem das Betriebspersonal benachrichtigen, dass die App-Antwort langsamer als normal ist.

Die umfassende Liste aller Instrumente zusammen mit ihren Attributen wird in ASP.NET Core integrierten Metriken beschrieben.

Metriken verwenden

Die Verwendung von Metriken umfasst Folgendes:

• Instrumentation:Der Code in den .NET-Bibliotheken nimmt Messungen vor und ordnet diese Messungen einem Metriknamen zu. .NET und ASP.NET Core enthalten viele integrierte Metriken.
• Sammlung und Speicherung: Eine .NET-App konfiguriert benannte Metriken, die von der App für externe Speicherung und Analyse übertragen werden. Einige Tools können eine Konfiguration außerhalb der App mithilfe von Konfigurationsdateien oder einem UI-Tool durchführen.
• Visualisierung: Ein Tool, das die Metriken in einem lesbaren Format anzeigen kann. Zum Beispiel Grafana und Prometheus.
• Alarmierung: Ein Tool, das Benachrichtigungen bereitstellt, wenn eine Metrik einen Schwellenwert überschreitet. Wenn beispielsweise die durchschnittliche Reaktionszeit für einen Webdienst 400 ms überschreitet, kann eine Warnung an die Betriebsmitarbeiter gesendet werden.
• Analyse: Ein Tool, das die Metriken im Laufe der Zeit analysieren kann. Dieses Tool ist häufig ein webbasiertes Dashboard, das angepasst werden kann, um die wichtigsten Metriken für eine bestimmte App anzuzeigen.

Mit instrumentiertem Code können numerische Messungen erfasst werden, aber um nützliche Metriken für die Überwachung zu erstellen, müssen Sie die Messungen aggregieren, übertragen und speichern. Das Verfahren zum Aggregieren, Übertragen und Speichern von Daten wird als Sammlung bezeichnet. Dieses Lernprogramm zeigt mehrere Beispiele für das Sammeln und Anzeigen von Metriken:

• Auffüllen von Metriken in Grafana mit OpenTelemetry und Prometheus.
• Anzeigen von Metriken in Echtzeit mit dotnet-counters

Sie können messungen auch Schlüsselwertpaaren zuordnen, die als Tags bezeichnet werden, mit denen Sie Daten für die Analyse kategorisieren können. Weitere Informationen finden Sie unter Mehrdimensionale Metriken.

Erstellen der Starter-App

Erstellen Sie mit dem folgenden Befehl eine neue ASP.NET Core-App:

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

Ersetzen Sie den Inhalt von Program.cs mit dem folgenden Code:

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

Anzeigen von Metriken mit Dotnet-Counters

dotnet-counters ist ein Befehlszeilentool , das Livemetriken für .NET-Apps bei Bedarf anzeigen kann. Es ist keine Einrichtung erforderlich, sodass es nützlich ist für Ad-hoc-Untersuchungen oder um zu überprüfen, ob die Metrikinstrumentation funktioniert. Es funktioniert sowohl mit System.Diagnostics.Metrics-basierten APIs als auch mit EventCounters.

Wenn das Tool dotnet-counters nicht installiert ist, führen Sie den folgenden Befehl aus:

dotnet tool update -g dotnet-counters

Während die Test-App ausgeführt wird, starten Sie dotnet-counters. Der folgende Befehl zeigt ein Beispiel für die Überwachung aller dotnet-counters Metriken vom Microsoft.AspNetCore.Hosting Messgerät.

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

Ein Output ähnlich der folgenden wird angezeigt:

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

Weitere Informationen finden Sie unter dotnet-counters.

Anreichern der ASP.NET Core-Anforderungsmetrik

ASP.NET Core enthält viele integrierte Metriken. Die http.server.request.duration-Metrik:

• zeichnet die Dauer von HTTP-Anforderungen auf dem Server auf
• erfasst Anforderungsinformationen in Tags, z. B. den abgeglichenen Routen- und Antwortstatuscode

Die http.server.request.duration Metrik unterstützt die Tag-Anreicherung durch die Verwendung von IHttpMetricsTagsFeature. Anreicherung bedeutet, dass eine Bibliothek oder App einer Metrik eigene Tags hinzufügt. Dieses Feature ist nützlich, wenn eine App Dashboards oder Warnungen, die mit Metriken erstellt wurden, eine benutzerdefinierte Kategorisierung hinzufügen möchte.

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

Das vorherige Beispiel:

• fügt Middleware hinzu, um die ASP.NET Core-Anforderungsmetrik anzureichern
• Ruft IHttpMetricsTagsFeature aus HttpContext ab. Die Funktion ist nur dann im Kontext vorhanden, wenn jemand auf die Metrik lauscht. Vergewissern Sie sich, dass IHttpMetricsTagsFeature nicht null ist, bevor Sie es verwenden.
• Fügt der http.server.request.duration-Metrik ein benutzerdefiniertes Tag hinzu, das die Marketingquelle der Anforderung enthält.
  • Das Tag weist den Namen mkt_medium und einen Wert auf, der auf dem Abfragezeichenfolgenwert utm_medium basiert. Der utm_medium-Wert wird in einen bekannten Wertebereich aufgelöst.
  • Mit dem Tag können Anforderungen nach Marketingmediumtyp kategorisiert werden, was beim Analysieren des Web-App-Datenverkehrs nützlich sein könnte.

Hinweis

Beim Anreichern mit benutzerdefinierten Tags die Best Practices für mehrdimensionale Metriken befolgen. Tags, die zu viele sind oder einen ungebundenen Bereich aufweisen, erstellen viele Tagkombinationen, was zu hohen Dimensionen führt. Sammlungstools weisen Grenzwerte für unterstützte Dimensionen für einen Leistungsindikator auf und filtern möglicherweise Ergebnisse, um eine übermäßige Arbeitsspeichernutzung zu verhindern.

HTTP-Metriken für bestimmte Endpunkte und Anfragen deaktivieren

Der Verzicht auf die Aufzeichnung von Metriken ist besonders nützlich bei Endpunkten, die häufig von automatisierten Systemen aufgerufen werden, z. B. für Zustandsprüfungen. Aufzeichnungsmetriken für diese Anforderungen sind im Allgemeinen nicht erforderlich. Unerwünschte Telemetrie verwendet Ressourcen zum Sammeln und Speichern und kann Ergebnisse, die in einem Telemetriedashboard angezeigt werden, verfälschen.

Sie können HTTP-Anforderungen an einen Endpunkt aus Metriken ausschließen, indem Sie Metadaten hinzufügen, entweder mit dem DisableHttpMetrics-Attribut oder der DisableHttpMetrics-Methode :

• Fügen Sie das DisableHttpMetrics-Attribut dem Web-API-Controller, SignalR Hub oder gRPC-Dienst hinzu.
• Rufen Sie DisableHttpMetrics beim Zuordnen von Endpunkten beim Start der App auf:

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

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

Alternativ wurde die IHttpMetricsTagsFeature.MetricsDisabled Eigenschaft für Folgendes hinzugefügt:

• Erweiterte Szenarien, in denen eine Anforderung keinem Endpunkt zugeordnet ist.
• Dynamisches Deaktivieren der Metriksammlung für bestimmte HTTP-Anforderungen.

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

Erstellen benutzerdefinierter Metriken

Sie erstellen Metriken mithilfe von APIs im System.Diagnostics.Metrics Namespace. Weitere Informationen finden Sie unter Erstellen benutzerdefinierter Metriken.

Erstellen von Metriken in ASP.NET Core-Apps mit IMeterFactory

Erstellen von Meter-Instanzen in ASP.NET Core-Anwendungen mit IMeterFactory.

ASP.NET Core registriert IMeterFactory standardmäßig in Dependency Injection (DI). Die Verbrauchseinheitenfactory integriert Metriken in DI, was die Isolierung und Sammlung von Metriken vereinfacht. IMeterFactory ist besonders beim Testen hilfreich. Sie ermöglicht es mehreren Tests, parallel auszuführen und erfasst nur Metrikwerte, die in einem Test aufgezeichnet werden.

Um IMeterFactory in einer App zu verwenden, erstellen Sie einen Typ, der IMeterFactory verwendet, um die benutzerdefinierten Metriken der App zu erstellen:

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

Registrieren Sie den Metriktyp bei DI in Program.cs:

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

Fügen Sie den Metriktyp ein, und erfassen Sie Werte nach Bedarf. Da der Metriktyp in DI registriert ist, kann er mit MVC-Controllern, minimalen APIs oder einem anderen Typ verwendet werden, der von DI erstellt wird:

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

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

Um das „Contoso.Web“-Meter zu überwachen, verwenden Sie den folgenden dotnet-counters-Befehl.

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

Ein Output ähnlich der folgenden wird angezeigt:

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    

Anzeigen von Metriken in Grafana mit OpenTelemetry und Prometheus

Overview

OpenTelemetry:

• Ist ein anbieterneutrales Open-Source-Projekt, das von der Cloud Native Computing Foundation unterstützt wird.
• Standardisiert das Generieren und Sammeln von Telemetrie für cloudeigene Software.
• Funktioniert mit .NET mithilfe der .NET-Metrik-APIs.
• Wird von Azure Monitor und vielen APM-Anbietern unterstützt.

Dieses Tutorial zeigt eine der Integrationen, die für OpenTelemetry-Metriken mithilfe der OSS-Projekte Prometheus und Grafana verfügbar sind. Der Metrikdatenfluss:

1. Die ASP.NET Core-Metrik-APIs zeichnen Messungen aus der Beispiel-App auf.

2. Die OpenTelemetry .NET-Bibliothek, die in der App ausgeführt wird, aggregiert die Messungen.

3. Die Prometheus-Exporterbibliothek stellt die aggregierten Daten über einen HTTP-Metrikenendpunkt zur Verfügung. "Exporter" ist der Begriff, den OpenTelemetry für die Bibliotheken verwendet, die Telemetriedaten an herstellerspezifische Back-Ends übertragen.

4. Ein Prometheus-Server:

   • Fragt den Metrikenendpunkt ab.
   • Liest die Daten.
   • Speichert die Daten in einer Datenbank für langfristige Persistenz. Prometheus bezeichnet in diesem Zusammenhang das Lesen und Speichern von Daten als Scraping eines Endpunkts.
   • Kann auf einem anderen Computer ausgeführt werden.

5. Der Grafana-Server:

   • Fragt die in Prometheus gespeicherten Daten ab und zeigt sie auf einem webbasierten Überwachungsdashboard an.
   • Kann auf einem anderen Computer ausgeführt werden.

Anzeigen von Metriken aus der Beispiel-App

Wechseln Sie zur Beispiel-App. Der Browser zeigt Hello OpenTelemetry! ticks:<3digits> an, wobei 3digits die letzten drei Ziffern der aktuellen DateTime.Ticks sind.

Fügen Sie /metrics an die URL an, um den Metrikendpunkt anzuzeigen. Der Browser zeigt die erfassten Metriken an:

Einrichten und Konfigurieren von Prometheus

Führen Sie die ersten Schritte von Prometheus aus, um einen Prometheus-Server einzurichten und zu bestätigen, dass er funktioniert.

Ändern Sie die prometheus.yml Konfigurationsdatei so, dass Prometheus den Metrikendpunkt verschrottet, den die Beispiel-App verfügbar macht. Fügen Sie den folgenden hervorgehobenen Text im scrape_configs-Abschnitt hinzu:

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

Ersetzen Sie 5045 im vorherigen hervorgehobenen YAML durch die Portnummer, die von der Beispiel-App verwendet wird.

Prometheus starten

1. Laden Sie die Konfiguration neu, oder starten Sie den Prometheus-Server neu.
2. Vergewissern Sie sich auf der Seite Status>Ziele des Prometheus-Webportals, dass OpenTelemetryTest den Status UP aufweist.

Wählen Sie das Symbol Metrik-Explorer öffnen aus, um die verfügbaren Metriken anzuzeigen:

Geben Sie eine Indikatorkategorie wie http_ in das Eingabefeld Expression ein, um die verfügbaren Metriken anzuzeigen:

Alternativ können Sie eine Zählerkategorie wie kestrel in das Eingabefeld Ausdruck eingeben, um die verfügbaren Metriken anzuzeigen:

Anzeigen von Metriken auf einem Grafana-Dashboard

• Befolgen Sie die Installationsanweisungen, um Grafana zu installieren und mit einer Prometheus-Datenquelle zu verbinden.

• Befolgen Sie die Anweisungen zum Erstellen eines Prometheus-Diagramms. Alternativ können Sie auch vorgefertigte Dashboards für .NET-Metriken unter .NET Team Dashboards @ grafana.com herunterladen. Die heruntergeladene Dashboard-JSON kann in Grafana importiert werden.

Testen von Metriken in ASP.NET Core-Apps

Sie können Metriken in ASP.NET Core Apps testen. Eine Möglichkeit hierzu ist das Sammeln und Bestätigen von Metrikwerten in ASP.NET Core Integrationstests mithilfe von 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"]);
            });
    }
}

Der vorherige Test:

• Es wird ein Bootstrap einer Web-App im Arbeitsspeicher mit WebApplicationFactory<TEntryPoint> ausgeführt. Program im generischen Argument der Factory gibt die Web-App an.
• Metrikwerte werden mit MetricCollector<T> gesammelt
  • Erfordert einen Paketverweis auf Microsoft.Extensions.Diagnostics.Testing.
  • Der MetricCollector<T> wird mithilfe der IMeterFactory der Web-App erstellt. Auf diese Weise kann der Collector nur Metrikwerte melden, die vom Test aufgezeichnet werden.
  • Enthält den Namen des Zählers, Microsoft.AspNetCore.Hosting, und den zu erfassenden Zählernamen, http.server.request.duration.
• Sendet eine HTTP-Anforderung an die Web-App.
• Bestätigt den Test mithilfe von Ergebnissen aus dem Metriksammler.

ASP.NET Kernmetriken Identity

Identity ASP.NET Core Observability hilft Ihnen, Benutzerverwaltungsaktivitäten und Authentifizierungsprozesse zu überwachen.

Die Metriken befinden sich im Microsoft.AspNetCore.Identity Meter und werden in den folgenden Abschnitten beschrieben.

Metriken für die Benutzerverwaltung

• aspnetcore.identity.user.create.duration misst die Dauer von Benutzererstellungsvorgängen.
• aspnetcore.identity.user.update.duration misst die Dauer von Benutzeraktualisierungsvorgängen.
• aspnetcore.identity.user.delete.duration misst die Dauer von Benutzerlöschvorgängen.
• aspnetcore.identity.user.check_password_attempts zählt Kennwortüberprüfungsversuche.
• aspnetcore.identity.user.generated_tokens Zählt Token, die für Benutzer generiert werden, z. B. Kennwortzurücksetzungstoken.
• aspnetcore.identity.user.verify_token_attempts zählt Tokenüberprüfungsversuche.

Authentifizierungsmetriken

• aspnetcore.identity.sign_in.authenticate.duration misst die Dauer von Authentifizierungsvorgängen.
• aspnetcore.identity.sign_in.check_password_attempts zählt die Kennwortüberprüfungsversuche während der Anmeldung.
• aspnetcore.identity.sign_in.sign_ins zählt erfolgreiche Anmeldungen.
• aspnetcore.identity.sign_in.sign_outs zählt Abmeldungen.
• aspnetcore.identity.sign_in.two_factor_clients_remembered zählt die gespeicherten Zwei-Faktor-Authentifizierungsclients.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten zählt vergessene Zwei-Faktor-Clients.

Verwenden Sie die folgenden Metriken, um:

• Überwachen sie die Benutzerregistrierung und -verwaltung.
• Verfolgen Sie Authentifizierungsmuster und potenzielle Sicherheitsprobleme.
• Messen Sie die Leistung von Vorgängen Identity.
• Beobachten Sie die Verwendung der zweistufigen Authentifizierung.

Anzeigen von Identity Metriken

Verwenden Sie dotnet-counters, um diese Metriken anzuzeigen und sie in Echtzeit zu überwachen. Oder exportieren Sie sie nach Prometheus, und visualisieren Sie sie in Grafana mithilfe der weiter oben in diesem Artikel beschriebenen Techniken.

So überwachen Sie beispielsweise alle Identity Metriken mit dotnet-counters:

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

ASP.NET Core-Verbrauchseinheiten und -Leistungsindikatoren

Eine Liste der ASP.NET Core Meter und Zähler finden Sie unter ASP.NET Core Metriken. In ASP.NET Core 11 und später geben die integrierten HTTP-Servermetriken (z. B. Microsoft.AspNetCore.Server.Kestrel und Microsoft.AspNetCore.Hosting) Daten aus, die den erforderlichen Teilen der OpenTelemetry-HTTP-Server-Semantikkonventionen entsprechen. Sie können diese Meter mit dem OpenTelemetry SDK ohne das OpenTelemetry.Instrumentation.AspNetCore Paket nutzen.