ETW Provider Names and GUIDs

  • Article

An ETW provider is a component that creates ETW events. Internally, ETW identifies each provider with a GUID, and all event filtering/routing in ETW starts with the provider GUID. For example, if I want to capture an ETL file containing events from a particular provider, I would find the provider's GUID, and then execute an xperf or tracelog command similar to the following:

xperf -start MySessionName -f MySession.etl -on 2e0582f3-d1b6-516a-9de3-9fd79ef952f8

GUIDs are ugly, so the systems layered above core ETW have established conventions for friendly provider names. For example, ETW manifests include the provider GUID and the provider name. When you compile the manifest and register the resulting decoding information, both the GUID and the name are added to the registry, allowing the decoding information to be found either by GUID or by name.

To avoid problems with this system:

  • The association between GUID and Name is one-to-one. Once you've published the Name and GUID for a provider, the association between Name and GUID is permanent. If you change the GUID, you must change the Name, and if you change the Name, you must change the GUID.
  • Searching for providers by Name is generally not case-sensitive. However, some reporting tools may be confused if they see two names that differ in case. Because of this, do not change the uppercase/lowercase of any letters in the name once you've published the Name of a provider.
  • The provider Name is not localized. It is a symbol, like a variable name or file name.
  • The provider Name is global, so it should be properly namespaced. Manifest providers often use the convention CompanyName-ProductName-ComponentName (with additional parts as needed for SubCompontName), e.g. "Microsoft-Windows-Globalization". It is also common to use periods instead of hyphens, e.g. "Microsoft.Windows.DHCP".

The .NET EventSource class developed a convention for generating the provider GUID by hashing the provider Name (algorithm based on RFC 4122). This has worked well in practice -- the developer provides the human-friendly provider name, and EventSource internally manages turning that into a machine-friendly GUID. If the provider Name is changed, the provider GUID will also change (as long as the change involves more than just uppercase/lowercase).

Support for this convention has been added to WPR. Normally, you provide WPR with the provider's GUID, but if you generated the provider GUID using the EventSource algorithm, you can instead provide the friendly name to WPR prefixed with an asterisk, e.g. "*MyProviderName".

This convention has also been adopted by the Windows Framework LoggingChannel class. The provider GUID is an optional parameter, and if omitted, the provider GUID will be generated using the EventSource algorithm.

This convention can also be used with manifest-based ETW or with TraceLoggingProvider.h, but the tools will not automatically generate the GUID for you. Instead, you can use the attached EtwGuid tool (public domain C# sample code). The tool treats each command-line argument as a provider Name. For each argument, it outputs a code snippet with the corresponding provider GUID. The resulting code snippet is formatted for use with TraceLoggingProvider.h, but the GUID can also be used in a manifest.

Example usage:

 D:\Stuff\Projects\EtwGuid\bin\Debug>EtwGuid.exe SampleProvider1 SampleProvider2

TRACELOGGING_DEFINE_PROVIDER(
    g_hMyProvider,
    "SampleProvider1",
    // {69aed5be-95eb-5b26-ed54-cf841b064fed}
    (0x69aed5be,0x95eb,0x5b26,0xed,0x54,0xcf,0x84,0x1b,0x06,0x4f,0xed));

TRACELOGGING_DEFINE_PROVIDER(
    g_hMyProvider,
    "SampleProvider2",
    // {7880d1eb-f225-56df-f429-3e3a24c6f149}
    (0x7880d1eb,0xf225,0x56df,0xf4,0x29,0x3e,0x3a,0x24,0xc6,0xf1,0x49));

D:\Stuff\Projects\EtwGuid\bin\Debug>

EtwGuid.zip