StartKernelTrace function

The StartKernelTrace function registers and starts a kernel event tracing session. Also, you can enable stack walking for certain kernel events using StartKernelTrace.


WINAPI StartKernelTrace(
  __out    PTRACEHANDLE TraceHandle,
  __inout  PEVENT_TRACE_PROPERTIES Properties,
  __in     STACK_TRACING_EVENT_ID StackTracingEventIds[],
  __in     ULONG cStackTracingEventIds


TraceHandle [out]

Stores a handle to an event tracing session. TraceHandle is set to zero if the handle is not valid. TraceHandle should not be compared to INVALID_HANDLE_VALUE. Do not use this handle if the function fails.

Properties [in, out]

Stores a pointer to an EVENT_TRACE_PROPERTIES structure. EVENT_TRACE_PROPERTIES configures certain aspects of session behavior.

For more information about the format of this parameter, see Formatting the Properties Parameter.

StackTracingEventIds [in]

An array of STACK_TRACING_EVENT_ID entries, where each entry specifies the type of events on which to enable stack walking.

For more information about the format of this parameter, see Formatting the StackTracingEventIds Parameter.

cStackTracingEventIds [in]

The number of STACK_TRACING_EVENT_ID entries in the StackTracingEventIds parameter.

Return value

StartKernelTrace returns ERROR_SUCCESS if the call was successful.

Possible error return values include:

Return codeDescription

Possibly indicates that Wnode.Guid does not correspond to SystemTraceControlGuid or KernelRundownGuid. Also, this error return value possibly indicates the number of cStackTracingEventIds is greater than 256.

Note  Starting with Windows Vista, kernel-mode WPT/ETW only supports 16 stack tracing event IDs. In the case where there are more than 16 stack tracing event IDs, the error for too many stack tracing event IDs is detected and returned by StartTrace rather than StartKernelTrace.


Possibly indicates that there are invalid trace flags in Properties.EnableFlags.


Possibly indicates failure to allocate memory for EVENT_TRACE_PROPERTIES.


Only a single instance of Kernel logger runs on the system. If StartKernelTrace attempts to start after another component has started kernel logging, this error is possibly returned.


If the function fails for a reason other than those listed, a system error code is returned. For more information about system error codes, see System Error Codes.


For more information about how to configure symbol decoding, see Symbol Support.



Available in Windows Vista and later versions of the Windows operating system. This function is distributed with the Windows Performance Analyzer.


KernelTraceControl.h (include KernelTraceControl.h or Evntrace.h)


Contained in KernelTraceControl.dll.

See also




Send comments about this topic to Microsoft

Build date: 5/5/2012