共用方式為

StartKernelTrace

  • 發行項

此函式會註冊並啟動核心事件追蹤會話。 您也可以使用這個函式來啟用特定核心事件的堆疊走動。

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

參數

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

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

EVENT_TRACE_PROPERTIES 結構的第一個成員是 WNODE_HEADER結構，這裡稱為 Wnode。

下列EVENT_TRACE_PROPERTIES。必須設定 Wnode 成員，才能設定核心追蹤控制項。

BufferSize
此成員包含為事件追蹤會話屬性配置之記憶體的總大小，以位元組為單位。 記憶體大小必須包含足夠的空間來儲存下列資料：

  • EVENT_TRACE_PROPERTIES 結構。

  • 會話名稱字串。

  • 記錄檔名稱字串。

Guid
每個追蹤會話都必須定義 GUID 以參考會話。

針對 NT 核心記錄器會話，此成員必須設定為 SystemTraceControlGuid。 如需記錄模式常數的詳細資訊，請參閱 NT 核心記錄器常數。

ClientCoNtext
這個成員會設定計算每個事件的記錄時間戳記時所使用的時鐘解析。 這個成員的預設值是查詢效能計數器。

您可以指定下列其中一個值：

  • 1： 查詢效能計數器 (QPC) 。 QPC 提供高解析度 (100 奈秒) 時間戳記，但擷取的成本比較高。 如果您有高事件率，或取用者合併來自不同緩衝區的事件，請使用這個解析。 在較舊的電腦上，時間戳記可能不正確，因為計數器有時會因為硬體錯誤而向前略過。

  • 2： 系統時間。 系統時間提供低解析度 (10 毫秒) 時間戳記，但比擷取成本較低。 如果事件數量很高，系統時間的解析度可能不足以判斷事件序列。 在此情況下，一組事件會有相同的時間戳記，但 ETW 傳遞事件的順序可能不正確。

  • 3： CPU 週期計數器。 CPU 計數器提供最高解析度的時間戳記，而且擷取成本最低。 不過，CPU 計數器不可靠，不應該用於生產環境。 例如，在某些電腦上，計時器會因熱度和電源變更而變更頻率，除了在某些狀態中停止之外。 如果您的硬體不支援此時鐘類型，ETW 會使用系統時間。 在 Windows Server 2003、具有 SP1 和 Windows XP 的 Windows XP 中，不支援此值。 它是在 Windows Server 2003 SP1 和 Windows XP SP2 中引進。

標誌
這個成員必須包含WNODE_FLAG_TRACED_GUID，表示結構包含事件追蹤資訊，並將資訊傳送至記錄器。 WNODE_FLAG_TRACED_GUID定義于 Evntrace.h 中。

也必須設定下列EVENT_TRACE_PROPERTIES成員：

LogFileMode
指出核心事件追蹤會話中要使用的記錄模式。 您可以使用這個成員來指定要寫入記錄檔、即時取用者或兩者的事件。

此成員也可用來指定會話是私人記錄器會話。 可以指定一或多個模式。 如需可能模式的清單，請參閱 記錄模式常數。

注意 除非有即時取用者準備好取用事件，否則請勿指定即時記錄。 如果沒有即時取用者，事件會寫入播放檔案。 播放檔案的大小有限。 如果達到限制，則不會將任何新事件記錄到記錄檔或播放檔案。 記錄函式會因為STATUS_LOG_FILE_FULL而失敗。

EnableFlags
這個成員僅用於 NT 核心記錄器會話。 它會向核心記錄器識別要追蹤的事件。 藉由使用邏輯 OR，這個成員可以包含一或多個值。 除了指定的事件之外，核心記錄器也會記錄硬體設定事件。

除了EVENT_TRACE_PROPERTIES所提供的追蹤控制項旗標之外，還有下列追蹤控制項旗標：

LogFileNameOffset
這個數位代表從配置給 結構的記憶體開頭到包含記錄檔名稱之 Null 終止字串開頭的位移。

