TraceLoggingWriteActivity macro (traceloggingprovider.h)

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.

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);
}

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

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

See also

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

TraceLogging Wrapper Macros