StartHeapTrace

This function registers and starts a heap tracing session for a set of specified PIDs. You can also enable stack walking for certain heap events such as allocation or deletion using this function.

The process for which heap tracing is to be enabled must be created before calling this function. In order to capture heap events from the very start of the program, it is advisable that the process be started with the CREATE_SUSPENDED flag, then heap tracing enabled for its PID, then the process resumed.

Heap tracing is very verbose and can quickly generate a very large trace file. Events may be lost easily if the session’s buffers are too small or too few. It is recommended that the number of processes for which heap tracing is enabled be limited in order to not lose events. Enabling heap tracing may have a performance impact on the process being traced.

ULONG
WINAPI
StartHeapTrace(
    _Out_ PTRACEHANDLE TraceHandle,
    _Inout_ PEVENT_TRACE_PROPERTIES Properties,
    _In_z_ LPCWSTR wszSessionName,
    _In_reads_opt_(cPids) const ULONG Pids[],
    _In_  ULONG cPids,
    _In_reads_opt_(cStackTracingEventIds) const STACK_TRACING_EVENT_ID StackTracingEventIds[],
    _In_  ULONG cStackTracingEventIds
    );

Parameters

TraceHandle [out]
Stores a handle to an event tracing session. This parameter is set to zero if the handle is not valid. This parameter 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.

It is not necessary to set the Guid member because this function always uses the its own value. If you do specify a GUID it will not be used.

wszSessionName [in]
SThe session name to pass to StartTrace.

Pids [in]
An array of process IDs to enable heap tracing on.

cPids [in]
The size of the Pids array.

cStackTracingEventIds [in]
The size of the StackTracingEventIds array.

Return Value

ERROR_SUCCESS indicates success.

Possible error values are described in the following table.

Error Value	Description
ERROR_ALREADY_EXISTS	Only a single instance of the kernel logger runs on the system. If this function attempts to start after another component has started kernel logging, this error is possibly returned.
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.

If the function fails for a reason other than those listed, a system error code is returned.

Remarks

None

Related topics

Functions

UpdateHeapTrace