utilitaire d’analyse des performances dotnet-trace

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

Installer

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

• outil global dotnet :

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

  dotnet tool install --global dotnet-trace
  

• 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

Synopsis

dotnet-trace [-h, --help] [--version] <command>

Description

L’outil dotnet-trace :

• Est un outil .NET Core multiplateforme.
• Active la collecte des traces .NET Core dans un processus en cours d’exécution sans profileur natif.
• Repose sur EventPipe du runtime .NET Core.
• Offre la même expérience sur Windows, Linux ou macOS.

Options

• -h|--help

  Affiche l’aide en ligne de commande.

• --version

  Affiche la version de l’utilitaire dotnet-trace.

• --duration

  Durée d’exécution de la trace. --duration 00:00:00:05 l’exécutera pendant 5 secondes.

Commandes

dotnet-trace collect

Collecte une trace de diagnostic à partir d’un processus en cours d’exécution ou lance un processus enfant et le trace (.NET 5 ou version ultérieure). Pour que l’outil exécute un processus enfant et le trace à partir de son démarrage, ajoutez -- à la commande collect.

Synopsis

dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--clrevents <clrevents>]
    [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [--duration dd:hh:mm:ss]
    [-n, --name <name>] [--diagnostic-port] [-o|--output <trace-file-path>] [-p|--process-id <pid>]
    [--profile <profile-name>] [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io] [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

Options

• --buffersize <size>

  Définit la taille de la mémoire tampon en mémoire, en mégaoctets. Valeur par défaut = 256 Mo.

  Notes

  Si le processus cible émet des événements plus rapidement qu’ils ne peuvent être écrits sur le disque, cette mémoire tampon peut dépasser la capacité et certains événements seront supprimés. Vous pouvez atténuer ce problème en augmentant la taille de la mémoire tampon ou en réduisant le nombre d’événements enregistrés.

• --clreventlevel <clreventlevel>

  Détail des événements CLR à émettre. Le tableau suivant présente les niveaux d’événements disponibles.

  Valeur de chaîne	Valeur numérique
  logalways	0
  critical	1
  error	2
  warning	3
  informational	4
  verbose	5

• --clrevents <clrevents>

  Liste des mots clés du fournisseur d’exécution CLR permettant d’activer des signes séparés par des +. Il s’agit d’un mappage simple qui vous permet de spécifier des mots clés d’événement via des alias de chaîne plutôt que par leurs valeurs hexadécimales. Par exemple, dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 demande le même ensemble d’événements que dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Le tableau ci-dessous présente la liste des mots clés disponibles :

  Alias de chaîne de mot clé	Valeur hexadécimale du mot clé
  gc	0x1
  gchandle	0x2
  fusion	0x4
  loader	0x8
  jit	0x10
  ngen	0x20
  startenumeration	0x40
  endenumeration	0x80
  security	0x400
  appdomainresourcemanagement	0x800
  jittracing	0x1000
  interop	0x2000
  contention	0x4000
  exception	0x8000
  threading	0x10000
  jittedmethodiltonativemap	0x20000
  overrideandsuppressngenevents	0x40000
  type	0x80000
  gcheapdump	0x100000
  gcsampledobjectallocationhigh	0x200000
  gcheapsurvivalandmovement	0x400000
  gcheapcollect	0x800000
  gcheapandtypenames	0x1000000
  gcsampledobjectallocationlow	0x2000000
  perftrack	0x20000000
  stack	0x40000000
  threadtransfer	0x80000000
  debugger	0x100000000
  monitoring	0x200000000
  codesymbols	0x400000000
  eventsource	0x800000000
  compilation	0x1000000000
  compilationdiagnostic	0x2000000000
  methoddiagnostic	0x4000000000
  typediagnostic	0x8000000000

  Vous pouvez en savoir plus sur le fournisseur CLR plus en détail dans la documentation de référence du fournisseur d’exécution .NET.

• --format {Chromium|NetTrace|Speedscope}

  Définit le format de sortie de la conversion du fichier de trace. Par défaut, il s’agit de NetTrace.

• -n, --name <name>

  Nom du processus à partir duquel collecter la trace.

• --diagnostic-port <path-to-port>

  Nom du port de diagnostic à créer. Consultez Utiliser le port de diagnostic pour collecter une trace à partir du démarrage de l’application pour apprendre à utiliser cette option afin de collecter une trace à partir du démarrage de l’application.

• --duration <time-to-run>

  Heure de l’exécution de la trace. Utilisez le format dd:hh:mm:ss. Par exemple 00:00:00:05 l’exécutera pendant 5 secondes.

• -o|--output <trace-file-path>

  Chemin d’accès de sortie pour les données de trace collectées. Si aucune valeur n’est spécifiée, <appname>_<yyyyMMdd>_<HHmmss>.nettrace est utilisé par défaut, par exemple « myapp_20210315_111514.nettrace ».

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

  ID de processus à partir duquel collecter la trace.

• --profile <profile-name>

  Ensemble prédéfini nommé de configurations de fournisseur qui permet aux scénarios de suivi courants d’être spécifiés succinctement. Les profils suivants sont disponibles :

• --providers <list-of-comma-separated-providers>

  Liste séparée par des virgules des fournisseurs EventPipe à activer. Ces fournisseurs complètent tous les fournisseurs découlant de --profile <profile-name>. S’il existe une incohérence pour un fournisseur spécifique, cette configuration est prioritaire sur la configuration implicite du profil.

  Cette liste de fournisseurs se présente sous la forme suivante :

  • Provider[,Provider]
  • Provider a la forme suivante : KnownProviderName[:Flags[:Level][:KeyValueArgs]].
  • KeyValueArgs a la forme suivante : [key1=value1][;key2=value2].

  Pour en savoir plus sur certains fournisseurs connus dans .NET, reportez-vous aux fournisseurs d’événements connus.

• -- <command> (pour les applications cibles exécutant .NET 5 ou version ultérieure)

  Après les paramètres de configuration de collection, l’utilisateur peut ajouter --, suivi d’une commande pour démarrer une application .NET avec au moins un runtime 5.0. Cela peut être utile lors du diagnostic des problèmes qui se produisent au début du processus, tels que le problème de performances de démarrage ou le chargeur d’assembly et les erreurs de classeur.

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

• --show-child-io

  Affiche les flux d’entrée et de sortie d’un processus enfant lancé dans la console actuelle.

• --resume-runtime

  Reprendre le runtime une fois que la session a été initialisée, la valeur par défaut est true. Désactivez la reprise du runtime à l’aide de --resume-runtime:false.

• --stopping-event-provider-name

  Chaîne, analysée en l’état, qui arrête la trace lorsqu’elle atteint un événement avec le nom du fournisseur correspondant. Pour un événement d’arrêt plus spécifique, fournissez --stopping-event-event-name et/ou --stopping-event-payload-filter. Par exemple, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime pour arrêter la trace à l’atteinte du premier événement émis par le fournisseur d’événements Microsoft-Windows-DotNETRuntime.

• --stopping-event-event-name

  Chaîne, analysée en l’état, qui arrête la trace lorsqu’elle atteint un événement avec le nom de l’événement correspondant. --stopping-event-provider-name doit être défini. Pour un événement d’arrêt plus spécifique, fournissez --stopping-event-payload-filter. Par exemple, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted pour arrêter la trace à l’atteinte du premier événement Method/JittingStarted émis par le fournisseur d’événements Microsoft-Windows-DotNETRuntime.

• --stopping-event-payload-filter

  Chaîne, analysée en tant que paires [payload_field_name]:[payload_field_value] séparées par des virgules, ce qui arrête la trace à l’atteinte d’un événement contenant toutes les paires de charges utiles spécifiées. Nécessite que --stopping-event-provider-name et --stopping-event-event-name soient définis. Par exemple, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick pour arrêter la trace lors du premier événement Method/JittingStarted de la méthode OnButtonClick dans l’espace de noms Program émis par le fournisseur d’événements Microsoft-Windows-DotNETRuntime.

• L’arrêt de la trace peut prendre beaucoup de temps (jusqu’à quelques minutes) pour les applications volumineuses. Le runtime doit envoyer le cache type pour tout le code managé capturé dans la trace.

• Sur Linux et macOS, cette commande attend l’application cible et dotnet-trace pour partager la même variable d’environnement TMPDIR. Dans le cas contraire, la commande expire.

• Pour collecter une trace à l’aide de dotnet-trace, il doit être exécuté en tant que même utilisateur que l’utilisateur exécutant le processus cible ou en tant que racine. Sinon, l’outil ne parvient pas à établir une connexion avec le processus cible.

• Si vous rencontrez une exception non gérée lors de l’exécution dotnet-trace collect, cela entraîne une trace incomplète. Si trouver la cause racine de l’exception est votre priorité, accédez à Collecter les vidages en cas d’incident. En raison de l’exception non gérée, la trace est tronquée lorsque le runtime s’arrête pour empêcher tout autre comportement non souhaité, tel qu’un blocage ou une altération des données. Même si la trace est incomplète, vous pouvez toujours l’ouvrir pour voir ce qui a mené à l’échec. Toutefois, il manquera des informations d’exécution (cela se produit à la fin d’une trace) afin que les piles puissent être non résolues (en fonction des fournisseurs activés). Ouvrez la trace en exécutant PerfView avec l’indicateur /ContinueOnError sur la ligne de commande. Les journaux contiennent également l’emplacement où l’exception a été déclenchée.

• Lors de la spécification d’un événement d’arrêt via les options --stopping-event-*, car l’EventStream est analysé de manière asynchrone, certains événements passent entre le moment où un événement de trace correspondant aux options d’événement d’arrêt spécifiées est analysé et l’EventPipeSession est arrêtée.

dotnet-trace convert

Convertit les traces nettrace en formats alternatifs à utiliser avec des outils d’analyse de trace alternatifs.

Synopsis

dotnet-trace convert [<input-filename>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

Arguments

• <input-filename>

  Entrez un fichier de trace à convertir. La valeur par défaut est trace.nettrace.

Options

• --format <Chromium|NetTrace|Speedscope>

  Définit le format de sortie de la conversion du fichier de trace.

• -o|--output <output-filename>

  Nom de fichier de sortie. L’extension du format cible va être ajoutée.

dotnet-trace ps

Répertorie les processus dotnet à partir desquels les traces peuvent être collectées. dotnet-trace 6.0.320703 et versions ultérieures, affiche également les arguments de ligne de commande avec lequel chaque processus a démarré, le cas échéant.

Synopsis

dotnet-trace 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-trace ps . La sortie que vous verrez est la suivante. Les arguments de ligne de commande, le cas échéant, sont affichés dans dotnet-trace version 6.0.320703 et ultérieures.

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

dotnet-trace list-profiles

Répertorie les profils de suivi prédéfini avec une description des fournisseurs et des filtres dans chaque profil.

Synopsis

dotnet-trace list-profiles [-h|--help]

dotnet-trace report

Crée un rapport dans stdout à partir d’une trace générée précédemment.

Synopsis

dotnet-trace report [-h|--help] <tracefile> [command]

Arguments

• <tracefile>

  Chemin d’accès du fichier pour la trace en cours d’analyse.

Commandes

dotnet-trace report topN

Recherche les principales méthodes N qui se trouvent sur la pile d’appels la plus longue.

Synopsis

dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]

Options

• -n|--number <n>

Donne les méthodes N principales sur la pile d’appels.

• --inclusive

Affichez les principales méthodes N en fonction du temps inclusif. Si ce paramètre n’est pas précisé, le temps exclusif est utilisé par défaut.

• -v|--verbose

Affichez les paramètres de chaque méthode dans leur totalité. Si ce paramètre n’est pas précisé, les paramètres sont tronqués.

Collecter une trace avec dotnet-trace

Pour collecter des traces à l’aide de dotnet-trace :

• Obtenez l’identificateur de processus (PID) de l’application .NET Core à partir duquel collecter les traces.

  • Sur Windows, vous pouvez utiliser le Gestionnaire des tâches ou la commande tasklist, par exemple.
  • Sur Linux, par exemple, la commande ps.
  • dotnet-trace ps

• Exécutez la commande suivante :

  dotnet-trace collect --process-id <PID>
  

  La commande précédente génère une sortie similaire à ce qui suit :

  Press <Enter> to exit...
  Connecting to process: <Full-Path-To-Process-Being-Profiled>/dotnet.exe
  Collecting to file: <Full-Path-To-Trace>/trace.nettrace
  Session Id: <SessionId>
  Recording trace 721.025 (KB)
  

• Arrêtez la collecte en appuyant sur la touche <Enter>. dotnet-trace termine la journalisation des événements dans le fichier trace.nettrace .

Lancer une application enfant et collecter une trace à partir de son démarrage à l’aide de dotnet-trace

Parfois, il peut être utile de collecter une trace d’un processus à partir de son démarrage. Pour les applications exécutant .NET 5 ou une version ultérieure, il est possible de le faire à l’aide de dotnet-trace.

Cela lance hello.exe avec arg1 et arg2 en tant qu’arguments de ligne de commande et collecte une trace à partir du démarrage de son runtime :

dotnet-trace collect -- hello.exe arg1 arg2

La commande précédente génère une sortie similaire à ce qui suit :

No profile or providers specified, defaulting to trace profile 'cpu-sampling'

Provider Name                           Keywords            Level               Enabled By
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile
Microsoft-Windows-DotNETRuntime         0x00000014C14FCCBD  Informational(4)    --profile

Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
Output File    : E:\temp\gcperfsim\trace.nettrace


[00:00:00:05]   Recording trace 122.244  (KB)
Press <Enter> or <Ctrl+C> to exit...

Vous pouvez arrêter de collecter la trace en appuyant sur la touche <Enter> ou <Ctrl + C>. Cette opération fermera également hello.exe.

Utiliser le port de diagnostic pour collecter une trace à partir du démarrage de l’application

Le port de diagnostic est une fonctionnalité d’exécution ajoutée dans .NET 5 qui vous permet de démarrer le suivi à partir du démarrage de l’application. Pour y parvenir en utilisant dotnet-trace, vous pouvez utiliser dotnet-trace collect -- <command> comme décrit dans les exemples ci-dessus ou utiliser l’option --diagnostic-port.

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

Toutefois, lorsque vous souhaitez obtenir un contrôle plus fin sur la durée de vie de l’application en cours de suivi (par exemple, surveiller l’application pendant les 10 premières minutes uniquement et poursuivre son exécution) 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-trace.

1. La commande ci-dessous fait en sorte que dotnet-trace crée un socket de diagnostic nommé myport.sock et attend une connexion.

   dotnet-trace 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-trace.

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

   Cela doit ensuite permettre à dotnet-trace de démarrer le suivi de 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-trace 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.

Afficher la trace capturée à partir de dotnet-trace

Sur Windows, vous pouvez afficher les fichiers .nettrace dans Visual Studio ou PerfView à des fins d’analyse.

Sur Linux, vous pouvez afficher la trace en modifiant le format de sortie de dotnet-trace à speedscope. Modifiez le format du fichier de sortie à l’aide de l’option -f|--format. Vous pouvez choisir entre nettrace (l’option par défaut) et speedscope. L’option -f speedscope fera en sorte que dotnet-trace génère un fichier speedscope. Les fichiers Speedscope peuvent être ouverts sur https://www.speedscope.app.

Pour les traces collectées sur des plateformes autres que Windows, vous pouvez également déplacer le fichier de trace vers une machine Windows et l’afficher dans Visual Studio ou PerfView.

Utiliser le fichier .rsp pour éviter de taper des commandes longues

Vous pouvez lancer dotnet-trace avec un fichier .rsp qui contient les arguments à passer. Cela peut être utile lors de l’activation des fournisseurs qui s’attendent à des arguments longs ou lors de l’utilisation d’un environnement d’interpréteur de commandes qui supprime les caractères.

Par exemple, le fournisseur suivant peut être fastidieux à taper chaque fois que vous souhaitez effectuer le suivi :

dotnet-trace collect --providers Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

En outre, l’exemple précédent contient " comme élément de l’argument. Étant donné que les guillemets ne sont pas gérés de manière égale par chaque interpréteur de commandes, vous pouvez rencontrer différents problèmes lors de l’utilisation de différents interpréteurs de commandes. Par exemple, la commande à entrer dans zsh est différente de la commande dans cmd.

Au lieu de taper cela à chaque fois, vous pouvez enregistrer le texte suivant dans un fichier appelé myprofile.rsp.

--providers
Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Une fois que vous avez enregistré myprofile.rsp, vous pouvez lancer dotnet-trace avec cette configuration à l’aide de la commande suivante :

dotnet-trace @myprofile.rsp

Voir aussi

• Fournisseurs d’événements connus de .NET