TraceQueryInformation

This function gets information about Event Trace for Windows (ETW) in general or about a trace session.

Declaration

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

Parameters

The SessionHandle argument selects a trace session, also known as an event logger, to query. Some information classes query ETW in general and require that this argument be zero.

The InformationClass argument tells what sort of information is sought. What the function puts into this buffer depends on the information class.

The TraceInformation and InformationLength arguments are respectively the address and size (in bytes) of a buffer that is to receive the information. For one information class, the function expects input from the buffer too. For another, the TraceInformation argument can be NULL and the InformationLength argument is then ignored.

The ReturnLength argument is the address of a variable whose value on output tells how much information, in bytes, the successful function has put into the buffer or may tell how much the failed function might have put into the buffer (had the buffer been large enough). This argument can be NULL if the caller does not want to know how much information is produced or is available.

Return Value

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

Availability

The TraceQueryInformation function is exported from ADVAPI32 in version 6.2 and higher, as a forward to KERNELBASE. In version 6.3 and higher, it is forwarded instead to the API Set api-ms-win-eventing-controller-l1-1-0 and is implemented in SECHOST.

Documentation Status

The TraceQueryInformation 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 information that may be produced it neglects to describe the format.

Behaviour

The function supports the following information classes:

Value Name Versions
0x04 TraceSystemTraceEnableFlagsInfo 6.2 and higher
0x05 TraceSampledProfileIntervalInfo 6.2 and higher
0x07 TraceProfileSourceListInfo 6.2 and higher
0x0B TraceVersionInfo 10.0 and higher
0x0E TraceDisallowListQuery 10.0 and higher

Given any other, the function returns ERROR_NOT_SUPPORTED.

All remaining behaviour varies with the information class. They have similar elements to their treatment. This allows some shorthands. Notably, where the descriptions below say simply that the function sets the return length, it’s left as understood that what gets set is the variable at the address given by ReturnLength if the latter is not NULL.

The essential handling for most information classes is to query the kernel through the NtQuerySystemInformation function, giving its information class SystemPerformanceTraceInformation (0x1F). The kernel has its own expectation for its information buffer as both input and output. 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, the kernel’s input continues with the SessionHandle, unchanged, and then an allowance for output. The kernel’s output, on success, is copied to the function’s information buffer and becomes the function’s output. 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.

TraceSystemTraceEnableFlagsInfo (0x04)

The information class TraceSystemTraceEnableFlagsInfo reports which groups of kernel events are enabled for the given trace session. Note that the trace session will need to be an NT Kernel Logger session.

The information buffer is to receive 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. However, eight are presently meaningful. Altogether they make a PERFINFO_GROUPMASK. The function sets the return length to the size of this structure. If the information buffer is too small for the structure, the function returns ERROR_BAD_LENGTH.

The array of group masks is obtained from 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 from which it extracts the EventTraceGroupMasks as the whole of the function’s own output.

TraceSampledProfileIntervalInfo (0x05)

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 as both input and output. This structure has a C-language definition in EVNTRACE.H:

Offset Definition Remarks
0x00
ULONG Source;
input
0x04
ULONG Interval;
output

The function sets the return length to the size of this structure. If the information buffer is not an exact fit, the function returns ERROR_BAD_LENGTH.

If the Source on input is zero, the function gets the Interval from the kernel’s information class EventTraceTimeProfileInformation (0x03). The kernel receives an EVENT_TRACE_TIME_PROFILE_INFORMATION structure from which the function extracts the ProfileInterval as the Interval within the function’s output.

A non-zero Source on input takes values from the KPROFILE_SOURCE enumeration. This has a C-language definition in WDM.H from the Windows Driver Kit (WDK). The function gets the corresponding interval from the kernel as output from the NtQueryIntervalProfile function, having given the Source as input.

TraceProfileSourceListInfo (0x07)

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

The information buffer, if given, is to receive some number of irregularly spaced fixed-size PROFILE_SOURCE_INFO structures. The spacing is irregular because each such fixed-size structure can be followed by variable-size data. This structure has a C-language definition in EVENTRACE.H:

Offset Definition
0x00
ULONG NextEntryOffset;
0x04
ULONG Source;
0x08
ULONG MinInterval;
0x0C
ULONG MaxInterval;
0x10
ULONG64 Reserved;
0x18
WCHAR Description [ANYSIZE_ARRAY];

The function gets its output from the kernel’s information class EventTraceProfileSourceListInformation (0x0D). The kernel receives an EVENT_TRACE_PROFILE_LIST_INFORMATION structure as a fixed-size header for the variable-size data. Because the size is not known in advance, the function double-buffers. Failure to get sufficient memory is failure for the function, wich returns ERROR_OUTOFMEMORY. The function can be given no information buffer as a way to determine how big a buffer might have sufficed and which might still suffice if the call is repeated. (Expression of detail still to be sorted out!)

TraceVersionInfo (0x0B)

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_VERSION_INFO structure for the function to fill. This structure has a C-language definition in EVNTRACE.H:

Offset Definition
0x00
UINT EtwTraceProcessingVersion;
0x04
UINT Reserved;

The function sets the return length to the size of this structure. If the information buffer is not an exact fit, the function returns ERROR_BAD_LENGTH.

The function itself chooses the EtwTraceProcessingVersion for the output. Presently, this is 1. The Reserved member is ignored.

TraceDisallowListQuery (0x0E)

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