Examiner les compteurs de performances (dotnet-counters)

  • Article

Cet article s’applique à : ✔️ dotnet-counters version 3.0.47001 et versions ultérieures.

Les compteurs peuvent être lus à partir d’applications exécutant .NET 5 ou version ultérieure.

Installer

Il existe deux façons de télécharger et d’installer dotnet-counters :

  • outil global dotnet :

    Pour installer la dernière version de version du dotnet-counters package NuGet, utilisez la commande d’installation de l’outil dotnet :

    dotnet tool install --global dotnet-counters

  • Téléchargement direct :

    Téléchargez l’exécutable de l’outil qui correspond à votre plateforme :

    Système d''exploitation Plateforme
    Windows x86 | x64 | Arm | Arm-x64
    Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64

Notes

Pour utiliser dotnet-counters sur une application x86, vous avez besoin d’une version x86 correspondante de l’outil.

Synopsis

dotnet-counters [-h|--help] [--version] <command>

Description

dotnet-counters est un outil de surveillance des performances pour l’analyse ad hoc de l’intégrité et l’examen des performances de premier niveau. Il peut observer les valeurs de compteur de performances publiées via l’API EventCounter ou l’API Meter. Par exemple, vous pouvez surveiller rapidement des éléments tels que l’utilisation du processeur ou le taux d’exceptions levées dans votre application .NET Core pour voir s’il y a quelque chose de suspect avant de plonger dans une enquête plus sérieuse sur les performances à l’aide PerfView ou dotnet-trace.

Options

  • --version

    Affiche la version de l’utilitaire dotnet-counters.

  • -h|--help

    Affiche l’aide en ligne de commande.

Commandes

Commande
dotnet-counters collect
dotnet-counters list
dotnet-counters monitor
dotnet-counters ps

dotnet-counters collect

Collectez régulièrement les valeurs de compteur sélectionnées et exportez-les dans un format de fichier spécifié pour le post-traitement.

Synopsis

dotnet-counters collect [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-port] [--refresh-interval] [--counters <COUNTERS>] [--format] [-o|--output] [-- <command>]

Options

  • -p|--process-id <PID>

    Identifiant du processus à partir duquel collecter des données de compteur.

  • -n|--name <name>

    Nom du processus à partir duquel collecter des données de compteur.

  • --diagnostic-port

    Nom du port de diagnostic à créer. Consultez Utilisation du port de diagnostic pour savoir comment utiliser cette option pour démarrer la surveillance des compteurs à partir du démarrage de l’application.

  • --refresh-interval <SECONDS>

    Nombre de secondes à retarder entre la mise à jour des compteurs affichés

  • --counters <COUNTERS>

    Liste de compteurs séparés par des virgules. Les compteurs peuvent être spécifiés provider_name[:counter_name]. Si provider_name est utilisé sans liste éligible de compteurs, tous les compteurs du fournisseur sont affichés. Pour découvrir les noms de fournisseurs et de compteurs, utilisez la commande dotnet-counters list . Pour EventCounters, provider_name est le nom de l’EventSource. provider_name est le nom du compteur pour Meters.

  • --format <csv|json>

    Format à exporter. Actuellement disponible : csv, json.

  • -o|--output <output>

    Le nom du fichier de sortie.

  • -- <command>

    Après les paramètres de configuration de collection, l’utilisateur peut ajouter -- une commande pour démarrer une application .NET. dotnet-counters lance un processus avec la commande fournie et collecte les métriques demandées. Cela peut être utile pour collecter des métriques pour le chemin d’accès de démarrage de l’application et peut être utilisé pour diagnostiquer ou surveiller les problèmes qui se produisent avant ou peu après le point d’entrée principal.

    Remarque

    L’utilisation de cette option surveille le premier processus .NET qui communique à l’outil, ce qui signifie que si votre commande lance plusieurs applications .NET, elle collecte uniquement la première application. Par conséquent, il est recommandé d’utiliser cette option sur les applications autonomes ou d’utiliser l’option dotnet exec <app.dll>.

    Remarque

    Le lancement d’un exécutable .NET via dotnet-counters redirige ses entrées/sorties et vous ne pourrez pas interagir avec son stdin/stdout. La sortie de l’outil via CTRL+C ou SIGTERM met fin en toute sécurité à l’outil et au processus enfant. Si le processus enfant se termine avant l’outil, l’outil se ferme également. Si vous avez besoin d’utiliser stdin/stdout, vous pouvez utiliser l’option --diagnostic-port. Pour plus d’informations, consultez Utilisation du port de diagnostic.

