Métriques ASP.NET Core

Les métriques sont des mesures numériques signalées au fil du temps. Utilisez-les pour surveiller l’intégrité d’une application et générer des alertes. Par exemple, un service web peut suivre le nombre de :

• Requêtes reçues par seconde.
• Millisecondes nécessaires pour répondre.
• Réponses qu’il envoie par erreur.

Signalez ces métriques à un système de surveillance à intervalles réguliers. Configurez des tableaux de bord pour afficher les métriques et créer des alertes pour avertir les personnes des problèmes. Si le service web est prévu pour répondre aux requêtes dans un délai de 400 ms et commence à répondre en 600 ms, le système de surveillance peut informer le personnel chargé des opérations que la réponse de l’application est plus lente que prévu.

La liste complète de tous les instruments avec leurs attributs est décrite dans ASP.NET Core métriques intégrées.

Utiliser les mesures

L’utilisation de métriques implique les éléments suivants :

• Instrumentation : le code des bibliothèques .NET prend des mesures et les associe à un nom de métrique. .NET et ASP.NET Core comptent de nombreuses métriques intégrées.
• Regroupement et stockage : Une application .NET configure les métriques nommées à transmettre à partir de l’application pour le stockage et l’analyse externes. Certains outils peuvent effectuer une configuration en dehors de l’application à l’aide de fichiers de configuration ou d’un outil d’interface utilisateur.
• Visualisation: Outil qui peut afficher les métriques dans un format lisible par l’homme. Par exemple, Grafana et Prometheus.
• Alerte: Outil qui fournit des notifications lorsqu’une métrique dépasse un seuil. Par exemple, si le temps de réponse moyen d’un service web dépasse 400 ms, une alerte peut être envoyée au personnel des opérations.
• Analyse: Outil qui peut analyser les métriques au fil du temps. Cet outil est souvent un tableau de bord web qui peut être personnalisé pour afficher les métriques les plus importantes pour une application spécifique.

Le code instrumenté peut enregistrer des mesures numériques, mais pour créer des métriques utiles pour la surveillance, vous devez agréger, transmettre et stocker les mesures. Le processus d’agrégation, de transmission et de stockage des données est appelé collecte. Ce tutoriel présente plusieurs exemples de collecte et d’affichage des métriques :

• Remplissage des métriques dans Grafana avec OpenTelemetry et Prometheus.
• Affichage des métriques en temps réel avec dotnet-counters

Vous pouvez également associer des mesures à des paires clé-valeur appelées balises qui vous permettent de classer les données à des fins d’analyse. Pour plus d’informations, consultez la section Métriques multidimensionnelles.

Créer l’application de démarrage

Créez une application ASP.NET Core avec la commande suivante :

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

Remplacez le contenu de Program.cs par le code suivant :

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

Afficher les métriques avec dotnet-counters

dotnet-counters est un outil en ligne de commande qui peut afficher les métriques actives pour les applications .NET à la demande. Il ne nécessite pas d’installation, ce qui le rend utile pour les enquêtes ad hoc ou pour vérifier que l’instrumentation des métriques fonctionne. Il fonctionne avec les API basées sur System.Diagnostics.Metrics et sur les EventCounters.

Si l’outil dotnet-counters n’est pas installé, exécutez la commande suivante :

dotnet tool update -g dotnet-counters

Pendant l’exécution de l’application test, lancez dotnet-counters. La commande suivante affiche un exemple de dotnet-counters surveillance de toutes les métriques du Microsoft.AspNetCore.Hosting compteur.

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

Une sortie similaire à la suivante s’affiche à l’écran :

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

Pour plus d’informations, consultez dotnet-counters.

Enrichir la métrique des requêtes ASP.NET Core

ASP.NET Core possède de nombreux indicateurs de performance intégrés. L’indicateur de performance http.server.request.duration :

• Enregistre la durée des requêtes HTTP sur le serveur.
• Capture les informations de requête dans des balises, telles que l’itinéraire correspondant et le code d’état de la réponse.

