TraceSetInformation

This function sets properties for Event Tracing for Windows (ETW) in general or for a trace session.

Declaration

ULONG 
TraceQueryInformation (
    TRACEHANDLE SessionHandle, 
    TRACE_INFO_CLASS InformationClass, 
    PVOID TraceInformation, 
    ULONG InformationLength);

Parameters

The SessionHandle argument selects a trace session, also known as an event logger, to configure.

The InformationClass argument tells what sort of information is being set.

The TraceInformation and InformationLength arguments are respectively the address and size (in bytes) of a buffer that provides the information. What the function expects of this buffer depends on the information class. For some information classes, InformationLength can be zero and then TraceInformation may need to be NULL.

Return Value

The function returns ERROR_SUCCESS if successful, else a non-zero error code.

Availability

The TraceSetInformation function is exported from ADVAPI32 in version 6.1 and higher. Starting with version 6.2, however, the implementation in ADVAPI32 is just a stub for calling the true implementation via the API Set api-ms-win-eventing-controller-l1-1-0.dll.

Documentation Status

The TraceSetInformation function is documented. However, for most of the information classes the documentation is essentially useless since although it sketches (not always accurately) the purpose of the expected information it does not present the format.

Behaviour

The following implementation notes are from inspection of SECHOST from the original release of Windows 10 only. They may some day get revised to account for earlier versions. Meanwhile, where anything is added about earlier versions, take it not as an attempt at comprehensiveness but as a bonus from my being unable to resist a trip down memory lane or at least a quick look into the history.

The function supports the following information classes:

Given any other, the function returns ERROR_NOT_SUPPORTED.

All remaining behaviour varies with the information class. The essential handling for most is to call the kernel through the NtSetSystemInformation function, specifically through that function’s information class SystemPerformanceTraceInformation (0x1F). The kernel has its own expectation for its information buffer. The first dword of input is yet another information class, specifically the EVENT_TRACE_INFORMATION_CLASS, which is described below as the kernel’s information class. Typically, this input to the kernel continues with the SessionHandle, unchanged, and with data that is copied from or adapted from the function’s information buffer. Failure of this call to the kernel is failure for the function. The many reasons that the kernel may reject the call are not discussed here.

TraceStackTracingInfo (0x03)

The information class TraceStackTracingInfo specifies which NT Kernel Logger events are to have call-stack tracing information added whenever the event is sent to the given trace session.

The information buffer must provide an array of CLASSIC_EVENT_ID structures. This documented structure has a C-language definition in EVNTRACE.H:

GUID EventGuid;

UCHAR Type;

UCHAR Reserved [7];

If the information buffer is not an exact fit for a whole number of such structures or if the number exceeds 256, the function returns ERROR_INCORRECT_SIZE. The information buffer can be empty but then its address must be NULL, else the function returns ERROR_INVALID_PARAMETER.

Each structure in the array describes one event. The EventGuid and the Type together select a hook ID, which is a 16-bit identifier for each type of event that can be sent to an NT Kernel Logger session. The EventGuid selects the high byte, the Type becomes the low. If the EventGuid is not valid for this purpose, then the corresponding CLASSIC_EVENT_ID is simply ignored.

The valid hook IDs are sent to the kernel’s information class EventTraceStackTracingInformation (0x06). The kernel’s information buffer is an EVENT_TRACE_SYSTEM_EVENT_INFORMATION structure that contains the SessionHandle as the TraceHandle and to which the valid hook IDs, as interpreted from the function’s information buffer but extended from 16 to 32 bits, are appended as the HookId array. If the function cannot get memory for the kernel’s information buffer, it returns ERROR_OUTOFMEMORY.

TraceSystemTraceEnableFlagsInfo (0x04)

The information class TraceSystemTraceEnableFlagsInfo specifies which groups of NT Kernel Logger events to enable for the given trace session.

The information buffer must provide an array of 32-bit group masks. The first is compatible with the EnableFlags that are documented for the EVENT_TRACE_PROPERTIES structure that is the input to such functions as StartTrace and ControlTrace. There can be at most eight group masks, which altogether make a PERFINFO_GROUPMASK structure. If the information buffer would provide more or is not an exact fit for a whole number of group masks, the function returns ERROR_INVALID_PARAMETER.

The given group masks are sent to the kernel’s information class EventTraceGroupMaskInformation (0x01). The kernel receives an EVENT_TRACE_GROUPMASK_INFORMATION structure into which the function places the SessionHandle as the TraceHandle and the given group masks as the EventTraceGroupMasks. Each group mask that isn’t specified to the function gets specified to the kernel as zero.

TraceSampledProfileIntervalInfo (0x05)

The information class TraceSampledProfileIntervalInfo sets the interval for profiling a specified source.

