ASP.NET Core-metrik

Mått är numeriska mått som rapporteras över tid. De används vanligtvis för att övervaka hälsotillståndet för en app och generera aviseringar. En webbtjänst kan till exempel spåra hur många:

• Begäranden som tas emot per sekund.
• Millisekunder som krävdes för att svara.
• Ett fel inträffade vid skickandet av svaren.

Dessa mått kan rapporteras till ett övervakningssystem med jämna mellanrum. Instrumentpaneler kan konfigureras för att visa mått och aviseringar som skapats för att meddela personer om problem. Om webbtjänsten är avsedd att svara på begäranden inom 400 ms och börjar svara inom 600 ms kan övervakningssystemet meddela driftteamet att applikationssvaret är långsammare än normalt.

Se ASP.NET Core-mått för en omfattande lista över alla instrument tillsammans med deras attribut.

Use metrics

Användning av mått omfattar följande:

• Instrumentation: Kod i .NET-bibliotek tar mätningar och kopplar dessa mätningar till ett mätvärdesnamn. .NET och ASP.NET Core innehåller många inbyggda mått.
• Insamling och lagring: En .NET-app konfigurerar namngivna mått som ska överföras från appen för extern lagring och analys. Vissa verktyg kan utföra konfiguration utanför appen med hjälp av konfigurationsfiler eller ett gränssnittsverktyg.
• Visualisering: Ett verktyg som kan visa måtten i ett läsbart format för människor. Till exempel Grafana och Prometheus.
• Varningar: Ett verktyg som ger notifikationer när ett mått överskrider ett tröskelvärde. Om den genomsnittliga svarstiden för en webbtjänst till exempel överskrider 400 ms kan en avisering skickas till driftpersonalen.
• Analys: Ett verktyg som kan analysera måtten över tid. Det här är ofta en webbaserad instrumentpanel som kan anpassas för att visa de viktigaste måtten för en specifik app.

Instrumenterad kod kan registrera numeriska mått, men måtten måste aggregeras, överföras och lagras för att skapa användbara mått för övervakning. Processen för att aggregera, överföra och lagra data kallas insamling. Den här självstudien visar flera exempel på hur du samlar in och visar mått:

• Fylla i mått i Grafana med OpenTelemetry och Prometheus.
• Visa mått i realtid med dotnet-counters

Mått kan också associeras med nyckel/värde-par som kallas taggar som gör att data kan kategoriseras för analys. Mer information finns i Flerdimensionella mått.

Skapa startappen

Skapa en ny ASP.NET Core-app med följande kommando:

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

Ersätt innehållet i Program.cs med följande kod:

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

Visa mätvärden med dotnet-counters

dotnet-counters är ett kommandoradsverktyg som kan visa livemått för .NET-appar på begäran. Det kräver inte konfiguration, vilket gör det användbart för ad hoc-undersökningar eller för att verifiera att måttinstrumentation fungerar. Den fungerar med både System.Diagnostics.Metrics baserade API:er och EventCounters.

Om verktyget dotnet-counters inte är installerat kör du följande kommando:

dotnet tool update -g dotnet-counters

När testappen körs startar du dotnet-counters. Följande kommando visar ett exempel på övervakning av dotnet-counters alla mått från mätarenMicrosoft.AspNetCore.Hosting.

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

Utdata som liknar följande visas:

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

Mer information finns i dotnet-counters.

Utöka måttet för ASP.NET Core-begäran

ASP.NET Core har många inbyggda mått. Måttet http.server.request.duration :

• Registrerar varaktigheten för HTTP-begäranden på servern.
• Samlar in information om begäranden i taggar, till exempel den matchade vägen och svarsstatuskoden.

Måttet http.server.request.duration stöder taggberikning med hjälp av IHttpMetricsTagsFeature. Berikning är när ett bibliotek eller en app lägger till egna taggar i ett mått. Detta är användbart om en app vill lägga till en anpassad kategorisering till instrumentpaneler eller aviseringar som byggs på 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();

Följande exempel:

• Lägger till middleware för att berika ASP.NET Core-förfrågningsmätning.
• Hämtar IHttpMetricsTagsFeature från HttpContext. Funktionen finns bara i sammanhanget om någon övervakar måttet. Kontrollera att IHttpMetricsTagsFeature inte är null innan du använder det.
• Lägger till en anpassad tagg som innehåller förfrågans marknadsföringskälla till http.server.request.duration-måttet.
  • Taggen har namnet mkt_medium och ett värde baserat på utm_medium frågesträngsvärdet. Värdet utm_medium tilldelas ett känt intervall av värden.
  • Taggen tillåter att begäranden kategoriseras efter marknadsföringsmediumtyp, vilket kan vara användbart när du analyserar webbappstrafik.

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

Skapa anpassade mått

Mått skapas med hjälp av API:er inom System.Diagnostics.Metrics-namnområdet. Mer information om hur du skapar anpassade mått finns i Skapa anpassade mått .

Skapa mått i ASP.NET Core-appar med IMeterFactory

Vi rekommenderar att du skapar Meter instanser i ASP.NET Core-appar med IMeterFactory.