La métrique http.server.request.duration prend en charge l’enrichissement des balises en utilisant IHttpMetricsTagsFeature. L'enrichissement se produit lorsqu'une bibliothèque ou une application ajoute ses propres balises à un indicateur de performance. Cette fonctionnalité est utile si une application souhaite ajouter une catégorisation personnalisée aux tableaux de bord ou alertes créés avec des métriques.

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

L’exemple précédent :

• Ajoute un composant middleware pour enrichir la métrique de requête ASP.NET Core.
• Récupère la IHttpMetricsTagsFeature à partir de la HttpContext. La fonctionnalité n’est présente dans le contexte que si quelqu’un surveille la métrique. Vérifiez que IHttpMetricsTagsFeature n’est pas null avant de l’utiliser.
• Ajoute une balise personnalisée contenant la source marketing de la requête à l’indicateur de performance http.server.request.duration.
  • La balise a un nom mkt_medium et une valeur basés sur la valeur de la chaîne de requête utm_medium. La valeur utm_medium est résolue selon une plage de valeurs connue.
  • La balise permet de classer les demandes par type de support marketing, ce qui peut être utile lors de l'analyse du trafic des applications Web.

Remarque

Suivez les bonnes pratiques en matière des indicateurs de performance multidimensionnelles lors de l'enrichissement avec des balises personnalisées. Les balises trop nombreuses ou ayant une plage non bornée créent de nombreuses combinaisons de balises, ce qui entraîne une forte dimensionalité. Les outils de collection ont des limites sur les dimensions prises en charge pour un compteur et peuvent filtrer les résultats pour empêcher une utilisation excessive de la mémoire.

Désactiver les métriques HTTP sur certains points de terminaison et requêtes

La désactivation de l'enregistrement des métriques est bénéfique pour les points de terminaison fréquemment appelés par des systèmes automatisés, tels que les contrôles d’intégrité. L’enregistrement des métriques pour ces requêtes est généralement inutile. Les données de télémétrie indésirables utilisent des ressources pour collecter et stocker, et peuvent fausser les résultats affichés dans un tableau de bord de télémétrie.

Vous pouvez exclure les requêtes HTTP vers un point de terminaison des métriques en ajoutant des métadonnées, avec l’attribut DisableHttpMetrics ou la méthode DisableHttpMetrics :

• Ajoutez l’attribut DisableHttpMetrics au contrôleur d’API Web, au hub SignalR, ou au service gRPC.
• Appelez DisableHttpMetrics lors du mappage des points de terminaison au démarrage de l’application :

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

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

Vous pouvez également ajouter la IHttpMetricsTagsFeature.MetricsDisabled propriété pour :

• Les scénarios avancés où une requête ne correspond pas à un point de terminaison.
• La désactivation dynamique de la collecte de métriques pour des requêtes HTTP spécifiques

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

Créer des métriques personnalisées

Vous créez des métriques à l’aide des API dans l’espace de noms System.Diagnostics.Metrics. Pour plus d’informations, consultez Créer des métriques personnalisées.

Création d’indicateurs de performance dans les applications ASP.NET Core avec IMeterFactory

Créez des Meter instances dans ASP.NET Core applications avec IMeterFactory.

ASP.NET Core enregistre IMeterFactory par défaut dans le conteneur d’injection de dépendances (DI). L'usine de compteurs intègre les indicateurs de performance à DI, ce qui facilite l'isolement et la collecte des métriques. IMeterFactory est particulièrement utile pour les tests. Il permet à plusieurs tests d’exécuter côte à côte et collecte uniquement les valeurs de métriques enregistrées dans un test.

Pour utiliser IMeterFactory dans une application, créez un type qui servira IMeterFactory à créer les métriques personnalisées de l'application :

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

Enregistrez le type d’indicateur de performance avec DI dans Program.cs :

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

