TraceSetInformation function (evntrace.h)

The TraceSetInformation function configures event tracing session settings.

Syntax

ULONG WMIAPI TraceSetInformation(
  [in] TRACEHANDLE      SessionHandle,
  [in] TRACE_INFO_CLASS InformationClass,
  [in] PVOID            TraceInformation,
  [in] ULONG            InformationLength
);

Parameters

[in] SessionHandle

Handle of the event tracing session to be configured. The StartTrace function returns this handle when a new trace is started. To obtain the handle of an existing trace, use ControlTrace to query the trace properties based on the trace's name and then get the handle from the Wnode.HistoricalContext field of the returned EVENT_TRACE_PROPERTIES data.

[in] InformationClass

The information class to enable or disable. The information that the class captures is included in the extended data section of the event. For a list of information classes that you can enable, see the TRACE_QUERY_INFO_CLASS enumeration.

[in] TraceInformation

A pointer to information class specific data. The information class determines the contents of this parameter.

[in] InformationLength

The size, in bytes, of the data in the TraceInformation buffer.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

  • ERROR_BAD_LENGTH

    The program issued a command but the command length is incorrect. This error is returned if the InformationLength parameter is less than a minimum size.

  • ERROR_INVALID_PARAMETER

    The parameter is incorrect.

  • ERROR_NOT_SUPPORTED

    The request is not supported.

  • Other

    Use FormatMessage to obtain the message string for the returned error.

Remarks

Call this function after calling StartTrace.

If the InformationClass parameter is set to TraceStackTracingInfo, calling this function enables stack tracing of the specified kernel events. Subsequent calls to this function overwrites the previous list of kernel events for which stack tracing is enabled. To disable stack tracing, call this function with InformationClass set to TraceStackTracingInfo and InformationLength set to 0.

The extended data section of the event will include the call stack. The StackWalk_Event MOF class defines the layout of the extended data.

Typically, on 64-bit computers, you cannot capture the kernel stack in certain contexts when page faults are not allowed. To enable walking the kernel stack on x64, set the DisablePagingExecutive Memory Management registry value to 1. The DisablePagingExecutive registry value is located under the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management. This should only be done for temporary diagnosis purposes because it increases memory usage of the system.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header evntrace.h
Library Sechost.lib on Windows 8.1 and Windows Server 2012 R2; Advapi32.lib on Windows 8, Windows Server 2012, Windows 7 and Windows Server 2008 R2
DLL Sechost.dll on Windows 8.1 and Windows Server 2012 R2; Advapi32.dll on Windows 8, Windows Server 2012, Windows 7 and Windows Server 2008 R2

See also

TRACE_QUERY_INFO_CLASS

TraceQueryInformation