ASP.NET Core registrerar IMeterFactory i beroendeinjektionen (DI) som standard. Mätvärdesfabriken integrerar mätvärden med DI, vilket gör det enkelt att isolera och samla in mätvärden. IMeterFactory är särskilt användbart för testning. Det gör att flera tester kan köras sida vid sida och endast samla in måttvärden som registreras i ett test.

Om du vill använda IMeterFactory i en app skapar du en typ som använder IMeterFactory för att skapa appens anpassade mått:

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

Registrera måtttypen med DI i Program.cs:

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

Mata in måttyp och registrera värden där det behövs. Eftersom måtttypen är registrerad i DI kan den användas med MVC-styrenheter, minimala API:er eller någon annan typ som skapas av 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);
});

Om du vill övervaka mätaren "Contoso.Web" använder du följande dotnet-counters-kommando .

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

Utdata som liknar följande visas:

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    

Visa mått i Grafana med OpenTelemetry och Prometheus

Overview

OpenTelemetry:

• Är ett leverantörsneutralt projekt med öppen källkod som stöds av Cloud Native Computing Foundation.
• Standardiserar generering och insamling av telemetri för molnbaserad programvara.
• Fungerar med .NET genom att använda .NET-mått-API.
• Stöds av Azure Monitor och många APM-leverantörer.

Den här handledningen visar en av de integreringar som är tillgängliga för OpenTelemetry-metrik med hjälp av OSS-projekten Prometheus och Grafana. Dataflödet för mått:

1. API:erna för ASP.NET Core-mått registrerar mått från exempelappen.

2. OpenTelemetry .NET-biblioteket som körs i appen aggregerar måtten.

3. Prometheus-exporteringsbiblioteket gör aggregerade data tillgängliga via en HTTP-måttslutpunkt. "Exporter" är vad OpenTelemetry kallar biblioteken som överför telemetri till leverantörsspecifika bakändsystem.

4. En Prometheusserver:

   • Förfrågar metrikslutpunkten
   • Läser datan
   • Lagrar data i en databas för långsiktig beständighet. Prometheus refererar till att läsa och lagra data som att skrapa en slutpunkt.
   • Kan köras på en annan dator

5. Grafana-servern:

   • Frågar data som lagras i Prometheus och visar det på ett webbaserat övervakningsgränssnitt.
   • Kan köras på en annan dator.

Visa mått från exempelappen

Gå till exempelappen. Webbläsaren visar Hello OpenTelemetry! ticks:<3digits> var 3digits är de tre sista siffrorna i aktuella DateTime.Ticks.

/metrics Lägg till i URL:en för att visa måttslutpunkten. Webbläsaren visar de mått som samlas in:

Ställ in och konfigurera Prometheus

Följ de första stegen i Prometheus för att konfigurera en Prometheus-server och bekräfta att den fungerar.

Ändra prometheus.yml konfigurationsfilen så att Prometheus skrapar måttslutpunkten som exempelappen exponerar. Lägg till följande markerade text i avsnittet 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.

I föregående markerade YAML ersätter du 5045 med portnumret som exempelappen körs på.

Start Prometheus

1. Ladda om konfigurationen eller starta om Prometheus-servern.
2. Bekräfta att OpenTelemetryTest är i UP-tillståndet på sidan Statusmål> i Prometheus-webbportalen.

Välj ikonen Öppna måttutforskaren för att se tillgängliga mått:

Ange räknarkategori, till exempel http_ i indatarutan Uttryck för att se tillgängliga mått:

Du kan också ange räknarkategori, till exempel kestrel i rutan Uttrycksindata för att se tillgängliga mått:

Visa mått på en Grafana-instrumentpanel

• Följ installationsanvisningarna för att installera Grafana och ansluta den till en Prometheus-datakälla.

• Följ Skapa en Prometheus-graf. Du kan också ladda ned fördefinierade instrumentpaneler för .NET-mått på .NET-teamets instrumentpaneler @ grafana.com. JSON för nedladdad instrumentpanel kan importeras till Grafana.

Testa mått i ASP.NET Core-appar

Du kan testa mått i ASP.NET Core-appar. Ett sätt att göra det är att samla in och kontrollera måttvärden i ASP.NET Core-integreringstester med hjälp av 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"]);
            });
    }
}

Följande test:

• Bootstraps en webbapp i minnet med WebApplicationFactory<TEntryPoint>. Program i den generiska argumenten för fabriken specificerar webbappen.
• Samlar in måttvärden med MetricCollector<T>
  • Kräver en paketreferens till Microsoft.Extensions.Diagnostics.Testing
  • MetricCollector<T> skapas med webbappens IMeterFactory. På så sätt kan insamlaren endast rapportera måttvärden som registrerats av tester.
  • Innehåller mätarnamnet, Microsoft.AspNetCore.Hosting, och räknarnamnet, som ska samlas in, http.server.request.duration.
• Gör en HTTP-begäran till webbappen.
• Bekräftar testet med hjälp av resultat från måttinsamlaren.

ASP.NET Core-mätare och räknare

Se ASP.NET Core-mått för en lista över ASP.NET Core-mätare och räknare.