Notes

Sous Linux et macOS, cette commande s’attend à ce que l’application cible et dotnet-counters partagent la même variable d’environnement TMPDIR. Dans le cas contraire, la commande expire.

Notes

Pour collecter des métriques en utilisant dotnet-counters, il faut l’exécuter en tant qu’utilisateur exécutant le processus cible ou en tant que racine. Sinon, l’outil ne parvient pas à établir une connexion avec le processus cible.

Exemples

  • Collectez tous les compteurs à un intervalle d’actualisation de 3 secondes et générez un csv en tant que sortie :

    > dotnet-counters collect --process-id 1902 --refresh-interval 3 --format csv

--counters is unspecified. Monitoring System.Runtime counters by default.
Starting a counter session. Press Q to quit.

  • Démarrez dotnet mvc.dll en tant que processus enfant et commencez à collecter des compteurs d’exécution et des compteurs hébergement ASP.NET Core à partir du démarrage et enregistrez-le en tant que sortie JSON :

    > dotnet-counters collect --format json --counters System.Runtime,Microsoft.AspNetCore.Hosting -- dotnet mvc.dll
Starting a counter session. Press Q to quit.
File saved to counter.json

dotnet-counters list

Affiche une liste de noms de compteurs et de descriptions, regroupées par fournisseur.

Synopsis

dotnet-counters list [-h|--help]

Exemple

> dotnet-counters list
Showing well-known counters only. Specific processes may support additional counters.

System.Runtime
    cpu-usage                                    Amount of time the process has utilized the CPU (ms)
    working-set                                  Amount of working set used by the process (MB)
    gc-heap-size                                 Total heap size reported by the GC (MB)
    gen-0-gc-count                               Number of Gen 0 GCs per interval
    gen-1-gc-count                               Number of Gen 1 GCs per interval
    gen-2-gc-count                               Number of Gen 2 GCs per interval
    time-in-gc                                   % time in GC since the last GC
    gen-0-size                                   Gen 0 Heap Size
    gen-1-size                                   Gen 1 Heap Size
    gen-2-size                                   Gen 2 Heap Size
    loh-size                                     LOH Heap Size
    alloc-rate                                   Allocation Rate
    assembly-count                               Number of Assemblies Loaded
    exception-count                              Number of Exceptions per interval
    threadpool-thread-count                      Number of ThreadPool Threads
    monitor-lock-contention-count                Monitor Lock Contention Count
    threadpool-queue-length                      ThreadPool Work Items Queue Length
    threadpool-completed-items-count             ThreadPool Completed Work Items Count
    active-timer-count                           Active Timers Count

Microsoft.AspNetCore.Hosting
    requests-per-second                  Request rate
    total-requests                       Total number of requests
    current-requests                     Current number of requests
    failed-requests                      Failed number of requests

Notes

Les compteurs Microsoft.AspNetCore.Hosting s’affichent lorsqu’il existe des processus identifiés qui prennent en charge ces compteurs, par exemple ; lorsqu’une application ASP.NET Core s’exécute sur l’ordinateur hôte.

dotnet-counters monitor

Affiche régulièrement les valeurs d’actualisation des compteurs sélectionnés.

Synopsis

dotnet-counters monitor [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-port] [--refresh-interval] [--counters] [-- <command>]

Options

  • -p|--process-id <PID>

    Identifiant du processus à surveiller.

  • -n|--name <name>

    Nom du processus à surveiller.

  • --diagnostic-port

    Nom du port de diagnostic à créer. Consultez Utilisation du port de diagnostic pour savoir comment utiliser cette option pour démarrer la surveillance des compteurs à partir du démarrage de l’application.

  • --refresh-interval <SECONDS>

    Nombre de secondes à retarder entre la mise à jour des compteurs affichés

  • --counters <COUNTERS>

    Liste de compteurs séparés par des virgules. Les compteurs peuvent être spécifiés provider_name[:counter_name]. Si provider_name est utilisé sans liste éligible de compteurs, tous les compteurs du fournisseur sont affichés. Pour découvrir les noms de fournisseurs et de compteurs, utilisez la commande dotnet-counters list . Pour EventCounters, provider_name est le nom de l’EventSource. provider_name est le nom du compteur pour Meters.

