EVENT_TRACE_HEADER 結構 (evntrace.h)
EVENT_TRACE_HEADER 結構包含 TraceEvent 所撰寫之所有事件通用的標準事件追蹤資訊。
語法
typedef struct _EVENT_TRACE_HEADER {
USHORT Size;
union {
USHORT FieldTypeFlags;
struct {
UCHAR HeaderType;
UCHAR MarkerFlags;
} DUMMYSTRUCTNAME;
} DUMMYUNIONNAME;
union {
ULONG Version;
struct {
UCHAR Type;
UCHAR Level;
USHORT Version;
} Class;
} DUMMYUNIONNAME2;
ULONG ThreadId;
ULONG ProcessId;
LARGE_INTEGER TimeStamp;
union {
GUID Guid;
ULONGLONG GuidPtr;
} DUMMYUNIONNAME3;
union {
struct {
ULONG KernelTime;
ULONG UserTime;
} DUMMYSTRUCTNAME;
ULONG64 ProcessorTime;
struct {
ULONG ClientContext;
ULONG Flags;
} DUMMYSTRUCTNAME2;
} DUMMYUNIONNAME4;
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;
成員
Size
事件的位元組總數。 大小 包括標頭結構的大小，加上附加至標頭的任何事件特定數據大小。
在輸入時，大小必須小於事件追蹤會話緩衝區的大小減去 72 (0x48) 。
在輸出上，請勿在計算中使用這個數位。
DUMMYUNIONNAME
DUMMYUNIONNAME.FieldTypeFlags
保留的。
DUMMYUNIONNAME.DUMMYSTRUCTNAME
DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType
保留的。
DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags
保留的。
DUMMYUNIONNAME2
DUMMYUNIONNAME2.Version
這是 Class 成員的匯總。 低序位元組包含 Type、下一個字節包含 Level，最後兩個字節包含版本。
DUMMYUNIONNAME2.Class
DUMMYUNIONNAME2.Class.Type
事件類別。 提供者可以定義自己的事件類型，或使用下表所列的預先定義事件類型。
EVENT_TRACE_TYPE_CHECKPOINT：Checkpoint 事件。 用於不在活動開頭或結尾的事件。
EVENT_TRACE_TYPE_DC_END：數據收集結束事件。
EVENT_TRACE_TYPE_DC_START：數據收集開始事件。
EVENT_TRACE_TYPE_DEQUEUE:D equeue 事件。 活動在開始之前排入佇列時使用。 使用EVENT_TRACE_TYPE_START標記工作專案排入佇列的時間。 使用清除佇列事件類型來標記專案實際開始工作時的時間。 使用EVENT_TRACE_TYPE_END標記專案完成工作時的時間。
EVENT_TRACE_TYPE_END：End 事件。 使用 來追蹤多步驟事件的最終狀態。
EVENT_TRACE_TYPE_EXTENSION：擴充功能事件。 用於屬於上一個事件的接續事件。 例如，當事件追蹤記錄的數據超出會話緩衝區所能容納的數據時，請使用擴充事件類型。
EVENT_TRACE_TYPE_INFO：資訊事件。 這是預設事件類型。
EVENT_TRACE_TYPE_REPLY：回復事件。 當要求資源的應用程式可以接收多個回應時使用。 例如，如果用戶端應用程式要求 URL，而 Web 伺服器會藉由傳送數個檔案來回復，則收到的每個檔案都可以標示為回復事件。
EVENT_TRACE_TYPE_START：Start 事件。 使用 來追蹤多步驟事件的初始狀態。
如果您定義自己的事件類型，您應該使用從 10 開始的數位。 不過，您無法使用任何您想要使用的數位。 如果您的事件追蹤類別 GUID 支援多個事件類型，取用者會使用事件類型來判斷事件，以及如何解譯其內容。
DUMMYUNIONNAME2.Class.Level
提供者定義的值，定義用來產生事件的嚴重性層級。 值的範圍從 0 到 255。 控制器會在呼叫 EnableTraceEx2 函式時指定嚴重性層級。 提供者會從其 ControlCallback 實作呼叫 GetTraceEnableLevel 函式，以擷取嚴重性層級。 提供者會使用 值來設定這個成員。
ETW 會定義下列嚴重性層級。 選取高於 1 的層級也會包含較低層級的事件。 例如，如果控制器指定TRACE_LEVEL_WARNING (3) ，提供者也會產生TRACE_LEVEL_FATAL (1) ，TRACE_LEVEL_ERROR (2) 事件。
| 值 | 意義 |
|---|---|
| TRACE_LEVEL_CRITICAL (1) | 異常結束或終止事件 |
| TRACE_LEVEL_ERROR (2) | 嚴重錯誤事件 |
| TRACE_LEVEL_WARNING (3) | 配置失敗等警告事件 |
| TRACE_LEVEL_INFORMATION (4) | 非錯誤事件，例如進入或結束事件 |
| TRACE_LEVEL_VERBOSE (5) | 詳細的追蹤事件 |
DUMMYUNIONNAME2.Class.Version
指出您用來記錄事件的事件追蹤類別版本。 如果事件追蹤類別只有一個版本，請指定零。 版本會告訴取用者要使用哪一個MOF類別來譯碼事件數據。
ThreadId
在輸出上，識別產生事件的線程。
請注意，在 Windows 2000 上， ThreadId 是 ULONGLONG 值。
ProcessId
在輸出中，識別產生事件的進程。
Windows 2000： 不支援這個成員。
TimeStamp
在輸出上，包含事件發生的時間。 除非EVENT_TRACE_LOGFILE的 ProcessTraceMode 成員包含 PROCESS_TRACE_MODE_RAW_TIMESTAMP 旗標，否則解析是系統時間，在此情況下，解析取決於控制器建立會話時EVENT_TRACE_PROPERTIES的 Wnode.ClientContext 成員值。
DUMMYUNIONNAME3
DUMMYUNIONNAME3.Guid
事件追蹤類別 GUID。 您可以使用類別 GUID 來識別事件的類別和 Class.Type 成員，以識別事件類別內的事件。
或者，您可以使用 GuidPtr 成員來指定類別 GUID。
Windows XP 和 Windows 2000： 類別 GUID 先前必須使用 RegisterTraceGuids 函式註冊。
DUMMYUNIONNAME3.GuidPtr
事件追蹤類別 GUID 的指標。 或者，您可以使用 Guid 成員來指定類別 GUID。
寫入事件時，ETW 會使用指標將 GUID 複製到事件， (GUID 包含在事件中，而不是指標) 。
如果您使用此成員， Flags 成員也必須包含WNODE_FLAG_USE_GUID_PTR。
DUMMYUNIONNAME4
DUMMYUNIONNAME4.DUMMYSTRUCTNAME
DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime
核心模式指令的經過運行時間，以 CPU 時間單位為單位。 如果您使用私人會話，請改用 ProcessorTime 成員中的值。 如需詳細資訊，請參閱＜備註＞。
DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime
使用者模式指令的經過運行時間，以 CPU 時間單位為單位。 如果您使用私人會話，請改用 ProcessorTime 成員中的值。 如需詳細資訊，請參閱＜備註＞。
DUMMYUNIONNAME4.ProcessorTime
針對私人會話，CPU 刻度中使用者模式指示所耗用的運行時間。
DUMMYUNIONNAME4.DUMMYSTRUCTNAME2
DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext
保留的。
DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags
您必須將此成員設定為WNODE_FLAG_TRACED_GUID，而且可以選擇性地指定下列任何組合。
WNODE_FLAG_USE_GUID_PTR：指定 GuidPtr 成員是否包含類別 GUID。
WNODE_FLAG_USE_MOF_PTR：指定 MOF_FIELD 結構的陣列是否包含附加至此結構的事件數據。 陣列中的元素數目限制為 MAX_MOF_FIELDS。
備註
設定任何成員之前，請務必將此結構的記憶體初始化為零。
您可以使用 KernelTime 和 UserTime 成員來判斷一組指令的 CPU 成本， (值表示記錄時該線程所收取的 CPU 使用量) 。 例如，如果事件 A 和事件 B 會由相同的線程連續記錄，而且其 CPU 使用量號碼為 150 和 175，則由事件 A 與 B 之間的該線程所執行的活動成本為 25 個 CPU 時間單位， (175 – 150) 。
TRACE_LOGFILE_HEADER 結構的 TimerResolution 包含以 100 奈秒為單位的 CPU 使用量定時器解析度。 您可以使用定時器解析度搭配核心時間和用戶時間值，以判斷所使用的指令集 CPU 時間量。 例如，如果定時器解析度為 156,250，則 25 個 CPU 時間單位為 0.39 秒， (156,250 * 25 * 100 / 1,000,000,000,000) 。 這是一組事件 A 與 B 之間指令所使用的 CPU 時間 (未經過的時鐘時間) 。
不過請注意，CPU 使用量定時器解析度通常非常低， (大約 10 毫秒以上) 。 因此，CPU 使用量號碼無法用來考慮具有高精確度的線程之間的CPU時間使用量。 相反地，它們適用於長期、統計類型的分析。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 標頭 | evntrace.h |