The SessionHandle is irrelevant for this information class and must be zero, else the function returns ERROR_INVALID_PARAMETER.

The information buffer must provide exactly a TRACE_PROFILE_INTERVAL structure, else the function returns ERROR_BAD_LENGTH. This structure has a C-language definition in EVNTRACE.H:

ULONG Source;

ULONG Interval;

The Source takes its values from the KPROFILE_SOURCE enumeration. This has a C-language definition in WDM.H from the Windows Driver Kit (WDK). It lists the types of profiling data that the HAL may keep about processor performance. It is presumably also defined in headers that Microsoft does not publish but does make available to its own user-mode programmers: how else does type information for it appear in symbol files for such high-level modules as the URLMON.DLL from Internet Explorer?

If the Source is ProfileTime (0), the function sets the Interval through the kernel’s information class EventTraceTimeProfileInformation (0x03). The kernel receives an EVENT_TRACE_TIME_PROFILE_INFORMATION structure in which the ProfileInterval is the Interval from the function’s input.

For other values of the Source, the function sets the corresponding interval through the NtSetIntervalProfile function.

TraceProfileSourceConfigInfo (0x06)

The information buffer must provide an array of 32-bit profile sources from the KPROFILE_SOURCE enumeration. If the information buffer is not an exact fit for a whole number of such values or if the number exceeds 4, the function returns ERROR_INCORRECT_SIZE. If the number is 0, however, or if the buffer’s address is NULL, the function returns ERROR_INVALID_PARAMETER.

The given profile sources are sent to the kernel’s information class EventTraceProfileConfigInformation (0x0C). The kernel’s information buffer is an EVENT_TRACE_PROFILE_COUNTER_INFORMATION structure that contains the SessionHandle as the TraceHandle and to which the profile sources are appended as the ProfileSource array. If the function cannot get memory for the kernel’s information buffer, it returns ERROR_OUTOFMEMORY.

TracePmcEventListInfo (0x08)

The information class TracePmcEventListInfo specifies which kernel events are to have Performance Monitoring Counter (PMC) information added as an extended data item whenever the event is sent to the given trace session. Note that the trace session will need to be an NT Kernel Logger session. The choice of counters to collect is specified separately, through the information class TracePmcCounterListInfo.

The information buffer must provide an array of CLASSIC_EVENT_ID structures. If the information buffer is not an exact fit for a whole number of such structures or if the number exceeds 4, the function returns ERROR_INCORRECT_SIZE. The information buffer can be empty but then its address must be NULL, else the function returns ERROR_INVALID_PARAMETER.

Each structure in the array describes one kernel event. The EventGuid and the Type together select a hook ID, which is a 16-bit identifier for each type of event that can be sent to an NT Kernel Logger session. The EventGuid selects the high byte, the Type becomes the low. If the EventGuid is not valid for this purpose, then the corresponding CLASSIC_EVENT_ID is simply ignored.

The valid hook IDs are sent to the kernel’s information class EventTraceProfileEventListInformation (0x0E). The kernel receives an EVENT_TRACE_SYSTEM_EVENT_INFORMATION structure that contains the SessionHandle as the TraceHandle and to which the valid hook IDs, as interpreted from the function’s information buffer but extended from 16 to 32 bits, are appended as the HookId array. If the function cannot get memory for the kernel’s information buffer, it returns ERROR_OUTOFMEMORY.

TracePmcCounterListInfo (0x09)

The information class TracePmcCounterListInfo specifies which Performance Monitoring Counters the kernel is to collect as an extended data item whenever an applicable event is sent to the given trace session. Note that the trace session will need to be an NT Kernel Logger session. The applicable events are configured separately, through the information class TracePmcEventListInfo.

The information buffer must provide an array of 32-bit profile sources from the KPROFILE_SOURCE enumeration. If the information buffer is not an exact fit for a whole number of such values or if the number exceeds 4, the function returns ERROR_INCORRECT_SIZE. If the number is 0, however, or if the buffer’s address is NULL, the function returns ERROR_INVALID_PARAMETER.

The given profile sources are sent to the kernel’s information class EventTraceProfileCounterListInformation (0x0F). The kernel’s information buffer is an EVENT_TRACE_PROFILE_COUNTER_INFORMATION structure that contains the SessionHandle as the TraceHandle and to which the profile sources are appended as the ProfileSource array. If the function cannot get memory for the kernel’s information buffer, it returns ERROR_OUTOFMEMORY.

TraceSetDisallowList (0x0A)

This information class is unusual in that it is implemented in terms of NtTraceControl, specifically for its function code 0x1C. Microsoft’s name for this is not known. Notes on NtTraceControl are in preparation.