-- <command>

Après les paramètres de configuration de collection, l’utilisateur peut ajouter -- une commande pour démarrer une application .NET. dotnet-counters lance un processus avec la commande fournie et surveille les métriques demandées. Cela peut être utile pour collecter des métriques pour le chemin d’accès de démarrage de l’application et peut être utilisé pour diagnostiquer ou surveiller les problèmes qui se produisent avant ou peu après le point d’entrée principal.

Remarque

L’utilisation de cette option surveille le premier processus .NET qui communique à l’outil, ce qui signifie que si votre commande lance plusieurs applications .NET, elle collecte uniquement la première application. Par conséquent, il est recommandé d’utiliser cette option sur les applications autonomes ou d’utiliser l’option dotnet exec <app.dll>.

Remarque

Le lancement d’un exécutable .NET via dotnet-counters redirige ses entrées/sorties et vous ne pourrez pas interagir avec son stdin/stdout. La sortie de l’outil via CTRL+C ou SIGTERM met fin en toute sécurité à l’outil et au processus enfant. Si le processus enfant se termine avant l’outil, l’outil se ferme également. Si vous avez besoin d’utiliser stdin/stdout, vous pouvez utiliser l’option --diagnostic-port. Pour plus d’informations, consultez Utilisation du port de diagnostic.

Notes

Sur Linux et macOS, cette commande s’attend à ce que l’application cible et dotnet-counters partagent la même variable d’environnement TMPDIR.

Notes

Pour surveiller les métriques à l’aide de dotnet-counters, il faut l’exécuter en tant qu’utilisateur exécutant le processus cible ou en tant que racine.

Notes

Si vous voyez un message d’erreur similaire à celui-ci : [ERROR] System.ComponentModel.Win32Exception (299): A 32 bit processes cannot access modules of a 64 bit process., vous essayez d’utiliser dotnet-counters qui a une incompatibilité de bits par rapport au processus cible. Veillez à télécharger le nombre de bits correct de l’outil dans le lien d’installation.

Exemples

  • Surveillez tous les compteurs à partir de System.Runtime à un intervalle d’actualisation de 3 secondes :

    > dotnet-counters monitor --process-id 1902  --refresh-interval 3 --counters System.Runtime
Press p to pause, r to resume, q to quit.
    Status: Running

[System.Runtime]
    % Time in GC since last GC (%)                                 0
    Allocation Rate (B / 1 sec)                                5,376
    CPU Usage (%)                                                  0
    Exception Count (Count / 1 sec)                                0
    GC Fragmentation (%)                                          48.467
    GC Heap Size (MB)                                              0
    Gen 0 GC Count (Count / 1 sec)                                 1
    Gen 0 Size (B)                                                24
    Gen 1 GC Count (Count / 1 sec)                                 1
    Gen 1 Size (B)                                                24
    Gen 2 GC Count (Count / 1 sec)                                 1
    Gen 2 Size (B)                                           272,000
    IL Bytes Jitted (B)                                       19,449
    LOH Size (B)                                              19,640
    Monitor Lock Contention Count (Count / 1 sec)                  0
    Number of Active Timers                                        0
    Number of Assemblies Loaded                                    7
    Number of Methods Jitted                                     166
    POH (Pinned Object Heap) Size (B)                             24
    ThreadPool Completed Work Item Count (Count / 1 sec)           0
    ThreadPool Queue Length                                        0
    ThreadPool Thread Count                                        2
    Working Set (MB)                                              19

  • Surveillez simplement l’utilisation du processeur et la taille du tas GC à partir de System.Runtime :

    > dotnet-counters monitor --process-id 1902 --counters System.Runtime[cpu-usage,gc-heap-size]

Press p to pause, r to resume, q to quit.
  Status: Running

