metrische gegevens van ASP.NET Core

Metrische gegevens zijn numerieke metingen die in de loop van de tijd worden gerapporteerd. Gebruik deze om de status van een app te bewaken en waarschuwingen te genereren. Een webservice kan bijvoorbeeld bijhouden hoeveel:

• Aanvragen die per seconde worden ontvangen.
• Milliseconden die nodig zijn om te reageren.
• Reacties die het verzendt met een fout.

Rapporteer deze metrische gegevens met regelmatige tussenpozen aan een bewakingssysteem. Stel dashboards in om metrische gegevens weer te geven en waarschuwingen te maken om mensen op de hoogte te stellen van problemen. Als de webservice is bedoeld om te reageren op aanvragen binnen 400 ms en binnen 600 ms reageert, kan het bewakingssysteem de operationele medewerkers op de hoogte stellen dat het app-antwoord langzamer is dan normaal.

De uitgebreide lijst met alle instrumenten samen met hun kenmerken wordt beschreven in ASP.NET Core ingebouwde metrische gegevens.

Metrische gegevens gebruiken

Het gebruik van metrische gegevens omvat het volgende:

• Instrumentatie: Code in .NET-bibliotheken voert metingen uit en koppelt deze metingen aan een metrieknaam. .NET en ASP.NET Core bevatten veel ingebouwde metrische gegevens.
• Verzameling en opslag: Een .NET-app configureert benoemde metrische gegevens die moeten worden verzonden vanuit de app voor externe opslag en analyse. Sommige hulpprogramma's kunnen configuraties uitvoeren buiten de app met behulp van configuratiebestanden of een ui-hulpprogramma.
• Visualisatie: Een hulpprogramma waarmee de metrische gegevens in een door mensen leesbare indeling kunnen worden weergegeven. Bijvoorbeeld Grafana en Prometheus.
• Waarschuwen: Een hulpprogramma dat meldingen biedt wanneer een metrische waarde een drempelwaarde overschrijdt. Als de gemiddelde reactietijd voor een webservice bijvoorbeeld groter is dan 400 ms, kan er een waarschuwing worden verzonden naar het operationele personeel.
• Analyse: Een hulpprogramma waarmee de metrische gegevens in de loop van de tijd kunnen worden geanalyseerd. Dit hulpprogramma is vaak een webdashboard dat kan worden aangepast om de belangrijkste metrische gegevens voor een specifieke app weer te geven.

Geïnstrumenteerde code kan numerieke metingen vastleggen, maar om nuttige metrische gegevens te maken voor bewaking, moet u de metingen aggregeren, verzenden en opslaan. Het proces voor het samenvoegen, verzenden en opslaan van gegevens wordt verzameling genoemd. In deze zelfstudie ziet u verschillende voorbeelden van het verzamelen en weergeven van metrische gegevens:

• Metrische gegevens in Grafana vullen met OpenTelemetry en Prometheus.
• Metrische gegevens in realtime weergeven met dotnet-counters

U kunt metingen ook koppelen aan sleutel-waardeparen genaamd tags waarmee u gegevens voor analyse kunt categoriseren. Zie Multidimensionale metrische gegevens voor meer informatie.

De starter-app maken

Maak een nieuwe ASP.NET Core-app met de volgende opdracht:

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

Vervang de inhoud van Program.cs met de volgende 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();

Metingen weergeven met dotnet-counters

dotnet-counters is een opdrachtregelprogramma waarmee live metrische gegevens voor .NET-apps op aanvraag kunnen worden weergegeven. Hiervoor is geen installatie vereist, waardoor het nuttig is voor ad-hoconderzoeken of om te controleren of metrische instrumentatie werkt. Het werkt met zowel System.Diagnostics.Metrics op gebaseerde API's als EventCounters.

Als het hulpprogramma dotnet-counters niet is geïnstalleerd, voert u de volgende opdracht uit:

dotnet tool update -g dotnet-counters

Terwijl de test-app wordt uitgevoerd, start dotnet-counters. De volgende opdracht toont een voorbeeld van het bewaken van dotnet-counters alle metrische gegevens van de Microsoft.AspNetCore.Hosting meter.

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

Uitvoer die lijkt op het volgende wordt weergegeven:

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

Zie dotnet-counters voor meer informatie.

