Prise en main d’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 journaliser 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.
Notes
De nombreuses technologies qui s’intègrent à EventSource utilisent les termes « Traçage » et « Traces » au lieu de « Journalisation » et « Journaux ». Le sens est le 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 journaliser 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 à journaliser (AppStarted) et éventuellement des paramètres d’événement fortement typés (HelloWorld! et 12). Il n’existe aucun niveau de détail, ID d’événement, modèle de message ou autre chose qui n’a 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 journaliser. 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 sera 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 au nom, mais peut aider à accélérer le traitement automatisé des journaux. L’événement AppStarted a l’ID 1, spécifié dans EventAttribute.
- Nom de la source : nom de l’instance EventSource qui contient l’événement. Il est utilisé comme espace de noms pour les événements. Les noms d’événements et les ID doivent uniquement être uniques dans l’étendue de leur source. Ici, la source est nommée « Demo », comme spécifié dans EventSourceAttribute dans 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 timestamps, des ID de thread, des ID de processeur, des ID d’activité, des traces de pile et des métadonnées d’événement, comme des modèles de message, des niveaux de détail et des mots clés.
Pour plus d’informations et pour connaître les meilleures pratiques relatives à la création d’événements, consultez Instrumentation du 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 qui doivent être activés, 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-S’abonner, qui exige que les abonnés indiquent les événements qui doivent être activés et contrôlent la sérialisation des événements abonnés. EventSource dispose d’intégrations pour l’abonnement à partir du Suivi d’événements pour Windows (ETW) et EventPipe (.NET Core uniquement). Des abonnés personnalisés peuvent également être créés à l’aide de l’API System.Diagnostics.Tracing.EventListener.
Cette démonstration montre un exemple EventPipe pour les applications .NET Core. Pour en savoir plus sur d’autres options, consultez Collecte et affichage des traces d’événements. EventPipe est une technologie de suivi ouverte et multiplateforme intégrée au runtime .NET Core pour fournir aux développeurs .NET des outils de collecte de trace 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écharger et installer 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. À la ligne de commande, exécutez :
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
La sortie devrait ressembler à ce qui suit :
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é et émis le fichier de trace EventSourceDemo.exe_20220303_001619.nettrace en sortie.
L’ouverture du fichier dans Visual Studio affiche les événements enregistrés.
Dans l’affichage de 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 à partir d’une vue dans l’interface utilisateur s’ils vous distraient. Ces événements supplémentaires capturent des informations sur le processus et le code traité avec Jit, ce qui permet à Visual Studio de reconstruire les traces de pile d’événements.
