[Part 1] How I set up ETW for logging (native, .NET, Metro and UApp)

2016-03-01

Code

3 minutes

Check out the codes in GitHub.

Ive been using ETW as my go-to logging mechanism for Windows development. I will be sharing how I setup my environment here.

Creating the manifest file (.man)

I use ecmangen.exe to create my manifest file. This tool is included in the SDK. I have Visual Studio 2015 installed on a Win10 64-bit machine, and its location is C:\Program Files (x86)\Windows Kits\10\bin\x64\. It looks something like this (my completed manifest):

The red strip is the manifest file name, or my ETW provider name.

I started by right-clicking Events Section -> New -> Provider, then gave it a name. Then prepended the string Provider to the existing name for the Symbol, auto-generated the GUID, left the other fields as blank, then Save.

Setting up Keywords

Keywords basically is a mask for filtering log outputs. Mine is just a simple logging mechanism so I have only two keywords. Im not even using KeywordFunctionEntryExit (set to 0x1) that much nowadays so KeywordGeneric (set to 0x2) for me is enough. With this, I have the option later to output only the logs with the keyword KeywordFunctionEntryExit or KeywordGeneric, or both.

Setting up Templates

Templates are, well, templates for the events (in this context, a log is basically an event). Templates will contain the fields (with data types) I want to include in my log. My goal was to have logs with a format of [module_name: src_file_name: function_name] key: value, where key would be any label, say, variable name, and value as, well, any value, be it int or bool, or last error, etc. I thought that this format is generic enough for me to log any information from my code.

All events require a template (whether your template or default, which I admit I have never used). Multiple events can use a single template.

Setting up Events

Lastly, the events themselves. From the image above, I defined quite a number of events. If you noticed, my LastError event (which I use to log the GetLastError() API) specified the template TemplateKeyValueLastError and the keyword KeywordGeneric.

When the manifest file is compiled, all the defined events by default (can be modified during compilation) will generate a logging API with the name EventWrite<event_name>, which in the case of the highlighted one, EventWriteLastError().

Another thing to point out is the Message. The %[number] corresponds to the fields defined in the template used. First field will be %1, second field will be %2, and so on and so on.

Lastly, save your manifest file. The xml file will have a .man extension.

Check out part 2.