[System.Runtime]
    CPU Usage (%)                                 24
    GC Heap Size (MB)                            811

  • Surveillez les valeurs EventCounter des EventSource définis par l’utilisateur. Pour plus d’informations, consultez Tutoriel : Mesurer les performances à l’aide d’EventCounters dans .NET Core.

    > dotnet-counters monitor --process-id 1902 --counters Samples-EventCounterDemos-Minimal

Press p to pause, r to resume, q to quit.
    request                                      100

  • Affichez tous les compteurs connus disponibles dans dotnet-counters :

    > dotnet-counters list

Showing well-known counters for .NET (Core) version 3.1 only. Specific processes may support additional counters.
System.Runtime
    cpu-usage                          The percent of process' CPU usage relative to all of the system CPU resources [0-100]
    working-set                        Amount of working set used by the process (MB)
    gc-heap-size                       Total heap size reported by the GC (MB)
    gen-0-gc-count                     Number of Gen 0 GCs between update intervals
    gen-1-gc-count                     Number of Gen 1 GCs between update intervals
    gen-2-gc-count                     Number of Gen 2 GCs between update intervals
    time-in-gc                         % time in GC since the last GC
    gen-0-size                         Gen 0 Heap Size
    gen-1-size                         Gen 1 Heap Size
    gen-2-size                         Gen 2 Heap Size
    loh-size                           LOH Size
    alloc-rate                         Number of bytes allocated in the managed heap between update intervals
    assembly-count                     Number of Assemblies Loaded
    exception-count                    Number of Exceptions / sec
    threadpool-thread-count            Number of ThreadPool Threads
    monitor-lock-contention-count      Number of times there were contention when trying to take the monitor lock between update intervals
    threadpool-queue-length            ThreadPool Work Items Queue Length
    threadpool-completed-items-count   ThreadPool Completed Work Items Count
    active-timer-count                 Number of timers that are currently active

Microsoft.AspNetCore.Hosting
    requests-per-second                Number of requests between update intervals
    total-requests                     Total number of requests
    current-requests                   Current number of requests
    failed-requests                    Failed number of requests

  • Affichez tous les compteurs connus disponibles dans dotnet-counters pour les applications .NET 5 :

    > dotnet-counters list --runtime-version 5.0

Showing well-known counters for .NET (Core) version 5.0 only. Specific processes may support additional counters.
System.Runtime
    cpu-usage                          The percent of process' CPU usage relative to all of the system CPU resources [0-100]
    working-set                        Amount of working set used by the process (MB)
    gc-heap-size                       Total heap size reported by the GC (MB)
    gen-0-gc-count                     Number of Gen 0 GCs between update intervals
    gen-1-gc-count                     Number of Gen 1 GCs between update intervals
    gen-2-gc-count                     Number of Gen 2 GCs between update intervals
    time-in-gc                         % time in GC since the last GC
    gen-0-size                         Gen 0 Heap Size
    gen-1-size                         Gen 1 Heap Size
    gen-2-size                         Gen 2 Heap Size
    loh-size                           LOH Size
    poh-size                           POH (Pinned Object Heap) Size
    alloc-rate                         Number of bytes allocated in the managed heap between update intervals
    gc-fragmentation                   GC Heap Fragmentation
    assembly-count                     Number of Assemblies Loaded
    exception-count                    Number of Exceptions / sec
    threadpool-thread-count            Number of ThreadPool Threads
    monitor-lock-contention-count      Number of times there were contention when trying to take the monitor lock between update intervals
    threadpool-queue-length            ThreadPool Work Items Queue Length
    threadpool-completed-items-count   ThreadPool Completed Work Items Count
    active-timer-count                 Number of timers that are currently active
    il-bytes-jitted                    Total IL bytes jitted
    methods-jitted-count               Number of methods jitted

Microsoft.AspNetCore.Hosting
    requests-per-second   Number of requests between update intervals
    total-requests        Total number of requests
    current-requests      Current number of requests
    failed-requests       Failed number of requests

