StartKernelTrace function

Article
05/31/2018

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

Syntax

ULONG
WINAPI StartKernelTrace(
  _Out_   PTRACEHANDLE            TraceHandle,
  _Inout_ PEVENT_TRACE_PROPERTIES Properties,
  _In_    STACK_TRACING_EVENT_ID  StackTracingEventIds[],
  _In_    ULONG                   cStackTracingEventIds
);

Parameters

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 code	Description
ERROR_INVALID_PARAMETER	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](/windows/win32/api/evntrace/nf-evntrace-starttracea) rather than StartKernelTrace.
ERROR_INVALID_FLAGS	Possibly indicates that there are invalid trace flags in Properties.EnableFlags.
ERROR_OUT_OF_MEMORY	Possibly indicates failure to allocate memory for EVENT_TRACE_PROPERTIES.
ERROR_ALREADY_EXISTS	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.

Remarks

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

Requirements


Version	Available in Windows Vista and later versions of the Windows operating system. This function is distributed with the Windows Performance Analyzer.
Header	KernelTraceControl.h (include KernelTraceControl.h or Evntrace.h)
Library	KernelTraceControl.dll

Share via