WNODE_HEADER 結構

發行項
06/13/2023

WNODE_HEADER結構是EVENT_TRACE_PROPERTIES結構的成員。

語法

typedef struct _WNODE_HEADER {
  ULONG BufferSize;
  ULONG ProviderId;
  union {
    ULONG64 HistoricalContext;
    struct {
      ULONG Version;
      ULONG Linkage;
    };
  };
  union {
    HANDLE        KernelHandle;
    LARGE_INTEGER TimeStamp;
  };
  GUID  Guid;
  ULONG ClientContext;
  ULONG Flags;
} WNODE_HEADER, *PWNODE_HEADER;

成員

BufferSize

事件追蹤會話屬性所配置的記憶體大小總計，以位元組為單位。記憶體大小必須包含 EVENT_TRACE_PROPERTIES 結構的空間，加上記憶體中結構後面的會話名稱字串和記錄檔名稱字串。

ProviderId

保留供內部使用。

HistoricalCoNtext

輸出時，事件追蹤會話的控制碼。

版本

保留供內部使用。

連結

保留供內部使用。

KernelHandle

保留供內部使用。

時間戳

此結構中資訊更新的時間，自 1601 年 1 月 1 日午夜起的 100 奈秒間隔。

Guid

您為會話定義的 GUID。

針對 NT 核心記錄器會話，將此成員設定為 SystemTraceControlGuid。

如果此成員設定為 SystemTraceControlGuid 或 GlobalLoggerGuid，記錄器將會是系統記錄器。

針對私人記錄器會話，請將此成員設定為您要為會話啟用的提供者 GUID。

如果您啟動不是核心記錄器或私人記錄器會話的會話，就不需要指定會話 GUID。如果您未指定 GUID，ETW 會為您建立一個 GUID。只有在您想要變更與特定會話相關聯的預設許可權時，才需要指定會話 GUID。如需詳細資訊，請參閱 EventAccessControl 函式。

您無法使用相同的會話 GUID 啟動多個會話。

在 Windows Vista 之前： 您可以使用相同的會話 GUID 來啟動多個會話。

ClientContext