De metrische gegevens van de ASP.NET Core-aanvraag verrijken

ASP.NET Core heeft veel ingebouwde metrische gegevens. De http.server.request.duration metrische waarde:

• Registreert de duur van HTTP-aanvragen op de server.
• Legt aanvraaggegevens vast in tags, zoals de overeenkomende route- en antwoordstatuscode.

De http.server.request.duration metrische waarde biedt ondersteuning voor tagverrijking met behulp van IHttpMetricsTagsFeature. Verrijking is wanneer een bibliotheek of app zijn eigen tags toevoegt aan een metrische waarde. Deze functie is handig als een app een aangepaste categorisatie wil toevoegen aan dashboards of waarschuwingen die zijn gebouwd met metrische gegevens.

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

Het voorgaande voorbeeld:

• Hiermee voegt u middleware toe om de metrische gegevens van de ASP.NET Core-aanvraag te verrijken.
• Haalt de IHttpMetricsTagsFeature van de HttpContext. De functie is alleen aanwezig in de context als iemand naar de metrische gegevens luistert. Controleer IHttpMetricsTagsFeature of het niet null is voordat u deze gebruikt.
• Hiermee voegt u een aangepaste tag toe die de marketingbron van de aanvraag bevat aan de http.server.request.duration metrische waarde.
  • De tag heeft de naam mkt_medium en een waarde op basis van de utm_medium querytekenreekswaarde. De utm_medium waarde wordt omgezet in een bekend bereik met waarden.
  • Met de tag kunnen aanvragen worden gecategoriseerd op marketingmediumtype, wat nuttig kan zijn bij het analyseren van web-app-verkeer.

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

Aangepaste meetwaarden maken

U maakt metrische gegevens met behulp van API's in de System.Diagnostics.Metrics naamruimte. Zie Aangepaste metrische gegevens maken voor meer informatie.

Metrische gegevens maken in ASP.NET Core-apps met IMeterFactory

Maak Meter-instanties in ASP.NET Core-apps met IMeterFactory.

ASP.NET Core registreert standaard IMeterFactory in afhankelijkheidsinjectie (DI). De meterfactory integreert metrische gegevens met DI, waardoor het isoleren en verzamelen van metrische gegevens eenvoudig is. IMeterFactory is vooral nuttig voor het testen. Hiermee kunnen meerdere tests naast elkaar worden uitgevoerd en worden alleen metrische waarden verzameld die zijn vastgelegd in een test.

Om IMeterFactory in een app te gebruiken, maakt u een type dat IMeterFactory gebruikt om de aangepaste metrische gegevens van de app te maken.

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

Registreer het type metrische gegevens bij DI in Program.cs:

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

Injecteer waar nodig het type metrische gegevens en recordwaarden. Omdat het type metrische gegevens is geregistreerd in DI, kan het worden gebruikt met MVC-controllers, minimale API's of een ander type dat door DI wordt gemaakt:

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

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

Als u de meter Contoso.Web wilt bewaken, gebruikt u de volgende opdracht dotnet-counters .

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

Uitvoer die lijkt op het volgende wordt weergegeven:

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    

Metrische gegevens weergeven in Grafana met OpenTelemetry en Prometheus

Overview

OpenTelemetry:

• Is een leverancierneutraal opensource-project dat wordt ondersteund door de Cloud Native Computing Foundation.
• Standaardiseert het genereren en verzamelen van telemetrie voor cloudeigen software.
• Werkt met .NET met behulp van de metrische .NET-API's.
• Wordt goedgekeurd door Azure Monitor en veel APM-leveranciers.

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

In deze zelfstudie ziet u een van de integraties die beschikbaar zijn voor metrische gegevens van OpenTelemetry met behulp van de OSS Prometheus - en Grafana-projecten . De metrische gegevensstroom:

1. De ASP.NET Core-API's voor metrische API's registreren metingen uit de voorbeeld-app.

2. De OpenTelemetry .NET-bibliotheek die in de app wordt uitgevoerd, voegt de metingen samen.

3. De Prometheus-exportbibliotheek maakt de geaggregeerde gegevens beschikbaar via een eindpunt voor metrische HTTP-gegevens. 'Exporteur' is wat OpenTelemetry de bibliotheken aanroept die telemetrie verzenden naar leverancierspecifieke back-ends.

