EVENT_FILTER_DESCRIPTOR 構造体 (evntprov.h)
EVENT_FILTER_DESCRIPTOR構造体は、セッションがプロバイダーの enable コールバック関数に渡すフィルター データを定義します。
構文
typedef struct _EVENT_FILTER_DESCRIPTOR {
ULONGLONG Ptr;
ULONG Size;
ULONG Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;
メンバー
Ptr
Type メンバーで指定されたフィルターの種類のフィルター データへのポインター。
Type メンバーが EVENT_FILTER_TYPE_PID に設定されている場合、Ptr メンバーはプロセス ID (PID) の配列を指します。
Type メンバーが EVENT_FILTER_TYPE_EVENT_ID に設定されている場合、Ptr メンバーは、イベント ID の配列と、指定したイベント ID に対してトレースが有効か無効かを決定するブール値を含むEVENT_FILTER_EVENT_ID構造体を指します。
Type メンバーが EVENT_FILTER_TYPE_STACKWALK に設定されている場合、Ptr メンバーは、イベント ID の配列と、指定したイベント ID に対してスタック トレースが有効か無効かを決定するブール値を含むEVENT_FILTER_EVENT_ID構造体を指します。
Type メンバーが EVENT_FILTER_TYPE_SCHEMATIZED に設定されている場合は、フィルターの構築の詳細については、EVENT_FILTER_HEADER構造体を参照してください。
Size
データのサイズ (バイト単位)。
最大データ サイズ制限は、指定された Type メンバー (フィルターの型) によって異なります。 多くのフィルターの種類の最大データ サイズ (バイト単位) は、evntprov.h ヘッダー ファイルで 1024 に定義されているMAX_EVENT_FILTER_DATA_SIZEに制限されています。
Type
フィルターを識別するプロバイダー定義の値。 インストルメンテーション マニフェストで定義されているフィルターの場合は、このメンバーを EVENT_FILTER_TYPE_SCHEMATIZED に設定します。
このメンバーに指定できる値は、 evntprov.h ヘッダー ファイルで定義されています。
EVENT_FILTER_TYPE_NONE (0x00000000)
フィルターなし。
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)
スキーマ化されたフィルター。
これは、プロバイダー側のフィルター処理とも呼ばれる従来のフィルター設定です。 コントローラーは、フィルターのカスタム セットを、EnableTrace、EnableTraceEx、または EnableTraceEx2 呼び出しでプロバイダーに渡されるバイナリ オブジェクトとして定義します。 これらのフィルターを定義して解釈することは、コントローラーとプロバイダーに必要であり、コントローラーは該当するイベントのみをログに記録する必要があります。 フィルター処理できるバイナリ オブジェクトの型と形式が定義されていないため、コントローラーとプロバイダーの密接な結合が必要です。 TdhEnumerateProviderFilters 関数を使用して、マニフェストで定義されているフィルターを取得できます。
スキーマ化されたフィルターの詳細については、「フィルター の定義」を参照してください。
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)
内部使用のために予約されています。
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)
特定のトレース セッションのランダウンをキャプチャするために使用されます。 EnableTraceEx 関数に渡される ControlCode パラメーターは、EVENT_CONTROL_CODE_CAPTURE_STATEに設定する必要があり、ProviderId パラメーターは SystemTraceControlGuid である必要があります。 EVENT_FILTER_DESCRIPTOR構造体は、現在の ETW セッションを表す単一の TRACEHANDLE を指している必要があります。 その特定のセッションに対してランダウンが実行されます。
EVENT_FILTER_TYPE_PID (0x80000004)
プロセス ID。 これは、スコープ フィルターの 1 つです。
プロセス ID に基づいて ETW イベントをフィルター処理すると、指定されたプロセス内のプロバイダーからのイベントのみを含むイベント ストリーム (ファイルまたはリアルタイム) が生成されます。 プロバイダーは、PID が提供されているプロセスでのみ有効になります。 PID の一覧は 、EnableTraceEx2 が呼び出された時点で実行されているプロセスの PID であり、その特定の時点ですべてのプロセス (PID が提供される) でプロバイダーを有効にします。 PID の一覧はセッションに格納されません。 そのため、プロセスが終了してから再び表示されると、その中のプロバイダーはトレース セッションに対して自動的に有効になりません。 プライベート ロガー セッションはユーザー モード プロセス内で実行されるため、PID ベースのフィルター BLOB はカーネル モード ロガー セッションでのみ有効です。
フィルター処理できるプロセス ID の最大数は、evntprov.h ヘッダー ファイルで定義MAX_EVENT_FILTER_PID_COUNT 8 に制限されます。
プロセス ID フィルターが指定されている場合、プロバイダーはユーザー モード プロセスでのみ有効になります。 カーネル モード ドライバーによって同じプロバイダーが登録されている場合、有効になりません。
これは、システム全体のプライベート ロガーの EVENT_TRACE_PROPERTIES_V2 で使用されます。
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)
実行可能ファイルの名前。 これは、スコープ フィルターの 1 つです。
これは、システム全体のプライベート ロガーの EVENT_TRACE_PROPERTIES_V2 で使用されます。
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)
パッケージ ID。 これはスコープ フィルターの 1 つです
これは、特定の Windows ストア アプリ パッケージから生成されたイベントに対してプロバイダーをフィルター処理するために使用できます。
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)
パッケージの相対アプリ ID (PRAID)。 これはスコープ フィルターの 1 つです
これは、特定の Windows ストア アプリ パッケージから生成されたイベントに対してプロバイダーをフィルター処理するために使用できます。
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)
イベント ペイロード (イベントの内容)。
イベント ペイロード フィルターの最大データ サイズ (バイト単位) は、evntprov.h ヘッダー ファイルで定義MAX_EVENT_FILTER_PAYLOAD_SIZE 4096 に制限されます。
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)
イベント ID。
この機能を使用すると、イベントの一覧のフィルター処理を有効または無効にできます。 指定されたフィルター には、イベント ID の配列と、指定したイベントのフィルター処理を有効または無効にするかどうかを示すブール値を含むEVENT_FILTER_EVENT_ID構造体が含まれます。 各イベント書き込み呼び出しは、イベントのログ記録を有効または無効にするかどうかを確認するために、この配列をすばやく通過します。
TraceLogging プロバイダーに適用すると、トレース ログ イベントに静的イベント ID がないため、このフィルターは無視されます。
EVENT_FILTER_EVENT_ID構造体で許可されるイベント ID の最大数は、evntprov.h ヘッダー ファイルで定義MAX_EVENT_FILTER_EVENT_ID_COUNT 64 に制限されます。
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)
TraceLogging イベント名。
この機能を使用すると、名前に基づいてトレース ログ イベントを有効または無効にすることができます。 指定されたフィルターには、イベント名、キーワード (keyword)ビットマスク、フィルター処理するレベルの配列、および説明されたイベントを有効または無効にするかどうかを示すブール値を含むEVENT_FILTER_EVENT_NAME構造体が含まれます。 TraceLogging 以外のプロバイダーに適用された場合、これらのイベントにはペイロードに名前が指定されていないため、このフィルターは無視されます。
メモ：Windows 10 バージョン 1709 以降で使用できます。
EVENT_FILTER_TYPE_STACKWALK (0x80001000)
スタック ウォーク。
プロバイダーに対してスタック ウォークが有効になっている場合、プロバイダーによって生成されたすべてのイベントに対してスタックがキャプチャされます。 ほとんどの場合、ユーザーは特定の数のイベントからのみスタックに関心があります。
この機能を使用すると、イベントの一覧でスタック ウォークを有効または無効にできます。 指定されたフィルター には、イベント ID の配列と、指定したイベントのスタック キャプチャを有効または無効にするかどうかを示すブール値を含むEVENT_FILTER_EVENT_ID構造体が含まれます。 各イベント書き込み呼び出しは、スタックをキャプチャする必要があるかどうかを確認するために、この配列をすばやく通過します。
TraceLogging プロバイダーに適用すると、トレース ログ イベントに静的イベント ID がないため、このフィルターは無視されます。
このフィルターを使用する場合でも、プロバイダーからスタックを収集できるようにプロバイダーを有効にする場合は、ENABLE_TRACE_PARAMETERS構造体にEVENT_ENABLE_PROPERTY_STACK_TRACEを指定する必要があります。
EVENT_FILTER_EVENT_ID構造体で許可されるイベント ID の最大数は、evntprov.h ヘッダー ファイルで定義MAX_EVENT_FILTER_EVENT_ID_COUNT 64 に制限されます。
メモ：Windows 10 バージョン 1709 以降で使用できます。
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)
TraceLogging イベント名。
この機能を使用すると、イベント名に基づいて TraceLogging イベントのスタック コレクションをフィルター処理できます。 指定されたフィルターには、イベント名、キーワード (keyword)ビットマスク、フィルター処理するレベルの配列、および記述されたイベントのスタックを収集するかどうかを示すブール値を含むEVENT_FILTER_EVENT_NAME構造体が含まれます。
TraceLogging 以外のプロバイダーに適用された場合、これらのイベントにはペイロードに名前が指定されていないため、このフィルターは無視されます。
このフィルターを使用する場合でも、プロバイダーからスタックを収集できるようにプロバイダーを有効にする場合は、ENABLE_TRACE_PARAMETERS構造体にEVENT_ENABLE_PROPERTY_STACK_TRACEを指定する必要があります。
メモ：Windows 10 バージョン 1709 以降で使用できます。
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)
イベント レベルとキーワード (keyword)。
この機能を使用すると、イベントのレベルとキーワード (keyword)に基づいて、スタック コレクションをフィルター処理できます。 指定されたフィルターには、キーワード (keyword)ビットマスクとフィルター処理するレベルを含むEVENT_FILTER_LEVEL_KW構造体と、記述されたイベントのスタックを収集するかどうかを示すブール値が含まれます。
このフィルターを使用する場合でも、プロバイダーからスタックを収集できるようにプロバイダーを有効にする場合は、ENABLE_TRACE_PARAMETERS構造体にEVENT_ENABLE_PROPERTY_STACK_TRACEを指定する必要があります。
メモ：Windows 10 バージョン 1709 以降で使用できます。
解説
プロバイダーは、データのレイアウトとその目的を決定します。
Windows 8.1、Windows Server 2012 R2 以降では、イベント ペイロード、スコープ、スタック ウォーク フィルターを EnableTraceEx2 関数とENABLE_TRACE_PARAMETERSおよびEVENT_FILTER_DESCRIPTOR構造体で使用して、ロガー セッション内の特定の条件をフィルター処理できます。 イベント ペイロード フィルターの詳細については、 EnableTraceEx2、 TdhCreatePayloadFilter、および TdhAggregatePayloadFilters 関数と 、ENABLE_TRACE_PARAMETERS および PAYLOAD_FILTER_PREDICATE 構造体に関するページを参照してください。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| Header | evntprov.h |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示