記錄每個事件的時間戳記時所使用的時鐘解析。預設值為 QPC) (查詢效能計數器。

在 Windows Vista 之前： 預設值為系統時間。

在Windows 10版本 1703 之前：任何系統記錄器都不能同時使用 2 個不同的時鐘類型。

從 Windows 10 1703 版開始：已移除時鐘類型限制。系統記錄器現在可以同時使用這三種時鐘類型。

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

值	意義
1	查詢效能計數器 (QPC) 。 QPC 計數器提供不受系統時鐘調整影響的高解析度時間戳記。儲存在事件中的時間戳記相當於從 QueryPerformanceCounter API 傳回的值。如需此時間戳記特性的詳細資訊，請參閱取得高解析度時間戳記。如果您有高事件率，或取用者合併來自不同緩衝區的事件，您應該使用此解析。在這些情況下，QPC 時間戳記的精確度和穩定性可讓您更精確地排序來自不同緩衝區的事件。不過，QPC 時間戳記不會反映系統時鐘的更新，例如，如果系統時鐘因為追蹤正在進行同步處理而與 NTP 伺服器進行同步處理，追蹤中的 QPC 時間戳記將會繼續反映時間，就像未發生任何更新一樣。若要判斷解決方法，請在取用事件時，使用TRACE_LOGFILE_HEADER的PerfFreq成員。若要將事件的時間戳記轉換成 100-ns 單位，請使用下列轉換公式： scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart * 1000000.0 / logfileHeader.PerfFreq.QuadPart 請注意，在較舊的電腦上，時間戳記可能不正確，因為計數器有時會因為硬體錯誤而向前略過。
2	系統時間。系統時間提供時間戳記，追蹤系統時鐘的變更，例如，如果系統時鐘因追蹤進行同步處理而與 NTP 伺服器同步處理，追蹤中的系統時間戳記也會向前跳躍，以符合系統時鐘的新設定。在Windows 10之前的系統上，儲存在事件的時間戳記相當於 GetSystemTimeAsFileTime API 所傳回的值。在Windows 10或更新版本上，儲存在事件的時間戳記相當於 GetSystemTimePreciseAsFileTime API 所傳回的值。在Windows 10之前，此時間戳記的解析是系統時鐘刻度解析，如 TRACE_LOGFILE_HEADER 的 TimerResolution 成員所指出。從Windows 10開始，此時間戳記的解析是效能計數器解析，如 TRACE_LOGFILE_HEADER PerfFreq 成員所指出。若要將事件的時間戳記轉換成 100-ns 單位，請使用下列轉換公式： scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart 請注意，在Windows 10之前執行作業系統的系統上擷取事件時，如果事件數量很高，系統時間的解析可能不足以判斷事件順序。在此情況下，一組事件會有相同的時間戳記，但 ETW 傳遞事件的順序可能不正確。從Windows 10開始，時間戳記會以額外的精確度擷取，不過，在擷取追蹤時，系統時鐘調整時仍可能發生某些不穩定狀況。
3	CPU 迴圈計數器。 CPU 計數器提供最高解析度的時間戳記，而且是擷取最不密集的資源。不過，CPU 計數器不可靠，不應用於生產環境。例如，在某些電腦上，除了在某些狀態中停止之外，計時器也會因為熱和電源變更而變更頻率。若要判斷解析度，請在取用事件時，使用TRACE_LOGFILE_HEADER的CpuSpeedInMHz成員。如果您的硬體不支援此時鐘類型，ETW 會使用系統時間。 Windows Server 2003、Windows XP SP1 和 Windows XP：不支援此值，它是在 Windows Server 2003 SP1 和 Windows XP SP2 中引進。

Windows 2000： 不支援 ClientCoNtext 成員。

旗標

必須包含 WNODE_FLAG_TRACED_GUID ，表示結構包含事件追蹤資訊。

備註

設定任何成員之前，請務必將此結構的記憶體初始化為零。

若要將 ETW 時間戳記轉換成 FILETIME，請使用下列程式：

1.針對每個要處理 (的會話或記錄檔，也就是針對每個 EVENT\_TRACE\_LOGFILE) ，請檢查 logFile.ProcessTraceMode 欄位，以判斷是否設定 PROCESS\_TRACE\_MODE\_RAW\_TIMESTAMP旗標。根據預設，不會設定此旗標。如果未設定此旗標，ETW 執行時間會自動將每個 EVENT\_RECORD的時間戳記轉換成 FILETIME，再將 EVENT\_RECORD傳送至 EventRecordCallback 函式，因此不需要額外的處理。只有在追蹤正以 PROCESS\_TRACE\_MODE\_RAW\_TIMESTAMP 旗標集處理時，才應該使用下列步驟。 2.針對每個要處理 (的會話或記錄檔，也就是針對每個 EVENT\_TRACE\_LOGFILE) ，請檢查 logFile.LogfileHeader.ReservedFlags 欄位，以判斷記錄檔的時間戳記小數位數。根據 ReservedFlags 的值，遵循下列步驟之一，判斷其餘步驟中要用於 timeStampScale 的值：

a. 如果 ReservedFlags == 1 (QPC) ：DOUBLE timeStampScale = 10000000.0 / logFile.LogfileHeader.PerfFreq.QuadPart;B。如果 ReservedFlags == 2 (系統時間) ：DOUBLE timeStampScale = 1.0;請注意，使用系統時間的事件不需要其餘步驟，因為事件已在 FILETIME 單位中提供時間戳記。其餘步驟將會正常運作，但並非必要步驟，而且將會產生小型舍入錯誤。 c. 如果 ReservedFlags == 3 (CPU 迴圈計數器) ：DOUBLE timeStampScale = 10.0 / logFile.LogfileHeader.CpuSpeedInMHz; 3.在特定記錄檔的 EventRecordCallback 函式的 FIRST 呼叫上，使用 logFile (EVENT\_TRACE\_LOGFILE) 和 eventRecord (EVENT\_RECORD) 的資料來計算將用於記錄檔中其餘事件的 timeStampBase：INT64 timeStampBase = logFile.LogfileHeader.StartTime.QuadPart - (INT64) (timeStampScale \* eventRecord.EventHeader.TimeStamp.QuadPart) ;4.針對每個 eventRecord (EVENT\_RECORD) ，使用步驟 2 和 3 中計算的 timeStampScale 和 timeStampBase 值，將事件的時間戳記轉換成 FILETIME：INT64 timeStampInFileTime = timeStampBase + (INT64) (timeStampScale \* eventRecord.EventHeader.TimeStamp.QuadPart) ;

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
標頭	Wmistr.h

另請參閱

ControlCallback
EVENT_TRACE_PROPERTIES
GetTraceLoggerHandle
LARGE_INTEGER

值	意義
1	查詢效能計數器 (QPC) 。 QPC 計數器提供不受系統時鐘調整影響的高解析度時間戳記。儲存在事件中的時間戳記相當於從 QueryPerformanceCounter API 傳回的值。如需此時間戳記特性的詳細資訊，請參閱取得高解析度時間戳記。如果您有高事件率，或取用者合併來自不同緩衝區的事件，您應該使用此解析。在這些情況下，QPC 時間戳記的精確度和穩定性可讓您更精確地排序來自不同緩衝區的事件。不過，QPC 時間戳記不會反映系統時鐘的更新，例如，如果系統時鐘因為追蹤正在進行同步處理而與 NTP 伺服器進行同步處理，追蹤中的 QPC 時間戳記將會繼續反映時間，就像未發生任何更新一樣。若要判斷解決方法，請在取用事件時，使用TRACE_LOGFILE_HEADER的PerfFreq成員。若要將事件的時間戳記轉換成 100-ns 單位，請使用下列轉換公式： scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart * 1000000.0 / logfileHeader.PerfFreq.QuadPart 請注意，在較舊的電腦上，時間戳記可能不正確，因為計數器有時會因為硬體錯誤而向前略過。
2	系統時間。系統時間提供時間戳記，追蹤系統時鐘的變更，例如，如果系統時鐘因追蹤進行同步處理而與 NTP 伺服器同步處理，追蹤中的系統時間戳記也會向前跳躍，以符合系統時鐘的新設定。在Windows 10之前的系統上，儲存在事件的時間戳記相當於 GetSystemTimeAsFileTime API 所傳回的值。在Windows 10或更新版本上，儲存在事件的時間戳記相當於 GetSystemTimePreciseAsFileTime API 所傳回的值。在Windows 10之前，此時間戳記的解析是系統時鐘刻度解析，如 TRACE_LOGFILE_HEADER 的 TimerResolution 成員所指出。從Windows 10開始，此時間戳記的解析是效能計數器解析，如 TRACE_LOGFILE_HEADER PerfFreq 成員所指出。若要將事件的時間戳記轉換成 100-ns 單位，請使用下列轉換公式： scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart 請注意，在Windows 10之前執行作業系統的系統上擷取事件時，如果事件數量很高，系統時間的解析可能不足以判斷事件順序。在此情況下，一組事件會有相同的時間戳記，但 ETW 傳遞事件的順序可能不正確。從Windows 10開始，時間戳記會以額外的精確度擷取，不過，在擷取追蹤時，系統時鐘調整時仍可能發生某些不穩定狀況。
3	CPU 迴圈計數器。 CPU 計數器提供最高解析度的時間戳記，而且是擷取最不密集的資源。不過，CPU 計數器不可靠，不應用於生產環境。例如，在某些電腦上，除了在某些狀態中停止之外，計時器也會因為熱和電源變更而變更頻率。若要判斷解析度，請在取用事件時，使用TRACE_LOGFILE_HEADER的CpuSpeedInMHz成員。如果您的硬體不支援此時鐘類型，ETW 會使用系統時間。 Windows Server 2003、Windows XP SP1 和 Windows XP：不支援此值，它是在 Windows Server 2003 SP1 和 Windows XP SP2 中引進。

WNODE_HEADER 結構

語法

成員

備註

規格需求

另請參閱

意見反應

意見反應

其他資源