EVENT_FILTER_DESCRIPTOR 結構 (evntprov.h)

EVENT_FILTER_DESCRIPTOR結構會定義會話傳遞至提供者啟用回呼函式的篩選準則資料。

語法

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

成員

Ptr

類型 成員中所 指定之篩選類型的篩選資料的指標。

如果 Type 成員設定為 EVENT_FILTER_TYPE_PIDPtr 成員會指向 (PID) 的進程識別碼陣列。

如果 Type 成員設定為 EVENT_FILTER_TYPE_EVENT_IDPtr 成員會指向包含事件識別碼陣列的 EVENT_FILTER_EVENT_ID 結構,以及判斷指定事件識別碼的追蹤是否已啟用或停用的布林值。

如果 Type 成員設定為 EVENT_FILTER_TYPE_STACKWALKPtr 成員會指向包含事件識別碼陣列的 EVENT_FILTER_EVENT_ID 結構,以及判斷指定事件識別碼的堆疊追蹤是否已啟用或停用的布林值。

如果 Type 成員設定為 EVENT_FILTER_TYPE_SCHEMATIZED,請參閱 EVENT_FILTER_HEADER 結構,以取得建構篩選的詳細資料。

Size

資料的大小,以位元組為單位。

資料大小上限會根據指定的 Type 成員而有所不同, (篩選) 的類型。 許多篩選類型的資料大小上限限制為 MAX_EVENT_FILTER_DATA_SIZE,在 evntprov.h 標頭檔中定義為 1024。

Type

識別篩選準則的提供者定義值。 針對檢測資訊清單中定義的篩選,請將此成員設定為 EVENT_FILTER_TYPE_SCHEMATIZED

