StartTrace function

The StartTrace function registers and starts an event tracing session.

Syntax


ULONG StartTrace(
  _Out_    PTRACEHANDLE SessionHandle,
  _In_     LPCTSTR SessionName,
  _Inout_  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

SessionHandle [out]

Handle to the event tracing session.

Do not use this handle if the function fails. Do not compare the session handle to INVALID_HANDLE_VALUE; the session handle is 0 if the handle is not valid.

SessionName [in]

Null-terminated string that contains the name of the event tracing session. The session name is limited to 1,024 characters, is case-insensitive, and must be unique.

Windows 2000:  Session names are case-sensitive. As a result, duplicate session names are allowed. However, to reduce confusion, you should make sure your session names are unique.

This function copies the session name that you provide to the offset that the LoggerNameOffset member of Properties points to.

Properties [in, out]

Pointer to an EVENT_TRACE_PROPERTIES structure that specifies the behavior of the session. The following are key members of the structure to set:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

If SessionName is KERNEL_LOGGER_NAME, you must also set EnableFlags. Depending on the type of log file you choose to create, you may also need to specify a value for MaximumFileSize.

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 SessionName.
ERROR_INVALID_PARAMETER

One of the following is true:

  • Properties is NULL.
  • SessionHandle is 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 is SystemTraceControlGuid, but the SessionName parameter is not KERNEL_LOGGER_NAME.

    Windows 2000:  This case does not return an error.

ERROR_ALREADY_EXISTS

A session with the same name or GUID is already running.

ERROR_BAD_PATHNAME

You can receive this error for one of the following reasons:

  • Another session is already using the file name specified by the LogFileNameOffset member of the Properties structure.
  • Both LogFileMode and LogFileNameOffset are zero.
ERROR_DISK_FULL

There is not enough free space on the drive for the log file. This occurs if:

  • MaximumFileSize is nonzero and there is not MaximumFileSize bytes available for the log file
  • the drive is a system drive and there is not an additional 200 MB available
  • MaximumFileSize is zero and there is not an additional 200 MB available

Choose a drive with more space, or decrease the size specified in MaximumFileSize (if used).

Windows 2000:  Does not require an additional 200 MB available disk space.

ERROR_ACCESS_DENIED

Only users with 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.

If the user is a member of the Performance Log Users group, they may not have permission to create the log file in the specified folder.

 

Remarks

Event trace controllers call this function.

The session remains active until you stop the session, the computer is restarted or the maximum file size is reached for non-circular logs. To stop an event tracing session, call the ControlTrace function and set the ControlCode parameter to EVENT_TRACE_CONTROL_STOP.

You cannot start more than one session with the same session GUID.

Prior to Windows Vista:  You can start more than one session with the same session GUID.

To specify an NT Kernel Logger session, set SessionName to KERNEL_LOGGER_NAME and the Wnode.Guid member of Properties to SystemTraceControlGuid. If you do not specify the GUID as SystemTraceControlGuid, ETW will override the GUID value and set it to SystemTraceControlGuid.

Windows 2000:  To start the kernel session, the session name must be KERNEL_LOGGER_NAME and the Guid must be SystemTraceControlGuid.

To specify a private logger session, set Wnode.Guid member of Properties to the provider's control GUID, not the private logger session's control GUID. The provider must have registered the GUID before you call StartTrace.

You do not use this function to start a global logger session. For details on starting a global logger session, see Configuring and Starting the Global Logger Session.

Windows Phone 8.1: This API is supported.

Examples

For an example that uses StartTrace, see Configuring and Starting an Event Tracing Session.

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 R2;
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

StartTraceW (Unicode) and StartTraceA (ANSI)

See also

ControlTrace
EVENT_TRACE_PROPERTIES

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.