More on using EventSources with XPERF or WPR

In my introduction to EventSource blog, I showed a simple example of using EventSource to log ETW information. In that example I used the PerfView tool to collect and display the information.   It is also possible to do the same using the XPERF or WPR tools (part of the WIndows Performance Toolkit) and in this blog entry I give an example.   In this entry I give some background

For the most part, an EventSource is really just another ETW provider.    The main difference is that an EventSource has support for logging its manifest INTO THE DATA STREAM, to make the resulting ETW data stream SELF-DESCRIBING, in the sense that you don't need other information (e.g. a registered manifest), to decode event payloads.    Thus while you CAN register the manifest of an EventSource, you don't have to, and most EventSources don't.  (If you are interested in registering EventSource manifest see my blog on channel support will lead you to the EventSource Samples Nuget package that has detailed samples and documentation on doing this (because channels REQUIRE that you register the manifest)). 

The fact that an EventSource EMITs this data is however not sufficient, you also need TOOLS to USE the information (instead of looking in the registration database), to complete the picture.   Both PerfView and WPA do this.  Thus these tools 'just work' on EventSources and decode their payloads as you would expect.   However decoding the payloads is not the only use of the registration database.   In the Operating system an ETW provider is identify by a GUID and normally will look up the name in the registration database and thus can convert the name to a GUID.   SInce EventSources don't register themselves, it means that you can't use an EventSource name to turn the provider on or off.     EventSource solves this by making it possible to FIND the GUID from the NAME without needing a registration database.    It does this by picking a VERY PARTICULAR GUID.   Basically what it does is take the name of the EventSource, capitalize it (to make it case insensitive) and then HASH the name in a standard way (using SHA1), and then use the HASH to form a Guid.  The details are not particularly important, the key is that knowing just the name, you can find the GUID for a EventSource, and it is VERY unlikely that two EventSources will have the same GUID.    

The EventSources also PROVIDE a mechanism to solve the name -> GUID problem but again, tools have to step up and use this.   The PerfView and WPA tools have done this (however at last check XPERF does not).    The convention that both PerfView and WPA use is that a name that is prefixed with a '*' means 'please hash the name into a GUID using EventSources's standard hashing mechanism.   This allows you use names when turning providers on and off. 

 OK, with that background, we can apply this knowledge to the XPERF/WPR scenarios. 

The XPERF CASE:

Because XPERF does not support the *Name syntax, you must use the GUID in the XPERF command line.   To do this you need the GUID for the EventSource.   You can get this either by asking your EventSource for its name programmatically (it is the Guid Property on the EventSource), or perhaps easier simply turn on the provider using PerfView with the *Name syntax and then look in PerfVIew's log for the GUID for the EventSource.   Once you have the GUID you can form the command line.

For example, I determined that for the MinimalEventSource, its GUID was 7370a335-9b9a-5ba0-63c2-8ce045c35503, thus I could turn it on using the command lines

  • xperf -start MySession -on 7370a335-9b9a-5ba0-63c2-8ce045c35503
  • Run your scenario
  • xperf -stop MySession -d output.etl

Which turn on the provider, runs the scenario and stops the provider.  The resulting output.etl file can be viewed with WPA or PerfView.   In WPA the events are in the 'Generic Events' view and in PerfView in the 'events' view.  

 The WPR CASE:

WPR directly supports the *Name syntax, so you don't need to deal with the GUIDs.  However sadly unlike XPERF, WPR does not provide a way of adding another provider by passing a command line switch.   Instead you have to create  a WPRP file that describes the provider and its keywords/level and you refer to this WPRP on the command. line.   I have included such a file for the MinimalEventSource provider at the end of this blog.  If you download this you can run the commands

  • WPR -start  MinimalEventSource.wprp
  • Run your scenario
  • WPR -stop output.etl 

Most of this is a recap of this blog entry, which gives more hands-on details.  

MinimalEventSource.wprp