EventRegister Users' Guide

A utility for registering Event Tracing for Windows (ETW) event providers that are implemented using managed code and either the System.Diagnostics.Tracing.EventSource class or the NuGet-shipped Microsoft.Diagnostics.Tracing.EventSource.

A Quick Summary of Event Tracing for Windows (ETW)

Event Tracing for Windows is infrastructure built into the Windows operating system that allows user code to generate events.  This event logging capability is fast enough that even 100K events / sec is not unreasonable (but will have a noticable impact) and each event is marked with the process and thread it came from, as well as the time (typically in 100ns accuracy), so even fine grained timing intervals can be measured accurately.  More information can be found in the ETW MSDN reference.  Note that 'Classic' events refer to an older version of ETW (before windows Vista), and can be skipped initially.  Manifest based ETW is the model that managed code exposes (even if it is running on an older OS). 

Code that logs events is called a Provider and all providers must register themselves with the Operating System  (eg with the EventRegister) before any logging can happen.  When a provider registers it provides a GUID that is used to identify the provider.  Once registered the operating system will notify the provider if logging is desired.  The 'logman' command (as well as the xperf command) can then be used to turn providers on and off.

Each event that a provider creates has the following data

  1. Infomation logged for every event, including a timestamp, and the process and thread that generated the event.
  2. The GUID of the provider that created it.
  3. A small integer indicated which event the provider is logging.
  4. Optional information that allows events to be grouped by purpose (Tasks, Opcodes), Verbosity (Levels) or Audience (Channels).  In addition there is an event version number as well as the ability to describe sets of events that are often turned on or off together (Keywords). 
  5. Optional specific payload (arbirary binary data up to 64K)

Using Events from Managed Code

It is very easy to create a new provder from managed code using the System.Diagnositics.Eventing.EventSource case.  Here is the code for a very simple provider

sealed class MinimalProvider : EventSource
{
   public static MinimalProvider Log = new MinimalProvider();
   public void Load(long ImageBase, string Name) { if (IsEnabled()) WriteEventHelper(1, ImageBase, Name); }
   public void Unload(long ImageBase) { if (IsEnabled()) WriteEventHelper(2, ImageBase); }
}

This creates a new provider called 'MinimalProvider'.  This particular provider has two events (Load and Unload), and each event has extra information that gets passed along into the log (ImageBase and (for Load) Name).  You can then log things simply by doing

MinimalProvider.Log.Load(10, "FileLoading");    // Log a load
MinimalProvider.Log.Unload(10);		    // Log an unload
You can then log things simply by doing
logman start MySessionName -p {0c836fd3-ee92-4301-bc13-d8943e0c1e77} -ets
RUN_SCENARIO
logman stop MySessionName -ets

Where RUN_SCENARIO activates your logging.  Note that even if the process that has the provider is already running, the provider will get notified and logging will happen (no need to restart processes).  The commands above place all the logging information the a 'MySessionName.etl' file. 

An important observation is that events are fundamentally just blobs of data, and it is only by knowing the schema of the event that it can be put to real use.  Thus string names need to be given to events, and the payloads of the events need to be described (in a strongly typed way).  This is the purpose of the event manifest.  The event manifest is so important that EventSource writes it to the event stream before the provider writes its first event.  That way it is impossible for a log to be 'unreadable' because you don't have the decoding information.

The EventRegister Command

Some tools, however do not know how to decode the manifest that is in the event stream.  In addition, using a GUID to identify a provider in the logman command is inconvenient (hard for humans to remember).  Registering the manifest solves both of these problems and this is what EventRegister.exe is designed to do. 

Using EventRegister is simple

That is you simply give it the DLL that contains the definition of your provider.  The EventRegister command then uses the Reflection APIs to generate a manifest from the code in that DLL and registers it with the system (you need to be an administrator to do this). 

If your event source uses channel support (first provided in the EventSource NuGet package) you will need to generate manifest and resource DLLs at build time and deploy and register the manifest at the time your application is set up. To generate these files simply use the /dumpRegDlls qualifier

If you want to see the manifest that would be registered, you can use the /dumpManifest qualifier

You will need to do this on every machine where

If you are content to use GUIDs to turn your provider on and off, you only use tools that know how to fetch the manifest out of the log, and you do not use channel support then you don't need to register your provider.