EVENT_DESCRIPTOR 構造体 (evntprov.h)

[アーティクル]
08/23/2023

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 (つまりトレースログ) の場合、Id フィールドは通常意味を持たず、通常は 0 に設定されます。トレースログイベントは、通常、イベント ID ではなく、イベント名によって識別されます。

Version

マニフェストベースのイベントのバージョンを指定するために使用される 8 ビット番号。

バージョンは、特定の ID を持つイベントの定義のリビジョンを示します。特定の ID を持つすべてのイベントは、同様のセマンティクスを持つ必要がありますが、バージョンの変更を使用して、イベントの詳細の軽微な変更 (フィールドの型の変更や新しいフィールドの追加など) を示すことができます。

Channel

特殊なイベント処理を有効にするために使用される 8 ビット番号。

マニフェストベースのイベントでは、通常、チャネル 0 が使用されます。
トレースログベースのイベントでは、通常、チャネル 11 が使用されます。
プロバイダー特性を持つマニフェストベースのイベントでは、通常、チャネル 12 が使用されます。
その他のチャネル値は、イベントログイベントと共に使用できます。

16 未満のチャネル値は、ETW ランタイムによる特別な処理を可能にするために Microsoft が使用するために予約されています。チャネル値 16 以上は ETW ランタイムによって無視され (チャネル 0 と同じように扱われます)、ユーザー定義のセマンティクスを指定できます。

Level

イベントの重大度または重要度を表すために使用される 8 ビットの数値。

重要

イベントレベルは、イベントをフィルター処理するための主な手段です。すべてのイベントに意味のある (ゼロ以外の) レベルを常に割り当てます。

レベル値 0 から 5 は、Microsoft によって定義されます (および winmeta.hを参照)。evntrace.h レベル値 6 ~ 15 は予約されています。レベル値 16 から 255 は、イベントプロバイダーによって定義できます。

値	セマンティクス
LOG_ALWAYS (0)	イベントは、レベルベースのイベントフィルター処理をバイパスします。イベントでは、このレベルを使用しないでください。
CRITICAL (1)	重大なエラー
ERROR (2)	エラー
警告 (3)	警告
INFO (4)	Informational
VERBOSE (5)	"詳細"

イベントコレクションセッションでは、レベルフィルターを設定できます。つまり、セッションは、の eventDescriptor.Level <= session.LevelFilterイベントのみを受け入れます。レベルが 0 のイベントは、レベルベースのフィルター処理をバイパスすることに注意してください。

Opcode

イベントを特別なセマンティクスでマークするために使用される 8 ビットの数値。この値は、トレースデコーダーがイベントを整理および関連付けるために使用できます。グローバルに認識されるオペコード値は winmeta.h で定義されます。ほとんどのイベントでは INFO (0) が使用されます。オペコード値 10 ~ 239 には、ユーザー定義のセマンティクスを指定できます。

オペコード START (1) と STOP (2) は、ETW アクティビティの開始と終了を次のように示すために使用されます。

通常は EventActivityIdControl を使用して、トレース内で一意のアクティビティ ID を生成します。
opcode = START、アクティビティ ID = 生成されたアクティビティ ID、および関連するアクティビティ ID = 親アクティビティ ID (存在する場合) を使用して開始イベントを書き込みます。
opcode = INFO、アクティビティ ID = 生成されたアクティビティ ID を使用して、任意の数のアクティビティ情報イベントを書き込みます。
opcode = STOP、アクティビティ ID = 生成されたアクティビティ ID を使用して停止イベントを書き込みます。

トレースデコードツールを使用すると、アクティビティ ID に基づいてこれらのイベントをグループ化できます。

Task

イベントまたは関連するイベントグループに注釈を付けるために使用される 16 ビット番号。

イベントタスクコードは、プロバイダーによって定義されている任意の目的で使用できます。タスクコード 0 は既定で、イベントに特別なタスクコードが割り当てられていないことを示すために使用されます。 ETW マニフェストでは、各タスクコードにローカライズされた文字列を割り当てることがサポートされています。タスクコードは、イベントをカテゴリにグループ化したり、ローカライズされた "task" 文字列を各イベントに関連付けたりするために使用できます。

Keyword

イベントカテゴリのセット内のイベントのメンバーシップを示すために使用される 64 ビットビットマスク。

重要

イベントキーワード (keyword)は、イベントをフィルター処理するための主な手段です。すべてのイベントに意味のある (ゼロ以外の) キーワード (keyword)を常に割り当てます。

キーワード (keyword)の上位 16 ビット (ビットマスク 0xFFFF000000000000) は、Microsoft によって定義されます。キーワード (keyword)の下位 48 ビット (ビットマスク 0x0000FFFFFFFFFFFF) は、イベントプロバイダーによって定義されます。たとえば、イベントプロバイダーは、ビット 0 (ビットマスク 0x1) を "I/O" カテゴリに、ビット 1 (ビットマスク 0x2) を "UI" カテゴリに定義し、ビット 2 (ビットマスク 0x4) を "パフォーマンス測定" カテゴリとして定義します。このシナリオでは、イベントのキーワード (keyword)が0x5に設定され、イベントが "I/O" カテゴリと "パフォーマンス測定" カテゴリの両方にあることを示す場合があります。

イベントコレクションセッションでは、MatchAnyKeyword フィルターと MatchAllKeyword フィルターを設定できます。つまり、セッションは次の式が true のイベントのみを受け入れます。

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

キーワード (keyword)が 0 のイベントは、通常、キーワード (keyword)ベースのフィルター処理をバイパスすることに注意してください。

ヒント

バージョン 1507 以降Windows 10、イベントコレクションセッションでは、キーワード (keyword)が 0 に設定されているイベントを除外できます。これを行うには、プロバイダーのEVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0構成時に EnablePropertyEnableTraceEx2 に渡されるENABLE_TRACE_PARAMETERS構造体のフィールドにフラグを含めます。

注釈

この構造体は、 EventWrite を呼び出してイベントを書き込むときに使用されます。 EventEnabled を呼び出すときに使用して、イベントを生成する必要があるかどうかを判断することもできます (つまり、イベントリスナーがイベントに関心があるかどうかを判断するため)。

注意

ほとんどのイベントプロバイダーでは、 EVENT_DESCRIPTOR を直接使用しません。代わりに、ほとんどのイベントプロバイダーは、EventRegister、EventWriteEx、および EventUnregister の呼び出しをラップする ETW フレームワークを使用して実装されます。たとえば、イベントマニフェストを記述し、メッセージコンパイラを使用してイベントの C/C++ コードを生成したり、 TraceLogging を使用してマニフェストの必要性を回避したりできます。この構造体のメンバーとインストルメンテーションマニフェストの関係の詳細については、 EventDefinitionType 複合型の属性を参照してください。

この構造体は、EventRecordCallback コールバックで ProcessTrace を使用してイベントを使用するときにイベントレコードと共に返されるEVENT_HEADER構造体に含まれます。

注意

MOF ベースのイベントを処理する場合、イベント ID は Id フィールドではなく Opcode フィールドに含まれます。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
Header	evntprov.h (Evntprov.h を含む)