TraceLoggingWrite macro (traceloggingprovider.h)

Emits a TraceLogging event.

Syntax

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

Parameters

[in] hProvider

The handle of the TraceLogging provider to use for writing the event.

[in] eventName

A short and unique name to use for identifying the event. This must be a string literal and not a variable. It cannot have any embedded '\0' characters.

[in, optional] __VA_ARGS__

Up to 99 additional parameters to configure or add fields to the event. Each parameter must be one of the TraceLogging Wrapper Macros, such as TraceLoggingLevel, TraceLoggingKeyword, or TraceLoggingValue.

Return value

None

Remarks

Each invocation of the TraceLoggingWrite macro expands to the code necessary to write an event to ETW through the specified provider handle.

• TraceLoggingWrite checks whether the specified provider is registered. If the provider is not registered, TraceLoggingWrite does nothing.
• TraceLoggingWrite checks whether any consumer is listening for the event, as if by calling TraceLoggingProviderEnabled. If no consumer is listening for the event, TraceLoggingWrite does nothing.
• Otherwise, TraceLoggingWrite evaluates the runtime expressions specified in the arguments, saves the results, packs the necessary data into an event, and calls EventWriteTransfer to send the event to ETW.

The generated event will be constructed as follows:

• The event's provider ID, provider name, and provider group will come from the hProvider parameter.
• The event's name will come from the eventName parameter.
• In user-mode, the event's activity ID will come from the thread's implicit activity ID. In kernel-mode, the event's activity ID will be GUID_NULL.
• The event will not have a related activity ID.
• The event's level will come from the TraceLoggingLevel argument. If no TraceLoggingLevel argument is present, the event's level will be 5 (WINEVENT_LEVEL_VERBOSE). If more than one TraceLoggingLevel argument is present, the last argument will be used. To enable effective event filtering, always assign a meaningful non-zero level to every event.
• The event's keyword will come from the TraceLoggingKeyword argument. If no TraceLoggingKeyword argument is present, the event's keyword will be 0 (NONE). If more than one TraceLoggingKeyword argument is present, the values will be OR'ed together. To enable effective event filtering, always assign a meaningful non-zero keyword to every event.
• Other event attributes may be set by arguments such as TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag, or TraceLoggingChannel.
• Event fields can be grouped using TraceLoggingStruct.
• Event fields are added by field arguments like TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString, etc. See TraceLogging Wrapper Macros for details.

For example:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

An invocation of TraceLoggingWrite(hProvider, "EventName", args...) can be thought of as expanding to code like the following:

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

If generating complex events, you might get a compiler error indicating that the line is too long or that the compiler is out of heap space. This occurs when the TraceLoggingWrite macro expands to a line longer than can be supported by the compiler. If this happens you will need to simplify your event.

The TraceLoggingWrite macro uses an array of EVENT_DATA_DESCRIPTOR to transfer data to ETW. The maximum number of descriptors accepted by ETW is 128. Since each parameter may require the use of 0, 1, or 2 descriptors, it is possible to hit the data descriptor limit (128) before hitting the argument limit (99).

A call to TraceLoggingWrite is the same as a call to TraceLoggingWriteActivity with NULL for the pActivityId and pRelatedActivityId parameters. Use TraceLoggingWriteActivity if you need to specify activity IDs for an event.

Examples

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Requirements

See also

EventWriteTransfer

TraceLoggingWriteActivity

TraceLogging Wrapper Macros