Export (0) Print
Expand All

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.

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 codeDescription
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 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

Contained in KernelTraceControl.dll.

See also

StartTrace
EVENT_TRACE_PROPERTIES
STACK_TRACING_EVENT_ID

 

 

Send comments about this topic to Microsoft

Build date: 5/5/2012

Show:
© 2014 Microsoft