Microsoft-AspNetCore-Server-Kestrel
    connections-per-second      Number of connections between update intervals
    total-connections           Total Connections
    tls-handshakes-per-second   Number of TLS Handshakes made between update intervals
    total-tls-handshakes        Total number of TLS handshakes made
    current-tls-handshakes      Number of currently active TLS handshakes
    failed-tls-handshakes       Total number of failed TLS handshakes
    current-connections         Number of current connections
    connection-queue-length     Length of Kestrel Connection Queue
    request-queue-length        Length total HTTP request queue

System.Net.Http
    requests-started        Total Requests Started
    requests-started-rate   Number of Requests Started between update intervals
    requests-aborted        Total Requests Aborted
    requests-aborted-rate   Number of Requests Aborted between update intervals
    current-requests        Current Requests

  • Lancez my-aspnet-server.exe et surveillez le nombre d’assemblys chargés à partir de son démarrage :

    > dotnet-counters monitor --counters System.Runtime[assembly-count] -- my-aspnet-server.exe

Press p to pause, r to resume, q to quit.
  Status: Running

[System.Runtime]
    Number of Assemblies Loaded                   24

  • Lancez my-aspnet-server.exe avec arg1 et arg2 en tant qu’arguments de ligne de commande et surveillez son jeu de travail et sa taille de tas GC à partir de son démarrage :

    > dotnet-counters monitor --counters System.Runtime[working-set,gc-heap-size] -- my-aspnet-server.exe arg1 arg2

    Press p to pause, r to resume, q to quit.
  Status: Running

[System.Runtime]
    GC Heap Size (MB)                                 39
    Working Set (MB)                                  59

dotnet-counters ps

Répertorie les processus dotnet qui peuvent être surveillés par dotnet-counters. dotnet-counters version 6.0.320703 et ultérieures, affichez également les arguments de ligne de commande que chaque processus a démarré, le cas échéant.

Synopsis

dotnet-counters ps [-h|--help]

Exemple

Supposons que vous démarriez une application de longue durée à l’aide de la commande dotnet run --configuration Release. Dans une autre fenêtre, vous exécutez la commande dotnet-counters ps . La sortie que vous verrez est la suivante. Les arguments de ligne de commande, le cas échéant, sont affichés dans dotnet-counters version 6.0.320703 et ultérieures.

> dotnet-counters ps
  
  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

Utilisation du port de diagnostic

Le port de diagnostic est une fonctionnalité d’exécution qui vous permet de démarrer la surveillance ou de collecter des compteurs à partir du démarrage de l’application. Pour ce faire, vous pouvez utiliser dotnet-counters, soit utiliser dotnet-counters <collect|monitor> -- <command> comme décrit dans les exemples ci-dessus, soit utiliser l’option --diagnostic-port.

L’utilisation de dotnet-counters <collect|monitor> -- <command> pour lancer l’application en tant que processus enfant est le moyen le plus simple de le surveiller rapidement à partir de son démarrage.

Toutefois, lorsque vous souhaitez obtenir un contrôle plus fin sur la durée de vie de l’application surveillée (par exemple, surveiller l’application pendant les 10 premières minutes uniquement et continuer à s’exécuter) ou si vous devez interagir avec l’application à l’aide de l’interface CLI, l’option --diagnostic-port vous permet de contrôler à la fois l’application cible en cours d’analyse et dotnet-counters.

  1. La commande ci-dessous fait créer un socket de diagnostic nommé myport.sock par dotnet-counters et attend une connexion.

    dotnet-counters collect --diagnostic-port myport.sock

    Sortie :

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=/home/user/myport.sock

  2. Dans une console distincte, lancez l’application cible avec la variable d’environnement DOTNET_DiagnosticPorts définie sur la valeur dans la sortie dotnet-counters.

    export DOTNET_DiagnosticPorts=/home/user/myport.sock
./my-dotnet-app arg1 arg2

    Cela doit ensuite permettre dotnet-counters de commencer à collecter des compteurs sur my-dotnet-app :

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=myport.sock
Starting a counter session. Press Q to quit.

    Important

    Le lancement de votre application avec dotnet run peut poser problème, car l’interface CLI dotnet peut générer de nombreux processus enfants qui ne sont pas votre application. Ils peuvent se connecter à dotnet-counters avant votre application, laissant votre application suspendue au moment de l’exécution. Il est recommandé d’utiliser directement une version autonome de l’application ou d’utiliser dotnet exec pour lancer l’application.