您必須考量下列事項：

  • 副檔名應該是 .etl。

  • 路徑中的所有資料夾都必須存在。

  • 路徑可以是相對、絕對、本機或遠端。

  • 路徑不得包含環境變數，因為這些變數不會展開。

  • 起始追蹤的使用者必須具有資料夾的寫入權限。

  • 記錄檔名稱限制為 1024 個字元。

  • 如果您將 LogFileMode 設定為 EVENT_TRACE_PRI加值稅E_LOGGER_MODE 或 EVENT_TRACE_FILE_MODE_NEWFILE，請務必配置足夠的記憶體，以包含附加至私用記錄器會話之檔案名的進程識別碼，以及新增至使用新檔案記錄模式建立之記錄檔的循序號碼。

  • 例如，如果您不想要將事件記錄到記錄檔 (，您只指定EVENT_TRACE_REAL_TIME_MODE) ，請將 LogFileNameOffset 設定為零。 如果您只指定即時記錄，也提供具有有效記錄檔名稱的位移，則會使用記錄檔名稱來建立循序記錄檔和記錄檔事件。 如果 LogFileMode 為零，而且您提供具有有效記錄檔名稱的位移，也會建立循序記錄檔。

  • 如果您想要將事件記錄到記錄檔，您必須配置足夠的記憶體供此結構使用，以在結構之後包含記錄檔名稱和會話名稱。 記錄檔名稱必須遵循記憶體中的會話名稱。

  • 追蹤檔案是使用預設的安全性描述元來建立，這表示記錄檔會與父目錄具有相同的 ACL。 如果您想要限制檔案的存取權，請使用適當的 ACL 建立父目錄。

LoggerNameOffset
這個成員代表從配置給 結構的記憶體開頭到包含會話名稱之 Null 終止字串開頭的位移。

您必須考量下列事項：

  • 會話名稱限制為 1024 個字元。

  • 會話名稱不區分大小寫，而且必須是唯一的。

  • 配置此結構的記憶體時，必須保留足夠的記憶體，才能在結構之後包含會話名稱和記錄檔名稱。

  • 會話名稱必須位於記憶體中的記錄檔名稱之前。 記錄檔名稱必須複製到位移區域中。 此函式會寫入KERNEL_LOGGER_NAME定義的會話名稱。

根據所選擇的記錄檔類型，可能需要設定 MaximumFileSize 成員。

注意 您不需要在 LoggerNameOffset 上設定記錄器名稱，因為此函式一律會使用 KERNEL_LOGGER_NAME 值來呼叫 StartKernelTrace。 此函式會檢查 Wnode.Guid 是否對應至 SystemTraceControlGuid;如果不是，則會傳回ERROR_INVALID_PARAMETER。 如果 Wnode.Guid 對應至 KernelRundownGuid，則應該指定記錄器名稱。 KernelRundownGuid是用來記錄事件的控制 GUID，例如現有的進程資訊、執行緒資訊、每個進程載入的映射，以及 CPU、視訊、磁片、網路卡、服務、電源、隨插即用和磁片 IDE 通道等硬體設定。

傳回值

ERROR_SUCCESS表示成功。

下表說明可能的錯誤值。

錯誤值 描述

ERROR_ALREADY_EXISTS

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

ERROR_INVALID_FLAGS

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

ERROR_OUT_OF_MEMORY

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

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

備註

如果 StackTracingEventIds 包含EVENT_TRACE_PROPERTIES中未啟用的事件 。EnableFlags 欄位或無法由核心追蹤控制項解碼、忽略這些旗標，而且不會傳回錯誤碼。

需求：

版本： 從 Windows Vista 開始提供。 此結構會與 Windows 效能分析器一起散發。

頭： 在 KernelTraceControl.h 中宣告。 包含 KernelTraceControl.h。

圖書館： 包含在KernelTraceControl.dll中。

函式

系統資訊的自訂導入