StartHeapTrace

  • 發行項

此函式會註冊並啟動一組指定 PID 的堆積追蹤會話。 您也可以針對某些堆積事件啟用堆疊逐步解說，例如使用此函式進行配置或刪除。

必須先建立要啟用堆積追蹤的程式，才能呼叫此函式。 若要從程式的開頭擷取堆積事件，建議您從 CREATE_SUSPENDED 旗標開始程式，然後針對其 PID 啟用堆積追蹤，然後繼續程式。

堆積追蹤非常詳細資訊，而且可以快速產生非常大的追蹤檔案。 如果會話的緩衝區太小或太少，事件可能會很容易遺失。 建議啟用堆積追蹤的進程數目受到限制，以免遺失事件。 啟用堆積追蹤可能會對所追蹤的進程造成效能影響。

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

參數

TraceHandle [out]
儲存事件追蹤會話的控制碼。 如果控制碼無效，此參數會設定為零。 此參數不應與INVALID_HANDLE_VALUE進行比較。 如果函式失敗，請勿使用此控制碼。

屬性 [in， out]
儲存 EVENT_TRACE_PROPERTIES 結構的指標。 EVENT_TRACE_PROPERTIES設定會話行為的某些層面。

不需要設定 Guid 成員，因為此函式一律會使用自己的值。 如果您指定 GUID，則不會使用它。

wszSessionName [in]
要傳遞至 StartTrace 的會話名稱。

Pids [in]
要啟用堆積追蹤的進程識別碼陣列。

cPids [in]
Pids 陣列的大小。

cStackTracingEventIds [in]
StackTracingEventIds 陣列的大小。

傳回值

ERROR_SUCCESS表示成功。

下表說明可能的錯誤值。

錯誤值 描述

ERROR_ALREADY_EXISTS

只有核心記錄器的單一實例會在系統上執行。 如果此函式嘗試在另一個元件啟動核心記錄之後啟動，可能會傳回此錯誤。

ERROR_INVALID_FLAGS

可能表示 Properties.EnableFlags中有不正確追蹤旗標。

ERROR_OUT_OF_MEMORY

可能表示無法為EVENT_TRACE_PROPERTIES配置記憶體。

如果函式因列出的原因而失敗，則會傳回系統錯誤碼。

備註

None

函式

UpdateHeapTrace