TraceLoggingChannel macro (traceloggingprovider.h)

Article
06/10/2022

TraceLogging wrapper macro that sets the channel for the event.

Most TraceLogging events do not need to change the event's default channel and should not use TraceLoggingChannel.

Syntax

void TraceLoggingChannel(
  [in]  eventChannel
);

Parameters

[in] eventChannel

The channel to which the event should be logged. This is an integer value from 0 to 255.

See EVENT_DESCRIPTOR for details about the event channel.

Return value

None

Remarks

TraceLoggingChannel(eventChannel) can be used as a parameter to an invocation of a TraceLoggingWrite macro. Most TraceLogging events do not need to change the event's default channel and should not use TraceLoggingChannel.

The eventChannel parameter must be a compile-time constant 0 to 255. If no TraceLoggingChannel(n) arg is provided, the default channel is 11 (WINEVENT_CHANNEL_TRACELOGGING), indicating that this is a normal TraceLogging event. If multiple TraceLoggingChannel(n) args are provided, the value from the last TraceLoggingChannel(n) parameter will be used.

Channels are used in advanced Event Tracing for Windows (ETW) scenarios. These include writing to system-defined event consumers such as the Windows Event Log.

Warning

If your provider will run on Windows earlier than Windows 10, do not use TraceLoggingChannel. For an event to be recognized as TraceLogging-compatible by event decoders, it must either have the channel set to the default value (11) or it must have been marked as a TraceLogging event by the ETW runtime during EventWrite. This event marking is enabled by calling EventSetInformation to configure the provider as a TraceLogging provider. EventSetInformation in Windows 10 or later enables support for TraceLogging events regardless of channel, but earlier versions of Windows require a Windows update before they support marking TraceLogging events. For events captured on systems without an updated EventSetInformation, channel 11 is the only way to recognize a TraceLogging event, so events with other channels may not decode correctly.

TraceLogging and Event Log

In most cases, developers use manifest-based ETW for events that need to be recorded by Event Log. Event Log is primarily intended to collect low-volume events that are likely to be useful to the administrator of a system. Manifest-based ETW works well for this because it supports carefully-curated events (all events for the component are described in one manifest file) and because it supports localizable message strings that can help the administrator know how to react to the event.

Although TraceLogging events do not have message strings and are generally not centrally-curated, TraceLogging can still be appropriate for some Event Log scenarios. For example, while events that go to the Windows Logs (Application, Security, Setup and System) should always have localized message strings and should always be useful to the system administrator, events recorded in the Applications and Services Logs can be more technical and can record diagnostic information. When writing to the Applications and Services Logs, you might want to use TraceLogging to simplify management of the logged events.

Using TraceLogging events with Windows Event Log is similar to using normal manifest-based events with Event Log. You still need to create and register a manifest to define the provider and the channels but you don't need to define the individual events in the manifest:

Write an ETW manifest that defines your provider and the Event Log channels. The provider in the manifest should use the same provider name and provider guid (provider ID) as you used in your TRACELOGGING_DEFINE_PROVIDER macro. The manifest does not need to include <event> or <template> definitions since TraceLogging events are self-describing.
In the build process for your component, use Message Compiler (MC.exe) from Windows SDK 10.0.22621 or later to compile the manifest. This will generate the following files:
- ManifestName.h: C/C++ header containing constant definitions. This will define the ChannelSymbol and the ChannelSymbol_KEYWORD constants that you will need to use in your TraceLogging events. (The actual names of the constants will be different for each channel.)
- ManifestName.rc: Resource Compiler (RC.exe) script that adds the manifest BIN data to a binary (EXE, DLL, or SYS) file. You will need to include this resource script into the resources of one of the binary files in your component.
- ManifestNameTEMP.BIN, MSG00001.bin: manifest BIN data referenced by ManifestName.rc.
#include the generated ManifestName.h file into the code that needs to generate TraceLogging events. This will define the ChannelSymbol and ChannelSymbol_KEYWORD constants.
- If you specified the symbol attribute on the <channel> or <importChannel> definition in the manifest, the name of ChannelSymbol will be the value of your symbol attribute. Otherwise, ChannelSymbol will be ProviderSymbol_CHANNEL_ChannelName (i.e. it will use the symbol from your <provider> element and the name from your <channel> or <importChannel> element).
- The name of ChannelSymbol_KEYWORD is the name of ChannelSymbol followed by _KEYWORD.
- The ChannelSymbol_KEYWORD constant is only generated by MC.exe 10.0.22621 or later.
Each TraceLogging event that is to go to Event Log must use TraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD) to set the channel and keyword for the event. For example, if my channel's symbol is MY_CHANNEL, I would add TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) as parameters to the TraceLoggingWrite macro for the event.
In order for Event Log to recognize your provider, the information from your manifest must be included in the resources of a module (DLL, EXE, or SYS file) that will be installed on the target system.
In order for Event Log to receive events from your provider, you must register your manifest on the target system using wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll during component install. You must also unregister your manifest using wevtutil um ManifestFile.man during component uninstall.

Important

If your provider is registered with Event Log, all events generated by your provider must have a non-zero keyword specified with TraceLoggingKeyword, even if the event is not intended for Event Log. Events with keyword 0 cannot be filtered efficiently and will be delivered to Event Log only to be discarded. If Event Log is listening for any events from your provider, any event with Keyword 0 will unnecessarily increase Event Log overhead.

Example of a TraceLogging event for Event Log:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

Additional user-specified keywords can be added to events if appropriate, either by using multiple TraceLoggingKeyword arguments or by specifying multiple keywords in a single TraceLoggingKeyword argument, e.g. TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps only]
Minimum supported server	Windows Server 2012 R2
Target Platform	Windows
Header	traceloggingprovider.h

Share via