TraceLoggingWriteActivity macro (traceloggingprovider.h)

Article
06/10/2022

Emits a TraceLogging event with specified activity IDs.

Syntax

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [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] pActivityId

The activity ID for the event, or NULL to use the default.

[in, optional] pRelatedActivityId

The related activity ID for the event, or NULL for no related activity ID.

[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.

Important

ProviderId, Level and Keyword are the primary means for filtering events. Other kinds of filtering are possible but have much higher overhead. Always assign a non-zero level and keyword to every event.

Return value

None

Remarks

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

TraceLoggingWriteActivity checks whether the specified provider is registered. If the provider is not registered, TraceLoggingWriteActivity does nothing.
TraceLoggingWriteActivity checks whether any consumer is listening for the event, as if by calling TraceLoggingProviderEnabled. If no consumer is listening for the event, TraceLoggingWriteActivity does nothing.
Otherwise, TraceLoggingWriteActivity 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.
The event's activity ID will come from the pActivityId parameter. If pActivityId is NULL, user-mode events will use the thread's implicit activity ID and kernel-mode events will use GUID_NULL.
The event's related activity ID will come from the pRelatedActivityId parameter. If pRelatedActivityId is 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:

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

An invocation of TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, 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, aid, rid, N, data);
}

Note

Each TraceLoggingWriteActivity macro automatically checks TraceLoggingProviderEnabled so the event will only be written if a consumer is listening for events from the provider. As a result, it is usually unnecessary to directly call TraceLoggingProviderEnabled. Any runtime expressions in args... will be evaluated if and only if the event is enabled. Runtime expressions will not be evaluated more than once.

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 TraceLoggingWriteActivity macro expands to a line longer than can be supported by the compiler. If this happens you will need to simplify your event.

The TraceLoggingWriteActivity 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).

Important

Try to avoid large events. ETW is primarily designed for handling small events. TraceLoggingWriteActivity will silently drop any event that is too large. The event's size is based on the total of the event's headers (added by the ETW runtime), metadata (i.e. provider name, event name, field names, field types), and data (field values). If the event's total size is greater than 65535 or if the consumer session is using a buffer size smaller than the event's size, the event will not be recorded.

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.

See EventWriteTransfer for information about the semantics of the ActivityId and RelatedActivityId parameters.

See EventActivityIdControl for information about writing activities in ETW.

See TraceLoggingActivity for C++ classes that help manage TraceLogging ETW activities.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	traceloggingprovider.h
Library	Advapi32.lib