Injectez le type d’indicateur de performance et enregistrez les valeurs si nécessaire. Étant donné que le type de métriques est inscrit dans DI, il peut être utilisé avec des contrôleurs MVC, des API minimales ou tout autre type créé par 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);
});

Pour surveiller le compteur « Contoso.Web », utilisez la commande dotnet-counters suivante.

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

Une sortie similaire à la suivante s’affiche à l’écran :

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    

Afficher les métriques dans Grafana avec OpenTelemetry et Prometheus

Overview

OpenTelemetry:

• Il s’agit d’un projet open source indépendant du fournisseur soutenu par la Cloud Native Computing Foundation.
• Normalise la génération et la collecte de données de télémétrie pour les logiciels natifs cloud.
• Fonctionne avec .NET à l’aide des API de métrique .NET.
• Est approuvé par Azure Monitor et de nombreux fournisseurs APM.

Ce tutoriel montre l’une des intégrations disponibles pour les métriques OpenTelemetry à l’aide des projets OSS Prometheus et Grafana. Flux de données des métriques :

1. Les API de métrique ASP.NET Core enregistrent les mesures de l’exemple d’application.

2. La bibliothèque OpenTelemetry .NET en cours d’exécution dans l’application agrège les mesures.

3. La bibliothèque d’exportation Prometheus rend les données agrégées disponibles via un point de terminaison de métriques HTTP. « Exporter » est le nom donné par OpenTelemetry aux bibliothèques qui transmettent les données de télémétrie aux back-ends spécifiques au fournisseur.

4. Un serveur Prometheus :

   • Interroge le point de terminaison des métriques.
   • Lit les données.
   • Stocke les données dans une base de données pour une persistance à long terme. Prometheus désigne la lecture et le stockage de données comme le scraping d'un point de terminaison.
   • Peut s’exécuter sur un autre ordinateur.

5. Le serveur Grafana :

   • Interroge les données stockées dans Prometheus et les affiche sur un tableau de bord de surveillance web.
   • Peut s’exécuter sur un autre ordinateur.

Afficher les métriques de l’exemple d’application

Accédez à l’exemple d’application. Le navigateur indique Hello OpenTelemetry! ticks:<3digits> où 3digits sont les trois derniers chiffres du dateTime.Ticks actuel.

Ajoutez /metrics à l’URL pour afficher le point de terminaison des métriques. Le navigateur affiche les métriques en cours de collection :

Installer et configurer Prometheus

Suivez les Premières étapes de Prometheus pour configurer un serveur Prometheus et vérifier qu’il fonctionne.

Modifiez le fichier de configuration prometheus.yml afin que Prometheus supprime le point de terminaison de métriques exposé par l’exemple d’application. Ajoutez le texte en surbrillance suivant dans la section 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.

Dans le yaML mis en surbrillance précédent, remplacez 5045 par le numéro de port utilisé par l’exemple d’application.

Démarrer Prometheus

1. Rechargez la configuration ou redémarrez le serveur Prometheus.
2. Vérifiez qu’OpenTelemetryTest est dans l’état UP sur la page État>Cibles du portail web Prometheus.

Sélectionnez l’icône Ouvrir l’explorateur de métriques pour afficher les métriques disponibles :

Entrez une catégorie de compteurs comme http_ dans la zone d’entrée Expression pour afficher les métriques disponibles :

Vous pouvez également entrer une catégorie de compteurs comme kestrel dans la zone d’entrée Expression pour afficher les métriques disponibles :

Afficher les métriques sur un tableau de bord Grafana

• Suivez les instructions d’installation pour installer Grafana et la connecter à une source de données Prometheus.

• Suivez la Création d’un graphique Prometheus. Vous pouvez également télécharger des tableaux de bord prédéfinis pour les métriques .NET sur les tableaux de bord d’équipe .NET @ grafana.com. Le fichier JSON de tableau de bord téléchargé peut être importé dans Grafana.

