EVENT_DESCRIPTOR構造体 (evntprov.h)

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

Version

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

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

Channel

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

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

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

Level

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

重要

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

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

値	Semantics
LOG_ALWAYS (0)	イベントは、レベルベースのイベントフィルター処理をバイパスします。イベントはこのレベルを使用しないでください。
CRITICAL (1)	重大なエラー
エラー (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 を生成します。
オペコード = START、アクティビティ ID = 生成されたアクティビティ ID、および関連アクティビティ ID = 親アクティビティ ID (存在する場合) を使用して開始イベントを書き込みます。
オペコード = INFO、アクティビティ ID = 生成されたアクティビティ ID を使用して、任意の数のアクティビティ情報イベントを書き込みます。
オペコード = STOP、アクティビティ ID = 生成されたアクティビティ ID を使用して停止イベントを書き込みます。

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

Task

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

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

Keyword

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

重要

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

キーワードの上位 16 ビット (ビットマスク 0xFFFF000000000000) は、Microsoft によって定義されます。キーワードの下位 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構成時に 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 [デスクトップアプリのみ]
ヘッダー	evntprov.h (Evntprov.h を含む)