EventActivityIdControl function (evntprov.h)

Article
05/26/2022

Creates, queries, and sets activity identifiers for use in ETW events.

Syntax

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Parameters

[in] ControlCode

A control code that specifies the operation to perform.

EVENT_ACTIVITY_CTRL_GET_ID

Sets the ActivityId parameter to the value of the current thread's activity ID.
EVENT_ACTIVITY_CTRL_SET_ID

Sets the current thread's activity ID to the value of the ActivityId parameter.
EVENT_ACTIVITY_CTRL_CREATE_ID

Sets the ActivityId parameter to the value of a newly-generated locally-unique activity ID.
EVENT_ACTIVITY_CTRL_GET_SET_ID

Swaps the values of the ActivityId parameter and the current thread's activity ID. (Saves the value of the current thread's activity ID, then sets the current thread's activity ID to the value of the ActivityId parameter, then sets the ActivityId parameter to the saved value.)
EVENT_ACTIVITY_CTRL_CREATE_SET_ID

Sets the ActivityId parameter to the value of the current thread's activity ID, then sets the current thread's activity ID to the value of a newly-generated locally-unique activity ID.

[in, out] ActivityId

A pointer to a buffer that contains a 128-bit activity ID. This buffer may be read-from and/or written-to, depending on the value of the ControlCode parameter.

Return value

Returns ERROR_SUCCESS if successful.

Remarks

ETW events written using one of the EventWrite APIs will contain a 128-bit "activity ID" field and can optionally contain a 128-bit "related activity ID" field. Trace processing tools can use the values of these fields to organize events into groups called activities.

All events with an activity ID of zero (i.e. GUID_NULL) are assumed to not be a part of any activity.
All events that have a particular non-zero activity ID are assumed to be a part of the same activity.
To indicate the beginning of the activity, the provider should set Opcode to WINEVENT_OPCODE_START for the first event with a particular non-zero activity ID (the start event). If the activity is logically nested within another activity, the provider should set the start event's related activity ID field to the ID of the parent activity.
To indicate the end of the activity, the provider should set Opcode to WINEVENT_OPCODE_STOP for the last event with a particular non-zero activity ID (the stop event).

For activity IDs to be useful, newly-generated activity IDs must be locally-unique, i.e. the same ID must not be generated twice within the trace.

You can create activity IDs using EventActivityIdControl, which generates locally-unique IDs that are guaranteed to be unique across all processes on the local system until the system reboots. You can also use a GUID (globally-unique identifier) as an activity ID. You can create a GUID using an API such as UuidCreate.

User-mode threads have a thread-local 128-bit activity ID value (the thread's activity ID). The thread activity ID is initialized to 0 (i.e. GUID_NULL) when the thread is created. The thread activity ID can be read or updated using EventActivityIdControl. The thread activity ID will be used as the activity ID for all events written by EventWrite and for all events written by EventWriteTransfer or EventWriteEx where the ActivityId parameter is NULL.

Important

A function that alters a thread's activity ID should be careful to restore the original activity ID before exiting. Otherwise, the function's changes to the thread's activity ID will interfere with the activities of components that call the function.

Using an explicitly-specified activity ID

In cases where your activities are not limited to a single thread or where you want to avoid the possibility of interference from other components overwriting your thread's activity ID, you may want to explicitly specify event activities via the ActivityId field of EventWriteTransfer or EventWriteEx instead of using the automatic thread activity ID.

If using manifests and Message Compiler to write events, the macros generated by MC.exe -um use the thread's activity ID while the macros generated by MC.exe -km support an activity ID parameter. Originally, the -um macros only worked in user-mode, and the -km macros only worked in kernel-mode, so user-mode code could only use the current thread's activity ID. However, starting with MC.exe version 10.0.17741, the macros generated by MC.exe -km can be used for both user-mode and kernel-mode, so you can use MC.exe -km to generate macros that accept an activity ID parameter. (The MC-generated code does not support setting an event's related activity ID.)

If using TraceLoggingProvider.h to write events, the TraceLoggingWrite macro uses the thread's activity ID, while the TraceLoggingWriteActivity accepts parameters for activity ID and related activity ID. Alternatively, you can use the C++ classes in TraceLoggingActivity.h for your TraceLogging 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	evntprov.h
Library	Advapi32.lib
DLL	Advapi32.dll

Share via