EVENT_DESCRIPTOR 結構 (evntprov.h)

發行項
02/27/2024

EVENT_DESCRIPTOR 結構包含 ETW 事件的相關信息 (元數據) 。

語法

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

成員

Id

16 位數位，用來識別以指令清單為基礎的事件。

對於以指令清單為基礎的 ETW，Provider.DecodeGuid + Event.Id + Event.Version 的組合應該唯一識別事件，也就是具有相同 DecodeGuid、Id 和 Version 的所有事件都應該具有相同的字段集，且功能變數名稱、字段類型或字段順序沒有任何變更。

對於無指令清單的 ETW (也就是 TraceLogging) ，[標識符] 字段通常沒有意義，而且通常會設定為 0。 TraceLogging 事件通常會以其事件名稱來識別，而不是事件標識碼。

Version

用來指定以指令清單為基礎的事件版本的8位數位。

版本指出具有特定標識碼之事件定義的修訂。具有指定標識碼的所有事件都應該有類似的語意，但版本變更可用來指出事件詳細數據的次要修改，例如變更欄位類型或新增新的字段。

Channel

用來啟用特殊事件處理的8位數位。

指令清單型事件通常會使用通道 0。
TraceLogging 型事件通常會使用通道 11。
具有提供者特性的指令清單型事件通常會使用通道 12。
其他通道值可以搭配事件記錄檔事件使用。

低於 16 的通道值會保留供 Microsoft 使用，以啟用 ETW 運行時間的特殊處理。 ETW 運行時間會將通道值 16 和更新版本忽略 (視為通道 0) ，而且可以指定使用者定義的語意。

Level

用來描述事件的嚴重性或重要性的8位數位。

重要

事件層級是篩選事件的主要方法。一律將有意義的 (非零) 層級指派給每個事件。

層級值 0 到 5 是由 Microsoft (查看 evntrace.h 和 winmeta.h) 所定義。保留層級值 6 到 15。層級值 16 到 255 可由事件提供者定義。

值	語意
LOG_ALWAYS (0)	事件會略過層級式事件篩選。事件不應該使用此層級。
重大 (1)	嚴重錯誤
錯誤 (2)	錯誤
警告 (3)	警告
INFO (4)	資訊
VERBOSE (5)	「詳細資訊」

事件集合會話可以設定層級篩選，這表示會話只會接受其中 eventDescriptor.Level <= session.LevelFilter的事件。請注意，層級為 0 的事件會略過層級型篩選。

Opcode

用來以特殊語意標記事件的8位數位。追蹤譯碼器可以使用此值來組織和相互關聯事件。全域辨識的 opcode 值定義於 winmeta.h 中。大部分的事件都會使用 INFO (0) 。 Opcode 值 10 到 239 可以指定使用者定義的語意。

Opcodes START (1) 和 STOP (2) 用來指出 ETW 活動的開頭和結尾，如下所示：

產生追蹤內唯一的活動標識碼，通常是使用 EventActivityIdControl。
如果有任何) ，請使用 opcode = START、活動識別碼 = 產生的活動識別碼，以及相關的活動標識碼 = 父活動識別碼 (寫入起始事件。
使用 opcode = INFO 撰寫任意數目的活動資訊事件，活動標識碼 = 產生的活動識別碼。
使用 opcode = STOP 撰寫停止事件，活動識別碼 = 產生的活動識別碼。

追蹤譯碼工具接著可以根據其活動標識碼，將這些事件組織成群組。

Task

用來標註事件或相關事件群組的16位數位。

事件工作程式代碼可用於提供者所定義的任何用途。工作代碼 0 是預設值，用來指出未將任何特殊工作程式代碼指派給事件。 ETW 指令清單支援將當地語系化字串指派給每個工作程式碼。工作程式代碼可用來將事件分組為類別，或只是將本地化的「工作」字串與每個事件產生關聯。

Keyword

64 位位掩碼，用來指出事件類別集合中的事件成員資格。

重要

Event 關鍵詞是篩選事件的主要方法。請一律將有意義的 (非零) 關鍵詞指派給每個事件。

Microsoft 會定義關鍵詞的前 16 位 (位掩碼0xFFFF000000000000) 。事件提供者會定義關鍵詞的低 48 位 (位掩碼0x0000FFFFFFFFFFFF) 。例如，事件提供者可能會定義位0 (位掩碼0x1) 为 “I/O” 類別，位1 (位掩碼0x2) 为 “UI” 類別，而位2 (位掩碼0x4) 为「效能測量」類別。在此案例中，事件可能會將其關鍵詞設定為0x5，指出事件同時位於「I/O」和「效能測量」類別中。

事件集合會話可以設定 MatchAnyKeyword 和 MatchAllKeyword 篩選，這表示會話只會接受下列表達式為 true 的事件：

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

請注意，關鍵詞為 0 的事件通常會略過關鍵詞型篩選。

提示

從 Windows 10 1507 版和更新版本開始，事件集合會話可以排除其關鍵詞設定為 0 的事件。若要這樣做，請在EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0設定提供者時傳遞至 EnableTraceEx2 的 ENABLE_TRACE_PARAMETERS 結構字段中包含旗標EnableProperty。

備註

呼叫 EventWrite 以寫入事件時，會使用此結構。您也可以在呼叫 EventEnabled 時使用它來判斷事件是否應該產生 (，也就是判斷是否有任何事件接聽程式對事件) 感興趣。

注意

大部分的事件提供者不會直接使用 EVENT_DESCRIPTOR 。相反地，大部分的事件提供者都是使用 ETW 架構來實作，以包裝 對 EventRegister、 EventWriteEx 和 EventUnregister 的呼叫。例如，您可以撰寫事件指令清單，然後使用訊息編譯程式為事件產生 C/C++ 程式代碼，或者您可以使用 TraceLogging 來避免指令清單的需求。如需此結構成員與檢測指令清單相關的詳細資訊，請參閱 EventDefinitionType 複雜類型的屬性。

當您使用 ProcessTrace 搭配 EventRecordCallback 回呼時，此結構包含在事件記錄傳回的EVENT_HEADER結構中。

注意

處理MOF型事件時，事件識別會包含在 Opcode 欄位中，而不是 [ 標識元 ] 字段。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
標頭	evntprov.h (包括 Evntprov.h)