次の方法で共有


EVENT_DESCRIPTOR 構造体 (evntprov.h)

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 アクティビティの開始と終了を次のように示すために使用されます。

  1. 通常は EventActivityIdControl を使用して、トレース内で一意のアクティビティ ID を生成します。
  2. opcode = START、アクティビティ ID = 生成されたアクティビティ ID、および関連するアクティビティ ID = 親アクティビティ ID (存在する場合) を使用して開始イベントを書き込みます。
  3. opcode = INFO、アクティビティ ID = 生成されたアクティビティ ID を使用して、任意の数のアクティビティ情報イベントを書き込みます。
  4. 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 を含む)

こちらもご覧ください

EVENT_HEADER

EventDescCreate

EventDescGetChannel

EventDescGetId

EventDescGetKeyword

EventDescGetLevel

EventDescGetOpcode

EventDescGetTask

EventDescGetVersion

EventDescOrKeyword

EventDescSetChannel

EventDescSetId

EventDescSetKeyword

EventDescSetLevel

EventDescSetOpcode

EventDescSetTask

EventDescSetVersion

EventDescZero

EventEnabled

EventWrite

EventWriteTransfer

PROVIDER_EVENT_INFO

TdhEnumerateManifestProviderEvents

TdhGetManifestEventInformation