Collecter et afficher les traces EventSource

Cet article s’applique à : ✔️ .NET Core 3.1 et versions ultérieures✔️ .NET Framework 4.5 et versions ultérieures

Le guide de prise en main vous a montré comment créer un EventSource minimal et collecter des événements dans un fichier de trace. Ce tutoriel montre comment différents outils peuvent configurer les événements qui sont collectés dans une trace, puis afficher les traces.

Exemple d’application

Vous allez utiliser l’exemple d’application suivant qui génère des événements pour ce tutoriel. Compilez une application console .NET contenant le code suivant :

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
            DemoEventSource.Log.DebugMessage("Got here");
            DemoEventSource.Log.DebugMessage("finishing startup");
            DemoEventSource.Log.RequestStart(3);
            DemoEventSource.Log.RequestStop(3);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1, Keywords = Keywords.Startup)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
        [Event(2, Keywords = Keywords.Requests)]
        public void RequestStart(int requestId) => WriteEvent(2, requestId);
        [Event(3, Keywords = Keywords.Requests)]
        public void RequestStop(int requestId) => WriteEvent(3, requestId);
        [Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
        public void DebugMessage(string message) => WriteEvent(4, message);


        public class Keywords
        {
            public const EventKeywords Startup = (EventKeywords)0x0001;
            public const EventKeywords Requests = (EventKeywords)0x0002;
        }
    }
}

Configurer les événements à collecter

La plupart des outils de collecte d’événements utilisent ces options de configuration pour décider quels événements doivent être inclus dans une trace :

• Noms des fournisseurs : il s’agit d’une liste d’un ou plusieurs noms EventSource. Seuls les événements définis sur EventSource dans cette liste peuvent être inclus. Pour collecter des événements à partir de la classe DemoEventSource dans l’exemple d’application précédent, vous devez inclure le nom EventSource « Demo » dans la liste des noms de fournisseurs.
• Niveau de détail des événements : pour chaque fournisseur, vous pouvez définir un niveau de détail, et les événements dont la verbosité est supérieure à ce niveau seront exclus de la trace. Si vous avez spécifié que le fournisseur « Demo » dans l’exemple d’application précédent doit être collecté au niveau de détail Informational, l’événement DebugMessage serait exclu, car il a un niveau supérieur. La spécification de EventLevel LogAlways(0) est un cas particulier qui indique que des événements de n’importe quel niveau de détail doivent être inclus.
• Mots clés d’événement : pour chaque fournisseur, vous pouvez définir un ensemble de mots clés, et seuls les événements marqués avec au moins un des mots clés seront inclus. Dans l’exemple d’application ci-dessus, si vous avez spécifié le mot clé Startup, seuls les événements AppStarted et DebugMessage sont inclus. Si aucun mot clé n’est spécifié, il s’agit d’un cas particulier, et cela signifie que les événements avec n’importe quel mot clé doivent être inclus.

Conventions pour décrire la configuration du fournisseur

Bien que chaque outil détermine sa propre interface utilisateur pour définir la configuration de la trace, il existe une convention commune que de nombreux outils utilisent lors de la spécification de la configuration en tant que chaîne de texte. La liste des fournisseurs est spécifiée sous la forme d’une liste délimitée par des points-virgules, et chaque élément de fournisseur de la liste se compose d’un nom, de mots clés et d’un niveau, séparés par des caractères deux-points. Par exemple, « Demo:3:5 » identifie l’EventSource nommé « Demo » avec le masque de mot clé 3 (les parties Startup et Requests) et le EventLevel 5, qui est Verbose. De nombreux outils vous permettent également d’omettre le niveau et les mots clés si aucun filtrage de niveau ou de mot clé n’est souhaité. Par exemple, « Demo::5 » effectue uniquement un filtrage basé sur les niveaux, « Demo:3 » ne fait que le filtrage basé sur les mots clés, et « Demo » ne fait aucun filtrage de mot clé ou de niveau.

