ControlTrace function

The ControlTrace function flushes, queries, updates, or stops the specified event tracing session.

Syntax


ULONG ControlTrace(
  _In_     TRACEHANDLE SessionHandle,
  _In_     LPCTSTR SessionName,
  _Inout_  PEVENT_TRACE_PROPERTIES Properties,
  _In_     ULONG ControlCode
);

Parameters

SessionHandle [in]

Handle to an event tracing session, or NULL. You must specify SessionHandle if SessionName is NULL. However, ETW ignores the handle if SessionName is not NULL. The handle is returned by the StartTrace function.

SessionName [in]

Name of an event tracing session, or NULL. You must specify SessionName if SessionHandle is NULL.

To specify the NT Kernel Logger session, set SessionName to KERNEL_LOGGER_NAME.

Properties [in, out]

Pointer to an initialized EVENT_TRACE_PROPERTIES structure. This structure should be zeroed out before it is used.

If ControlCode specifies EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY or EVENT_TRACE_CONTROL_FLUSH, you only need to set the Wnode.BufferSize, Wnode.Guid, LoggerNameOffset, and LogFileNameOffset members of the EVENT_TRACE_PROPERTIES structure. If the session is a private session, you also need to set LogFileMode. You can use the maximum session name (1024 characters) and maximum log file name (1024 characters) lengths to calculate the buffer size and offsets if not known.

If ControlCode specifies EVENT_TRACE_CONTROL_UPDATE, on input, the members must specify the new values for the properties to update. On output, Properties contains the properties and statistics for the event tracing session. You can update the following properties.

MemberUse
EnableFlagsSet this member to 0 to disable all kernel providers. Otherwise, you must specify the kernel providers that you want to enable or keep enabled. Applies only to NT Kernel Logger sessions.
FlushTimerSet this member if you want to change the time to wait before flushing buffers. If this member is 0, the member is not updated.
LogFileNameOffsetSet this member if you want to switch to another log file. If this member is 0, the file name is not updated. If the offset is not zero and you do not change the log file name, the function returns an error.
LogFileModeSet this member if you want to turn EVENT_TRACE_REAL_TIME_MODE on and off. To turn real time consuming off, set this member to 0. To turn real time consuming on, set this member to EVENT_TRACE_REAL_TIME_MODE and it will be OR'd with the current modes.
MaximumBuffersSet this member if you want to change the maximum number of buffers that ETW uses. If this member is 0, the member is not updated.

 

For private logger sessions, you can update only the LogFileNameOffset and FlushTimer members.

If you are using a newly initialized EVENT_TRACE_PROPERTIES structure, the only members you need to specify, other than the members you are updating, are Wnode.BufferSize, Wnode.Guid, and Wnode.Flags.

If you use the property structure you passed to StartTrace, make sure the LogFileNameOffset member is 0 unless you are changing the log file name.

If you call the ControlTrace function to query the current session properties and then update those properties to update the session, make sure you set LogFileNameOffset to 0 (unless you are changing the log file name) and set EVENT_TRACE_PROPERTIES.Wnode.Flags to WNODE_FLAG_TRACED_GUID.

ControlCode [in]

Requested control function. You can specify one of the following values.

ValueMeaning
EVENT_TRACE_CONTROL_FLUSH

Flushes the session's active buffers. Typically, you do not need to flush buffers yourself. However, you may want to flush buffers if the event rate is low and you are delivering events in real time.

Windows 2000:  This value is not supported.

EVENT_TRACE_CONTROL_QUERY

Retrieves session properties and statistics.

EVENT_TRACE_CONTROL_STOP

Stops the session. The session handle is no longer valid.

EVENT_TRACE_CONTROL_UPDATE

Updates the session properties.

 

Note that it is not safe to flush buffers or stop a trace session from DllMain.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following table includes some common errors and their causes.

Return codeDescription
ERROR_BAD_LENGTH

One of the following is true:

  • The Wnode.BufferSize member of Properties specifies an incorrect size.
  • Properties does not have sufficient space allocated to hold a copy of the session name and log file name (if used).
ERROR_INVALID_PARAMETER

One of the following is true:

  • Properties is NULL.
  • SessionName and SessionHandle are both NULL.
  • The LogFileNameOffset member of Properties is not valid.
  • The LoggerNameOffset member of Properties is not valid.
  • The LogFileMode member of Properties specifies a combination of flags that is not valid.
  • The Wnode.Guid member of Properties is SystemTraceControlGuid, but the SessionName parameter is not KERNEL_LOGGER_NAME.
ERROR_BAD_PATHNAME

Another session is already using the file name specified by the LogFileNameOffset member of the Properties structure.

ERROR_MORE_DATA

The buffer for EVENT_TRACE_PROPERTIES is too small to hold all the information for the session. If you do not need the session's property information, you can ignore this error. If you receive this error when stopping the session, ETW will have already stopped the session before generating this error.

ERROR_ACCESS_DENIED

Only users running with elevated administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can control event tracing sessions. To grant a restricted user the ability to control trace sessions, add them to the Performance Log Users group. Only users with administrative privileges and services running as LocalSystem can control an NT Kernel Logger session.

Windows XP and Windows 2000:  Anyone can control a trace session.

ERROR_WMI_INSTANCE_NOT_FOUND

The given session is not running.

 

Remarks

Event trace controllers call this function.

This function supersedes the FlushTrace, QueryTrace, StopTrace, and UpdateTrace functions.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

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, Windows Server 2008 R2, Windows Server 2008, Windows Vista, and Windows XP

DLL

Sechost.dll on Windows 8.1 and Windows Server 2012;
Advapi32.dll on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, and Windows XP

Unicode and ANSI names

ControlTraceW (Unicode) and ControlTraceA (ANSI)

See also

EVENT_TRACE_PROPERTIES
QueryAllTraces
StartTrace

 

 

Community Additions

ADD
Show:
© 2014 Microsoft