4. Een Prometheus-server:

   • Peilt het eindpunt voor metrische gegevens.
   • Leest de gegevens.
   • Slaat de gegevens op in een database voor persistentie op lange termijn. Prometheus verwijst naar het lezen en opslaan van gegevens als het scrapen van een eindpunt.
   • Kan worden uitgevoerd op een andere computer.

5. De Grafana-server:

   • Query's uitvoeren op de gegevens die zijn opgeslagen in Prometheus en deze weergeven op een bewakingsdashboard op internet.
   • Kan worden uitgevoerd op een andere computer.

Metrische gegevens weergeven vanuit voorbeeld-app

Ga naar de voorbeeld-app. De browser toont Hello OpenTelemetry! ticks:<3digits>, waarbij 3digits de laatste drie cijfers zijn van de huidige DateTime.Ticks.

Voeg toe /metrics aan de URL om het eindpunt voor metrische gegevens weer te geven. In de browser worden de verzamelde metrische gegevens weergegeven:

Prometheus instellen en configureren

Volg de eerste stappen van Prometheus om een Prometheus-server in te stellen en te bevestigen dat deze werkt.

Wijzig het prometheus.yml configuratiebestand zodat Prometheus het eindpunt voor metrische gegevens verwijdert dat de voorbeeld-app beschikbaar maakt. Voeg de volgende gemarkeerde tekst toe in de scrape_configs sectie:

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

Vervang 5045 in de hierboven gemarkeerde YAML door het poortnummer dat door de voorbeeldtoepassing wordt gebruikt.

Prometheus starten

1. Laad de configuratie opnieuw of start de Prometheus-server opnieuw op.
2. Controleer of OpenTelemetryTest de UP-status heeft op de pagina Statusdoelen> van de Prometheus-webportal.

Selecteer het pictogram Metrische verkenner openen om beschikbare metrische gegevens weer te geven:

Voer een itemcategorie in, zoals http_ in het invoervak Expressie om de beschikbare metrische gegevens weer te geven:

U kunt ook een tellercategorie invoeren, zoals kestrel in het invoervak Expressie , om de beschikbare metrische gegevens weer te geven:

Metrische gegevens weergeven op een Grafana-dashboard

• Volg de installatie-instructies om Grafana te installeren en deze te verbinden met een Prometheus-gegevensbron.

• Volg Het maken van een Prometheus-grafiek. U kunt ook vooraf gebouwde dashboards voor .NET-metrische gegevens downloaden op .NET-teamdashboards @ grafana.com. Gedownloade dashboard-JSON kan worden geïmporteerd in Grafana.

Metrische gegevens testen in ASP.NET Core-apps

U kunt metrische gegevens testen in ASP.NET Core apps. Een manier om dit te doen, is door metrische waarden te verzamelen en te bevestigen in ASP.NET Core integratietests met behulp van 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"]);
            });
    }
}

De voorgaande test:

• Initialiseert een webapplicatie in het geheugen met WebApplicationFactory<TEntryPoint>. Program in het algemene argument van de factory geeft u de web-app op.
• Verzamelt metrische waarden met MetricCollector<T>
  • Vereist een pakketreferentie naar Microsoft.Extensions.Diagnostics.Testing.
  • De MetricCollector<T> wordt gemaakt met behulp van de IMeterFactory van de webapplicatie. Hierdoor kan de collector alleen metrische gegevens rapporteren die zijn vastgelegd door de test.
  • Bevat de meternaam, Microsoft.AspNetCore.Hosting, en de naam van de teller, http.server.request.duration om te verzamelen.
• Hiermee wordt een HTTP-aanvraag naar de web-app verzonden.
• Valideert de test met behulp van de resultaten van de metriekverzamelaar.

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

ASP.NET Kernmeters en tellers

Zie ASP.NET Core-metriek voor een lijst van ASP.NET Core-meters en -tellers. In ASP.NET Core 11 en hoger verzenden de ingebouwde HTTP-servermeters (bijvoorbeeld Microsoft.AspNetCore.Hosting en Microsoft.AspNetCore.Server.Kestrel) gegevens die voldoen aan de vereiste onderdelen van de semantische http-serverconventies van OpenTelemetry. U kunt deze meters gebruiken met de OpenTelemetry SDK zonder het OpenTelemetry.Instrumentation.AspNetCore pakket.