Métriques de test dans des applications ASP.NET Core

Vous pouvez tester les métriques dans les applications ASP.NET Core. Une façon de procéder consiste à collecter et à vérifier des valeurs de métriques dans les tests d’intégration ASP.NET Core à l’aide de 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"]);
            });
    }
}

Le test précédent :

• Démarre une application web en mémoire avec WebApplicationFactory<TEntryPoint>. Dans l’argument générique de la fabrique, Program spécifie l’application web.
• Collecte des valeurs de métriques avec MetricCollector<T>
  • Nécessite une référence de package à Microsoft.Extensions.Diagnostics.Testing.
  • Le fichier MetricCollector<T> est créé à l’aide du IMeterFactory de l’application web. Cela permet au collecteur de ne signaler que des valeurs de métriques enregistrées par le test.
  • Comprend le nom de la mesure, Microsoft.AspNetCore.Hosting, et le nom du compteur, http.server.request.duration, à collecter.
• Effectue une requête HTTP vers l’application web.
• Affirme le test à l’aide des résultats du collecteur de métriques.

Métriques ASP.NET Core Identity

L’observabilité d’ASP.NET Core Identity vous aide à surveiller les activités de gestion des utilisateurs et les processus d’authentification.

Les métriques se trouvent dans le Microsoft.AspNetCore.Identity compteur et sont décrites dans les sections suivantes.

Métriques de gestion des utilisateurs

• aspnetcore.identity.user.create.duration mesure la durée des opérations de création de l’utilisateur.
• aspnetcore.identity.user.update.duration mesure la durée des opérations de mise à jour utilisateur.
• aspnetcore.identity.user.delete.duration mesure la durée des opérations de suppression de l’utilisateur.
• aspnetcore.identity.user.check_password_attempts compte les tentatives de vérification de mot de passe.
• aspnetcore.identity.user.generated_tokens compte les jetons générés pour les utilisateurs, tels que les jetons de réinitialisation de mot de passe.
• aspnetcore.identity.user.verify_token_attempts compte les tentatives de vérification de jeton.

Métriques d’authentification

• aspnetcore.identity.sign_in.authenticate.duration mesure la durée des opérations d’authentification.
• aspnetcore.identity.sign_in.check_password_attempts compte les tentatives de vérification de mot de passe lors de la connexion.
• aspnetcore.identity.sign_in.sign_ins compte les connexions réussies.
• aspnetcore.identity.sign_in.sign_outs compte les déconnexions.
• aspnetcore.identity.sign_in.two_factor_clients_remembered compte le nombre de clients avec authentification à deux facteurs mémorisés.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten compte les clients à authentification à deux facteurs oubliés.

Utilisez ces métriques pour :

• Surveillez l’inscription et la gestion des utilisateurs.
• Suivez les modèles d’authentification et les problèmes de sécurité potentiels.
• Mesurez les performances des Identity opérations.
• Observez l’utilisation de l’authentification à deux facteurs.

Affichage des Identity métriques

Permet dotnet-counters d’afficher ces métriques et de les surveiller en temps réel. Vous pouvez également les exporter vers Prometheus et les visualiser dans Grafana à l’aide des techniques décrites précédemment dans cet article.

Par exemple, pour surveiller toutes les Identity métriques avec dotnet-counters:

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

Métriques et compteurs ASP.NET Core

Pour obtenir une liste des indicateurs et compteurs ASP.NET Core, consultez les métriques d’ASP.NET Core. Dans ASP.NET Core 11 et versions ultérieures, les compteurs de serveur HTTP intégrés (par exempleMicrosoft.AspNetCore.Hosting, et Microsoft.AspNetCore.Server.Kestrel) émettent des données conformes aux parties requises des conventions sémantiques du serveur HTTP OpenTelemetry. Vous pouvez consommer ces compteurs avec le SDK OpenTelemetry sans le package OpenTelemetry.Instrumentation.AspNetCore.