Walk Through Getting Started with ETW TraceEvent NuGet Samples package
In a previous post, I talked about the TraceEvent NuGet Library, which allows you to read and manipulate Event Tracing for Windws (ETW). There is a companion post about the EventSource NuGet package which allows you to create your own ETW events (or in fact to send those events to anywhere you choose). My blog entries have a by subject sorting that is handy if you wish to learn more.
But I realized that I have not really shown you step-by-step how to get started with these NuGet packages, and while it is easy, I could easily believe many people are not familiar with NuGet. So in this blog I will show you just how easy it is to get started with this using Visual Studio. (By the way you can get Visual Studio Express as a free download here).
So if you have any interest at all in tracing on windows here is your chance to experiment. To give you an idea just how powerful ETW and the TraceEvent library is, the PerfView tool which you can see in action with its videos, is pretty much just a viewer of the ETW data you can get at with this library.
You get started by creating a console application in Visual Studio. Specifically
- Select File -> New -> Project. This brings up a project creation dialog
- Select Templates -> Visual C# -> Windows in the left pane and 'Console Application in the main pane.
- If you wish to change its name, feel free to do so in the dialog boxes at the bottom, then Click OK.
This will make a new project with an empty 'Main' program. Now add the TraceEvent Samples Nuget package by doing the following
- Right click on the 'References' node in the Solution Explore Pane on the right.
- Select the 'Managed NuGet Packages
This brings up the Nuget Package manager.
- Make sure that the 'All' selection under 'Online' is selected on the left.
- Then type 'TraceEvent' in the search box in the upper right corner. This finds all packages with 'TraceEvent in them.
- Find the Microsoft TraceEvent Library Samples package and click the 'Install' button. This will cause VS to figure out all the other Nuget Packages you need (the samples need the TraceEvent package as well as the 'RX' packages because it shows off those capabilities as well. It will bring up a dialog box to accept the license. It is a standard, generous license.
- Click the 'Accpept' button to accept the license and continue.
You have now downloaded the necessary software into your test application. Note that this does not actually install anything in a normal sense. It simply downloads this package and makes it part of the current project. Your console application now has a reference to the Microsoft.Diagnostics.Tracing.TraceEvent.dll which is the TraceEvent library. One of the cool parts of Nuget is how easy it is to UNINSTALL as well as install. If you go back to the Nuget package manager, select 'Installed Packages' in the left pane you will see all your installed packages (for this project only. Every project is independent), and you can click 'Uninstall' on any of them and it will remove what you have installed. It will NOT remove anything you modified but otherwise it does a good job putting things back they way they were. Try it and see!
Anyway at this point our console application has downloaded and set up the references, but you application has not actually changed. It has however popped up a readme associated with the package so your screen should look something like this
From here we are simply following the README instructions. Things to note (also pointed out in the readme) is that all the sample code is under the 'TraceEventSamples' directory, and that there is a programmers guide that is also include that you can look at (note that in the future this may move directly to the web and not be in the package). All we need to do now is
- Add the 'TraceEventSamples.AllSamples.Run();' line to the main program (like it says to do in the README).
We now have a complete program. You can run it simply by hitting F5 (GO). There are 8 or so different samples and the 'AllSamples.Run' runs them all in sequence (with a Breakpoint between them). The samples include
- Real Time monitoring of ETW data
- Logging ETW data to a file
- Reading ETW data from a file
- Generating and Reading your own events using EventSource and TraceEvent (EventSource comes with V4.5 of the .NET Runtime, or you can get the Nuget package for it if you need it to run on older runtimes).
- Real time monitoring using the 'Reactive Extensions (RX) to process the events.
- Getting stack traces from the ETW events you logged
Each of the samples is heavily commented with design guidance. They are worth a read, and they will likely serve as the 'kernels' of your own logging projects.
Note that the Object Browser and Intellisense works. In particular if you do File -> View -> Object Browser you will see all the Microsoft.Diagnostics.Tracing.TraceEvent assembly and you can browse the classes and methods on it and read the documentation that comes with the classes. After you have gotten your initial bearings using the sample applications and read the programmers guide, browsing this is the way to learn more.
So there you have it. After you have does your experimentation, you probably want to cut and paste any code you created into a new project that represents the application you REALLY wanted to build,refer to the TraceEvent NuGet Package for that application. (you no longer need the samples). As far as deployment goes, like all Nuget packages, TraceEvent is simply a set of DLLs that get put into the output directory along the DLLs you authored explicitly. They are not special at this point. Along with Microsoft.Diagnostics.Tracing.TraceEvent there is also a couple unmanaged DLLs that does native code symbol lookup (msdia120.dll) and starting kernel mode session on pre Win8 OSs (KernelTraceControl.dll). If you don't look up native code symbols (only the 'Stacks sample does this), and don't turn on kernel mode ETW (that is you are not using EnableKernelProvider API OR you don't care that it does not work on Win7) than you don't need these DLLs.
Happy Eventing! Now go write some code....