TraceQueryInformation

This function gets information about Event Tracing 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);

The TRACE_INFO_CLASS enumeration is also named TRACE_QUERY_INFO_CLASS.

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.

The TraceInformation and InformationLength arguments are respectively the address and size (in bytes) of a buffer that is to receive the information. What the function puts into this buffer depends on the information class. 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 does not present the format.

Behaviour

The function supports the following information classes:

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 it sets 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, specifically through that function’s 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, 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 then an allowance for output. The kernel’s output, on success, is copied to the TraceQueryInformation 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, which must 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 has placed the SessionHandle as the TraceHandle. On success, the function 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:

ULONG Source;

ULONG Interval;

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 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 on input is ProfileTime (0), 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.

For non-zero values of Source, the function gets the corresponding interval from the kernel as output from the NtQueryIntervalProfile function, having passed the Source through 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 EVNTRACE.H:

ULONG NextEntryOffset;

ULONG Source;

ULONG MinInterval;

ULONG MaxInterval;

ULONG64 Reserved;

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:

UINT EtwTraceProcessingVersion;

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.