Bien démarrer avec EventSource
Cet article s’applique à : ✔️ .NET Core 3.1 et versions ultérieures ✔️ .NET Framework 4.5 et versions ultérieures
Cette procédure pas à pas montre comment consigner un nouvel événement avec System.Diagnostics.Tracing.EventSource, collecter des événements dans un fichier de trace, afficher la trace et comprendre les concepts EventSource de base.
Remarque
De nombreuses technologies intégrées à EventSource emploient les termes « traçage » et « traces » plutôt que « journalisation » et « journaux ». La signification est la même ici.
Journaliser un événement
L’objectif d’EventSource est de permettre aux développeurs .NET d’écrire du code comme celui-ci pour consigner un événement :
DemoEventSource.Log.AppStarted("Hello World!", 12);
Cette ligne de code a un objet de journalisation (DemoEventSource.Log), une méthode représentant l’événement à consigner (AppStarted), et éventuellement certains paramètres d’événement fortement typés (HelloWorld! et 12). Il n'y a pas de niveaux de détail, d'ID d'événement, de modèles de message, ou quoi que ce soit d'autre qui n'ait pas besoin d'être sur le site d'appel. Toutes ces autres informations sur les événements sont écrites en définissant une nouvelle classe dérivée de System.Diagnostics.Tracing.EventSource.
Voici un exemple minimal complet :
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
}
}
La classe DemoEventSource déclare une méthode pour chaque type d’événement que vous souhaitez consigner. Dans ce cas, un événement unique appelé « AppStarted » est défini par la méthode AppStarted(). Chaque fois que le code appelle la méthode AppStarted, un autre événement AppStarted est enregistré dans la trace si l’événement est activé. Voici quelques-unes des données qui peuvent être capturées avec chaque événement :
- Nom de l’événement : nom qui identifie le type d’événement enregistré. Le nom de l’événement est identique au nom de la méthode « AppStarted » dans ce cas.
- ID d’événement : ID numérique qui identifie le type d’événement enregistré. Il joue un rôle similaire à son nom, mais peut contribuer à un traitement automatisé et rapide des journaux. L’événement AppStarted a un ID de 1, spécifié dans la EventAttribute.
- Nom de la source : nom de l’EventSource qui contient l’événement. Il s’agit d’un espace de noms pour les événements. Les noms d’événements et les ID doivent simplement être uniques dans l’étendue de leur source. Ici, la source est nommée « Demo », spécifiée dans la EventSourceAttribute sur la définition de classe. Le nom de la source est également communément appelé nom de fournisseur.
- Arguments : toutes les valeurs d’argument de méthode sont sérialisées.
- Autres informations - Les événements peuvent également contenir des horodatages, des ID de threading, des ID de conteneur, des ID d'activité, des traces de pile et des métadonnées d'événement telles que des modèles de message, des niveaux de détail et des mots-clés.
Pour plus d'informations et de meilleures pratiques sur la création d'événements, consultez Instrumenter le code pour créer des événements.
Collecter et afficher un fichier de trace
Il n’existe aucune configuration requise dans le code qui décrit les événements à activer, où les données journalisées doivent être envoyées ou dans quel format les données doivent être stockées. Si vous exécutez l’application maintenant, elle ne produit aucun fichier de trace par défaut. EventSource utilise le modèle publier-abonnement, ce qui oblige les abonnés à indiquer les événements qui doivent être activés et à contrôler toute sérialisation pour les événements abonnés. EventSource dispose d'intégrations permettant de s'abonner à Event Tracing for Windows (ETW) et à EventPipe (.NET Core uniquement). Les abonnés personnalisés peuvent également être créés à l’aide de l’API System.Diagnostics.Tracing.EventListener.
Cette démonstration montre un EventPipe exemple pour les applications .NET Core. Pour découvrir davantage d'options, consultez Collecte et visualisation des traces d'événements. EventPipe est une technologie de suivi ouverte et multiplateforme intégrée au runtime .NET Core pour donner aux développeurs .NET des outils de collecte de traces et un format de trace compact portable (fichiers*.nettrace). dotnet-trace est un outil en ligne de commande qui collecte les traces EventPipe.
- Téléchargez et installez dotnet-trace.
- Générez l’application console ci-dessus. Cette démonstration suppose que l’application est nommée EventSourceDemo.exe et qu’elle se trouve dans le répertoire actif. Exécutez la ligne de commande :
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
Cela doit afficher une sortie similaire à :
Provider Name Keywords Level Enabled By
Demo 0xFFFFFFFFFFFFFFFF Verbose(5) --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_20220303_001619.nettrace
[00:00:00:00] Recording trace 0.00 (B)
Press <Enter> or <Ctrl+C> to exit...
Trace completed.
Cette commande a exécuté EventSourceDemo.exe avec tous les événements de l’EventSource « Demo » activés et a produit le fichier de trace EventSourceDemo.exe_20220303_001619.nettrace.
L’ouverture du fichier dans Visual Studio affiche les événements enregistrés.
Dans l’affichage liste, vous pouvez voir que le premier événement est l’événement Demo/AppStarted. La colonne de texte contient les arguments enregistrés, la colonne timestamp indique que l’événement s’est produit 27 ms après le démarrage de la journalisation et à droite, vous pouvez voir la pile des appels. Les autres événements sont automatiquement activés dans chaque trace collectée par dotnet-trace, bien qu'ils puissent être ignorés et filtrés de l'affichage dans l'interface utilisateur s'ils sont distrayants. Ces événements supplémentaires capturent des informations sur le processus et le code joint, ce qui permet à Visual Studio de reconstruire les traces de la pile d'événements.