Visual Studio

Le profileur Visual Studio prend en charge la collecte et l’affichage des traces. Il peut également afficher les traces collectées au préalable par d’autres outils, comme dotnet-trace.

Collecter une trace

La plupart des outils de profilage de Visual Studio utilisent des ensembles d’événements prédéfinis qui servent un objectif particulier, comme l’analyse de l’utilisation ou des allocations du processeur. Pour collecter une trace avec des événements personnalisés, vous allez utiliser l’outil Visionneuse d’événements.

1. Pour ouvrir le Profileur de performances dans Visual Studio, sélectionnez Alt+F2.

2. Cochez la case Visionneuse d’événements.

   

3. Sélectionnez la petite icône d’engrenage à droite de la visionneuse d’événements pour ouvrir la fenêtre de configuration.

   Dans le tableau ci-dessous Fournisseurs supplémentaires, ajoutez une ligne pour chaque fournisseur que vous souhaitez configurer en cliquant sur la case Activé, puis en entrant le nom du fournisseur, les mots clés et le niveau. Vous n’avez pas besoin d’entrer le GUID du fournisseur ; il est calculé automatiquement.

   

4. Sélectionnez OK pour confirmer les paramètres de configuration.

5. Sélectionnez Démarrer pour commencer à exécuter l’application et à collecter les journaux.

6. Sélectionnez Arrêter la collecte ou quittez l’application pour arrêter la collecte des journaux et afficher les données collectées.

Afficher une trace

Visual Studio peut afficher les traces qu’il a collectées lui-même ou afficher les traces collectées dans d’autres outils. Pour afficher les traces d’autres outils, utilisez Fichier>Ouvrir et sélectionnez un fichier de trace dans le sélecteur de fichiers. Le profileur Visual Studio prend en charge les fichiers .etl (format standard d’ETW), les fichiers .nettrace (format standard d’EventPipe) et les fichiers .diagsession (format standard de Visual Studio). Pour plus d’informations sur l’utilisation des fichiers de trace dans Visual Studio, consultez la documentation Visual Studio.

PerfView

PerfView est un outil de performances créé par l’équipe .NET qui peut collecter et afficher les traces ETW. Il peut également afficher les fichiers de trace collectés par d’autres outils dans différents formats. Dans ce tutoriel, vous allez collecter une trace ETW de l’application de démonstration, puis examiner les événements collectés dans la visionneuse d’événements de PerfView.

Collecter une trace

1. Téléchargez PerfView à partir de la page des versions. Ce tutoriel a été effectué avec PerfView version 2.0.76, mais toute version récente devrait fonctionner.

2. Démarrez PerfView.exe avec les autorisations d’administrateur.

   Notes

   La collection de traces ETW nécessite toujours des autorisations d’administrateur. Toutefois, si vous utilisez PerfView uniquement pour afficher une trace préexistante, aucune autorisation spéciale n’est nécessaire.

   

3. Dans le menu Collecter, sélectionnez Exécuter. Cela ouvre une nouvelle boîte de dialogue dans laquelle vous allez entrer le chemin d’accès à l’application de démonstration.

   

4. Pour configurer les événements qui sont collectés, développez Options avancées en bas de la boîte de dialogue. Dans la zone de texte Fournisseurs supplémentaires, entrez des fournisseurs à l’aide du format de texte conventionnel décrit précédemment. Dans ce cas, vous entrez « Demo:1:4 », ce qui signifie le mot clé 1 (événements Startup) et le niveau de détail 4 (Informational).

   

5. Pour lancer l’application et commencer à collecter la trace, sélectionnez le bouton Exécuter la commande. Lorsque l’application se ferme, la trace PerfViewData.etl est enregistrée dans le répertoire actif.

Afficher une trace

1. Dans la zone de texte déroulante de la fenêtre principale en haut à gauche, sélectionnez le répertoire contenant le fichier de trace. Double-cliquez ensuite sur le fichier de trace dans l’arborescence en dessous.

   

