WPR/WPA Support for Viewing System.Diagnostics.Tracing.EventSource

Up until now, when I have demonstrated how to use the System.Diagnostics.Tracing.EventSource to generate events, I have been using the PerfView tool to turn on the EventSources as well as view the resulting events.   This is because PerfView was on the 'cutting edge' of what I will call 'registration free' ETW that EventSources use.   

Well I am happy to report that the latest version of Windows Performance Toolkit available for download in the Window 8.1 ADK preview. now supports EventSources as well.    When you do the download, it gives you the option of what tools to download.   You only need the 'Windows Performance Toolkit' part of the package.   This includes the 'WPR tool for collecting traces, the WPA tool for analyzing them and the XPERF tool (which is the older tool that predates WPR/WPA).    By default these tools end up in the 'C:\Program Files (x86)\Windows Kits\8.1\Windows Performance Toolkit' directory and get put on your 'path' variable.  After installation you can simply type 'WPA or 'WPR' at the command prompt to launch the programs. 

Note that WPR/WPA and PerfView both use ETW (ETL files) as their format for storing the event information, which means roughly speaking (if you collect the right events), things collected with one tool, can be viewed by the other.   Thus you actually have several options for looking at ETW data (and EventSource data in particular)

  • You an collect with PerfView and view with the Windows Performance Analyzer (WPA) (or PerfView)
  • You an collect with the Windows Performance Recorder (WPR) and view with PerfView (or WPA)
  • You can collect with the older XPERF tool and view with WPA or PerfView.  

Collecting EventSource data with WPR

WPR is the tool that the Windows team would like people to use for data collection going forward so we start with that.    WPR is designed to take its description of what you want to collect from a 'profile', which you can make by authoring an XML file which by convention is given the .WPRP extension.    I have authored a such a file that turns on one EventSource called 'MinimalEventSource', and placed it in a file called MimimalEventSource.wprp.   This file is both attached to this blog, but I have also included it at the end of the article as an 'appendix'.   Armed with this WPRP file using WPR to collect is very easy

  • WPR -start MinimalEventSource.wprp
  • <run A program with MinimalEventSource events logged in it>
  • WPR -stop OUTPUTFILE.ETL

You can start several profiles in one command.  For example to get all the events in the built in 'GeneralProfile' as well as the ones in 'MinimalEventSource' you can do

  • WPR -start GeneralProfile -start MinimalEventSource.wprp
  • <run A program with MinimalEventSource events logged in it>
  • WPR -stop OUTPUTFILE.ETL

Notice that you don't give a file name when you start a trace.  This is because it is being logged to memory in a circular buffer.   When you stop the trace this memory is processed and dumped to the ETL file you specify.   Once you have a ETL file (and possibly an NGENPDB directory), you can look at it with WPA easily

  • WPA OUTPUTFILE.ETL

The EventSource events show up in the 'Generic Events' view of WPA.   Here is a screenshot. 

 Frankly this view is significantly better than PerfView Events view and has very powerful aggregation capabilities.    It is worth learning more about.    On the other hand, I do find that I spend a good minute setting up the view in WPA, and while there are profiles to help automate that, for quick, simple, view of my events I find I am faster with PerfView.    The nice thing is that you can choose whatever tool is most appropriate for you immediate analysis needs, since they both read the same data. 

Collecting PERFVIEW and viewing with WPA

PerfView definitely has some advantages over WPR for data collection.  For example to collect an eventSource with PerfView you need only do

  • PerfView /OnlyProviders=*MinimalEventSource collect

Moreover PerfView is XCOPY deployable and a 5MB quick download off the Web, Couple that with not needing to create a WPRP file, automatic ZIPPing, good default settings for .NET programs, and a bunch of useful ways of stopping on PerfCounters, Exception and other events, PerfView is often the better choice for data collection.  

Unfortunately the current version of PerfView (1.4.1) will not symbolically decode EventSource Events in WPA.   The problem is that WPA relies on special WPA specific events that it injects into the ETL file when it stops a trace.   The support for this came after PerfView V1.4.1 was released, so it does not have the necessary information in the ETL file.     We will be updating PerfView to fix this soon, but in the meantime for those who can't wait, you can download a fixed copy of PerfView from my Skydrive.     This architecture of WPA does have some interesting ramifications

  • It means it is the COLLECTOR not the VIEWER that matters.   Thus if you COLLECT with a fixed version of PerfView, you can VIEW on any version of WPA. 
  • It also means that any traces that were collected before the fix and be 'fixed' by simply 'merging' them with a fixed PerfView:  'PerfView /zip:false merge FILE.ETL'

Collecting with XPERF

The windows performance toolkit does come with the older XPERF.exe tool for collecting data.   If you are used to this (and want to avoid creating a profile for WPR, you can use it for collecting EventSource data.   However this command does NOT have support for the symbolic names for EventSources, so you MUST use the GUID.  Thus you first have to get the GUID for your EventSource (An easy way is to simply use PerfView (on any machine to turn on the EventSource (even if there are not instances on that machine), and look in perfVIews log (button in lower right corner), and it will show you the GUID it actually used.  You can also use the 'Guid' property on your EventSource in code or in a debugger to get the Guid.   Once you have it, it is pretty straightforward, for MinimalEventSource it would be

  • xperf -start MySession -on 7370a335-9b9a-5ba0-63c2-8ce045c35503
  • <run your scenario>
  • xperf -stop MySession -d OUTPUTFILE.ETL

 

 Recap: WPA/WPR supports EventSources

 So the short version of the announcement is that WPR/WPA supports EventSources.   Note that you only need to get the latest COLLECTOR, which means that if you use PerfView, you can simply get the updated version of that, or if you wish to use WPR/XPERF you download the WPT.   The event viewer is quite powerful and if you are doing more sophisticated data analysis, you should certainly invest in learning about it.

 

Appendix: The MinimalEventSource.wprp File

I have attached the MinimalEventSource.wprp at the end of the blog for easy download, but I have also included it here 'inline' for easy cut-and-paste.   The key part of the file is the name of the EventSource that you would like to enable, and I have highlighted it in red below.   Notice that we can use the name, not the GUID (but you can put a GUID there if you want).   The '*' before the name is important because like PerfView, it indicates that this name is not being looked up in some registration table, but is being hashed into the GUID using a standard mechanism. 

-----------------------------------------------------------------------------------------------------------------

<?xml version="1.0" encoding="utf-8"?>
<WindowsPerformanceRecorder Version="1.0">
  <Profiles>
    <EventCollector Id="EventCollector_MyEventSource" Name="MyEventSourceCollector">
      <BufferSize Value="1024" />
      <Buffers Value="200" />
    </EventCollector>
    <EventProvider Id="MinimalEventSource" Name="*MinimalEventSource" />

    <Profile Id="MyEventSource.Verbose.File" Name="MyEventSource" Description="EventSource Collection" LoggingMode="File" DetailLevel="Verbose">
      <Collectors>
        <EventCollectorId Value="EventCollector_MyEventSource">
          <EventProviders>
            <EventProviderId Value="MinimalEventSource" />
          </EventProviders>
        </EventCollectorId>
      </Collectors>
    </Profile>
    <Profile Id="MyEventSource.Verbose.Memory" Name="MyEventSource" Description="EventSource Collection" Base="MyEventSource.Verbose.File" LoggingMode="Memory" DetailLevel="Verbose" />
  </Profiles>
</WindowsPerformanceRecorder>

-----------------------------------------------------------------------------------------------------------------

MinimalEventSource.wprp