這個成員的可能值定義在 evntprov.h 標頭檔中。

  • EVENT_FILTER_TYPE_NONE (0x00000000)

    沒有篩選。

  • EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

    架構化篩選準則。

    這是傳統的篩選設定,也稱為提供者端篩選。 控制器會將一組自訂篩選定義為二進位物件,該物件會傳遞至EnableTraceEnableTraceEx 或 EnableTraceEx2呼叫中的提供者。 控制器和提供者必須定義和解譯這些篩選準則,而控制器應該只記錄適用的事件。 這需要與控制器和提供者緊密結合,因為無法定義可篩選之物件的二進位物件類型和格式。 TdhEnumerateProviderFilters函式可用來擷取資訊清單中定義的篩選。

    如需架構化篩選的詳細資訊,請參閱 定義篩選

  • EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

    保留供內部使用。

  • EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

    用來擷取特定追蹤會話的取消。 傳遞給EnableTraceEx函式的ControlCode參數必須設定為EVENT_CONTROL_CODE_CAPTURE_STATE而 ProviderId參數必須是SystemTraceControlGuidEVENT_FILTER_DESCRIPTOR結構應該指向代表目前 ETW 會話的單一TRACEHANDLE。 將會針對該特定會話執行取消。

  • EVENT_FILTER_TYPE_PID (0x80000004)

    處理序識別碼。 這是其中一個範圍篩選準則。

    根據進程識別碼篩選 ETW 事件會導致事件資料流程 (檔案或即時) ,其中包含來自指定進程中提供者的事件。 它只會在提供 PID 的進程中啟用提供者。 PID 清單是呼叫 EnableTraceEx2 時所執行之進程的 PID,而且將會在該特定時間) 提供 PID 的所有進程 (啟用提供者。 PID 清單將不會儲存在會話中。 因此,當進程終止並重新出現時,它中的提供者將不會自動啟用至追蹤會話。 PID 型 filter-blob 僅適用于核心模式記錄器會話,因為私人記錄器會話會在使用者模式進程內執行。

    可以篩選的進程識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_PID_COUNT為 8。

    如果提供進程識別碼篩選準則,則只會在使用者模式進程中啟用提供者。 如果相同提供者是由核心模式驅動程式註冊,則不會啟用。

    這與全系統私人記錄器 EVENT_TRACE_PROPERTIES_V2 搭配使用。

  • EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

    可執行檔名稱。 這是其中一個範圍篩選準則。

    這與全系統私人記錄器 EVENT_TRACE_PROPERTIES_V2 搭配使用。

  • EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

    套件識別碼。 這是其中一個範圍篩選準則

    這可用來篩選提供者,以從特定 Windows 市集應用程式套件發出的事件。

  • EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

    套件相對應用程式識別碼 (PRAID) 。 這是其中一個範圍篩選準則

    這可用來篩選提供者,以從特定 Windows 市集應用程式套件發出的事件。

  • EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

    事件承載 (事件) 的內容。

    事件承載篩選的資料大小上限限制為 MAX_EVENT_FILTER_PAYLOAD_SIZEevntprov.h 標頭檔中定義的上限為 4096。

  • EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

    事件識別碼。

    此功能允許啟用或停用事件清單的篩選。 提供的篩選包含 EVENT_FILTER_EVENT_ID 結構,其中包含事件識別碼的陣列,以及指出是否要啟用或停用指定事件的篩選布林值。 每個事件寫入呼叫都會快速完成此陣列,以瞭解啟用或停用記錄事件。

    套用至 TraceLogging 提供者時,將會忽略此篩選,因為 TraceLogging 事件沒有靜態事件識別碼。

    EVENT_FILTER_EVENT_ID結構中允許的事件識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_EVENT_ID_COUNT為 64。

  • EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

    TraceLogging 事件名稱。

    此功能允許根據其名稱啟用或停用 TraceLogging 事件。 提供的篩選包含 EVENT_FILTER_EVENT_NAME 結構,其中包含要篩選的事件名稱陣列、關鍵字位元遮罩和層級,以及指出要啟用或停用描述之事件的布林值。 套用至非 TraceLogging 提供者時,會忽略此篩選,因為這些事件在其承載中沒有指定名稱。

    注意:可在 Windows 10 1709 版和更新版本上使用。

  • EVENT_FILTER_TYPE_STACKWALK (0x80001000)

    堆疊逐步解說。

    當提供者啟用堆疊逐步執行時,就會針對提供者所產生的所有事件擷取堆疊。 大部分時候,使用者只對來自特定事件數目的堆疊感興趣。

    此功能允許在事件清單上啟用或停用堆疊逐步執行。 提供的篩選包含 EVENT_FILTER_EVENT_ID 結構,其中包含事件識別碼的陣列,以及指出是否要啟用或停用指定事件的堆疊擷取的布林值。 每個事件寫入呼叫都會快速完成此陣列,以找出是否應該擷取堆疊。

    套用至 TraceLogging 提供者時,將會忽略此篩選,因為 TraceLogging 事件沒有靜態事件識別碼。

    如果您選擇使用此篩選,當您啟用提供者以從提供者收集任何堆疊時,仍然必須在ENABLE_TRACE_PARAMETERS結構中指定EVENT_ENABLE_PROPERTY_STACK_TRACE

    EVENT_FILTER_EVENT_ID結構中允許的事件識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_EVENT_ID_COUNT為 64。

    注意:可在 Windows 10 1709 版和更新版本上使用。

  • EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

    TraceLogging 事件名稱。

    此功能允許根據事件名稱篩選 TraceLogging 事件的堆疊集合。 提供的篩選包含 EVENT_FILTER_EVENT_NAME 結構,其中包含要篩選的事件名稱、關鍵字位元遮罩和層級陣列,以及指出是否要收集所描述事件的堆疊的布林值。

    套用至非 TraceLogging 提供者時,會忽略此篩選,因為這些事件在其承載中沒有指定名稱。

    如果您選擇使用此篩選準則,當您讓提供者完全從提供者收集任何堆疊時,仍然必須在ENABLE_TRACE_PARAMETERS結構上指定EVENT_ENABLE_PROPERTY_STACK_TRACE

    注意:可在 Windows 10 1709 版和更新版本上使用。

  • EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

    事件層級和關鍵字。

    此功能可根據事件的層級和關鍵字,篩選事件的堆疊集合。 提供的篩選包含 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_PARAMETERSEVENT_FILTER_DESCRIPTOR結構可以使用事件承載、範圍和堆疊逐步解說篩選準則,以篩選記錄器會話中的特定條件。 如需事件承載篩選的詳細資訊,請參閱 EnableTraceEx2TdhCreatePayloadFilterTdhAggregatePayloadFilters 函式和 ENABLE_TRACE_PARAMETERSPAYLOAD_FILTER_PREDICATE 結構。

規格需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
標頭 evntprov.h

另請參閱

定義篩選

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_EVENT_ID

EnableCallback

EnableTrace

EnableTraceEx

EnableTraceEx2

PAYLOAD_FILTER_PREDICATE

TdhAggregatePayloadFilters

TdhCreatePayloadFilter