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

另請參閱

EVENT_TRACE

EventCallback

TraceEvent