2. Pour afficher la visionneuse d’événements, double-cliquez sur l’élément Événements qui s’affiche dans l’arborescence sous le fichier de trace.

   

3. Tous les types d’événements de la trace sont affichés dans la liste à gauche. Double-cliquez sur un type d’événement, comme Demo\AppStarted, pour afficher tous les événements de ce type dans la table à droite.

   

En savoir plus

Pour en savoir plus sur l’utilisation de PerfView, consultez les tutoriels vidéo PerfView.

dotnet-trace

dotnet-trace est un outil en ligne de commande multiplateforme qui peut collecter des traces à partir d’applications .NET Core à l’aide du suivi EventPipe. Il ne prend pas en charge l’affichage des données de trace, mais les traces qu’il collecte peuvent être affichées par d’autres outils, comme PerfView ou Visual Studio. dotnet-trace prend également en charge la conversion de ses traces de format .nettrace par défaut en d’autres formats, comme Chromium ou Speedscope.

Collecter une trace

1. Téléchargez et installez dotnet-trace.

2. Sur la ligne de commande, exécutez la commande dotnet-trace collect :

   E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   

   La sortie devrait ressembler à ce qui suit :

   E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe
   
   Provider Name                           Keywords            Level               Enabled By
   Demo                                    0x0000000000000001  Informational(4)    --providers
   
   Launching: EventSourceDemo.exe
   Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
   Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220317_021512.nettrace
   
   [00:00:00:00]   Recording trace 0.00     (B)
   Press <Enter> or <Ctrl+C> to exit...
   
   Trace completed.
   

   dotnet-trace utilise le format de texte conventionnel pour décrire la configuration du fournisseur dans l’argument --providers. Pour plus d’options sur l’utilisation des traces à l’aide de dotnet-trace, consultez la documentation dotnet-trace.

EventListener

System.Diagnostics.Tracing.EventListener est une API .NET qui peut être utilisée in-process pour recevoir des rappels pour les événements générés par un System.Diagnostics.Tracing.EventSource. Cette API peut être utilisée pour créer des outils de journalisation personnalisés ou pour analyser les événements en mémoire sans jamais les sérialiser.

Pour utiliser EventListener, déclarez un type qui dérive de EventListener, appelez EnableEvents pour vous abonner aux événements de n’importe quel EventSource d’intérêt, et remplacez le OnEventWritten, qui sera appelé chaque fois qu’un nouvel événement est disponible. Il est souvent utile de remplacer OnEventSourceCreated pour découvrir quels objets EventSource existent, mais cela n’est pas obligatoire. Voici un exemple d’implémentation de EventListener qui s’imprime dans la console lorsque des messages sont reçus :

1. Ajoutez ce code à l’application de démonstration.

   class ConsoleWriterEventListener : EventListener
   {
       protected override void OnEventSourceCreated(EventSource eventSource)
       {
           if(eventSource.Name == "Demo")
           {
               EnableEvents(eventSource, EventLevel.Informational);
           }
       }
   
       protected override void OnEventWritten(EventWrittenEventArgs eventData)
       {
           Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName);
       }
   }
   

2. Modifiez la méthode Main pour créer une instance de l’écouteur.

   public static void Main(string[] args)
   {
       ConsoleWriterEventListener listener = new ConsoleWriterEventListener();
   
       DemoEventSource.Log.AppStarted("Hello World!", 12);
       DemoEventSource.Log.DebugMessage("Got here");
       DemoEventSource.Log.DebugMessage("finishing startup");
       DemoEventSource.Log.RequestStart(3);
       DemoEventSource.Log.RequestStop(3);
   }
   

3. Générez et exécutez l'application. Auparavant, elle n’avait pas de sortie, mais elle écrit maintenant les événements dans la console :

   3/24/2022 9:23:35 AM AppStarted
   3/24/2022 9:23:35 AM RequestStart
   3/24/2022 9:23:35 AM RequestStop