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

Depending on the type of log file you choose to create, you may also need to specify a value for MaximumFileSize. See the Remarks section for more information on setting the Properties parameter and the behavior of the session.

Starting with Windows 10, version 1703:  For better performance in cross process scenarios, you can now pass filtering in to StartTrace when starting system wide private loggers. You will need to pass in the new EVENT_TRACE_PROPERTIES_V2 structure to include filtering information. See Configuring and Starting a Private Logger Session for more details.

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.

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.

Windows Server 2003:  You can start more than one session with the same session GUID.

For the logger to be a system logger and receive events from SystemTraceProvider, any of the following must be true:

• The Properties member Wnode.Guid is set to SystemTraceControlGuid or GlobalLoggerGuid.
• The Properties member LogFileMode includes the EVENT_TRACE_SYSTEM_LOGGER_MODE flag.
• SessionName is set to KERNEL_LOGGER_NAME.

Because system loggers receive special kernel events, they are subject to additional restrictions:

• There can be no more than 8 system loggers active on the same system.
• System loggers cannot be created within a Windows Server container.
• System loggers cannot use the EVENT_TRACE_USE_PAGED_MEMORY flag.
• Prior to Windows 10, version 1703, no more than 2 distinct clock types can be used simultaneously by any system loggers. For example, if one active system logger is using the "CPU cycle counter" clock type, and another active system logger is using the "Query performance counter" clock type, then any attempt to start a system logger using the "System time" clock type will fail because it would require the activation of a third clock type. Because of this limitation, Microsoft strongly recommends that system loggers do not use the "System time" clock type.
• Starting with Windows 10, version 1703, the clock type restriction has been removed. All three clock types can now be used simultaneously by system loggers.

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.

Examples

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

Requirements

See also

ControlTrace

EVENT_TRACE_PROPERTIES