EVENT_FILTER_DESCRIPTOR-Struktur (evntprov.h)

Artikel
08/23/2023

Die EVENT_FILTER_DESCRIPTOR-Struktur definiert die Filterdaten, die eine Sitzung an die Enable-Rückruffunktion des Anbieters übergibt.

Syntax

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

Member

Ptr

Ein Zeiger auf die Filterdaten für den filterten Typ, der im Type-Element angegeben ist.

Wenn das Type-Element auf EVENT_FILTER_TYPE_PID festgelegt ist, zeigt das Ptr-Element auf ein Array von Prozess-IDs (PIDs).

Wenn der Type-Member auf EVENT_FILTER_TYPE_EVENT_ID festgelegt ist, verweist das Ptr-Element auf eine EVENT_FILTER_EVENT_ID-Struktur , die ein Array von Ereignis-IDs und einen booleschen Wert enthält, der bestimmt, ob die Ablaufverfolgung für die angegebenen Ereignis-IDs aktiviert oder deaktiviert ist.

Wenn das Type-Element auf EVENT_FILTER_TYPE_STACKWALK festgelegt ist, verweist das Ptr-Element auf eine EVENT_FILTER_EVENT_ID-Struktur , die ein Array von Ereignis-IDs und einen booleschen Wert enthält, der bestimmt, ob die Stapelablaufverfolgung für die angegebenen Ereignis-IDs aktiviert oder deaktiviert ist.

Wenn der Type-Member auf EVENT_FILTER_TYPE_SCHEMATIZED festgelegt ist, finden Sie in der EVENT_FILTER_HEADER-Struktur Weitere Informationen zum Erstellen des Filters.

Size

Die Größe der Daten in Bytes.

Die maximale Datengröße variiert je nach dem angegebenen Typmember (dem Typ des Filters). Die maximale Datengröße in Bytes ist für viele Filtertypen auf MAX_EVENT_FILTER_DATA_SIZE beschränkt, die in der Headerdatei evntprov.h auf 1024 definiert sind.

Type

Ein vom Anbieter definierter Wert, der den Filter identifiziert. Legen Sie für filter, die in einem Instrumentierungsmanifest definiert sind, diesen Member auf EVENT_FILTER_TYPE_SCHEMATIZED fest.

Die möglichen Werte für diesen Member werden in der Headerdatei evntprov.h definiert.

EVENT_FILTER_TYPE_NONE (0x00000000)

Keine Filter.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

Ein schematisierter Filter.

Dies ist das herkömmliche Filtersetup, das auch als anbieterseitige Filterung bezeichnet wird. Der Controller definiert einen benutzerdefinierten Satz von Filtern als binäres Objekt, das im Aufruf EnableTrace, EnableTraceEx oder EnableTraceEx2 an den Anbieter übergeben wird. Es obliegt dem Controller und anbieter, diese Filter zu definieren und zu interpretieren, und der Controller sollte nur anwendbare Ereignisse protokollieren. Dies erfordert eine enge Kopplung von Controller und Anbieter, da Typ und Format des binären Objekts, das gefiltert werden kann, nicht definiert sind. Die TdhEnumerateProviderFilters-Funktion kann verwendet werden, um die in einem Manifest definierten Filter abzurufen.

Weitere Informationen zu schematisierten Filtern finden Sie unter Definieren von Filtern.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

Für die interne Verwendung reserviert.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

Wird verwendet, um einen Rundown einer bestimmten Ablaufverfolgungssitzung zu erfassen. Der an die EnableTraceEx-Funktion übergebeneControlCode-Parameter muss auf EVENT_CONTROL_CODE_CAPTURE_STATE und der Parameter ProviderId muss systemTraceControlGuid sein. Die EVENT_FILTER_DESCRIPTOR-Struktur sollte auf eine einzelne TRACEHANDLE verweisen, die eine aktuelle ETW-Sitzung darstellt. Ein Rundown wird für diese bestimmte Sitzung ausgeführt.
EVENT_FILTER_TYPE_PID (0x80000004)

Die Prozess-ID. Dies ist einer der Bereichsfilter.

Das Filtern von ETW-Ereignissen basierend auf Prozess-IDs führt zu einem Ereignisdatenstrom (Datei oder Echtzeit), der nur die Ereignisse der Anbieter in den angegebenen Prozessen enthält. Es aktiviert nur den Anbieter in den Prozessen, deren PIDs bereitgestellt werden. Die Liste der PIDs ist die PIDs der Prozesse, die zu dem Zeitpunkt ausgeführt werden, zu dem EnableTraceEx2 aufgerufen wird, und aktiviert den Anbieter in allen Prozessen (für die PIDs bereitgestellt werden) zu diesem bestimmten Zeitpunkt. Die Liste der PIDs wird nicht in der Sitzung gespeichert. Wenn ein Prozess beendet wird und dann wieder angezeigt wird, wird der darin angezeigte Anbieter nicht automatisch für die Ablaufverfolgungssitzung aktiviert. Das PIDs-basierte filter-blob ist nur für eine Protokollierungssitzung im Kernelmodus gültig, da die private Protokollierungssitzung innerhalb eines Benutzermodusprozesses ausgeführt wird.

Die maximale Anzahl von Prozess-IDs, die gefiltert werden können, wird durch MAX_EVENT_FILTER_PID_COUNT , die in der Headerdatei "evntprov.h " definiert sind, auf 8 beschränkt.

Wenn ein Prozess-ID-Filter bereitgestellt wird, wird der Anbieter nur in den Prozessen im Benutzermodus aktiviert. Falls derselbe Anbieter von einem Kernelmodustreiber registriert wird, wird er nicht aktiviert.

Dies wird mit EVENT_TRACE_PROPERTIES_V2 für systemweite private Protokollierungen verwendet.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

Der Name der ausführbaren Datei. Dies ist einer der Bereichsfilter.

Dies wird mit EVENT_TRACE_PROPERTIES_V2 für systemweite private Protokollierungen verwendet.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

Die Paket-ID. Dies ist einer der Bereichsfilter.

Dies kann verwendet werden, um Anbieter nach Ereignissen zu filtern, die von einem bestimmten Windows Store-App-Paket ausgegeben werden.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

Die paketrelative App-ID (PRAID). Dies ist einer der Bereichsfilter.

Dies kann verwendet werden, um Anbieter nach Ereignissen zu filtern, die von einem bestimmten Windows Store-App-Paket ausgegeben werden.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

Die Ereignisnutzlast (der Inhalt des Ereignisses).

Die maximale Datengröße in Bytes für einen Ereignisnutzlastfilter ist auf MAX_EVENT_FILTER_PAYLOAD_SIZE beschränkt, die in der Headerdatei evntprov.h auf 4096 definiert sind.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

Die Ereignis-ID.

Dieses Feature ermöglicht das Aktivieren oder Deaktivieren der Filterung für eine Liste von Ereignissen. Der bereitgestellte Filter enthält eine EVENT_FILTER_EVENT_ID-Struktur , die ein Array von Ereignis-IDs und einen booleschen Wert enthält, der angibt, ob die Filterung für die angegebenen Ereignisse aktiviert oder deaktiviert werden soll. Jeder Ereignisschreibaufruf durchläuft dieses Array schnell, um festzustellen, ob die Protokollierung des Ereignisses aktiviert oder deaktiviert wird.

Wenn dieser Filter auf einen TraceLogging-Anbieter angewendet wird, wird ignoriert, da TraceLogging-Ereignisse keine statischen Ereignis-IDs aufweisen.

Die maximale Anzahl der in der EVENT_FILTER_EVENT_ID-Struktur zulässigen Ereignis-IDs wird durch MAX_EVENT_FILTER_EVENT_ID_COUNT , die in der Headerdatei "evntprov.h " definiert sind, auf 64 beschränkt.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

Der Name des TraceLogging-Ereignisses.

Dieses Feature ermöglicht das Aktivieren oder Deaktivieren von TraceLogging-Ereignissen basierend auf ihren Namen. Der bereitgestellte Filter enthält eine EVENT_FILTER_EVENT_NAME-Struktur, die ein Array von Ereignisnamen, Schlüsselwort (keyword) Bitmasken und eine Ebene enthält, nach der gefiltert werden soll, sowie einen booleschen Wert, der angibt, ob die beschriebenen Ereignisse aktiviert oder deaktiviert werden sollen. Wenn er auf einen Nicht-TraceLogging-Anbieter angewendet wird, wird dieser Filter ignoriert, da für diese Ereignisse keine Namen in der Nutzlast angegeben sind.

Hinweis: Verfügbar unter Windows 10, Version 1709 und höher.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

Ein Stapellauf.

Wenn das Stapelgehen für einen Anbieter aktiviert ist, wird der Stapel für alle vom Anbieter generierten Ereignisse erfasst. In den meisten Fällen ist der Benutzer nur an einem Stapel von nur einer bestimmten Anzahl von Ereignissen interessiert.

Dieses Feature ermöglicht das Aktivieren oder Deaktivieren des Stapels für eine Liste von Ereignissen. Der bereitgestellte Filter enthält eine EVENT_FILTER_EVENT_ID-Struktur , die ein Array von Ereignis-IDs und einen booleschen Wert enthält, der angibt, ob die Stapelerfassung für die angegebenen Ereignisse aktiviert oder deaktiviert werden soll. Jeder Ereignisschreibaufruf durchläuft dieses Array schnell, um herauszufinden, ob der Stapel erfasst werden soll oder nicht.

Wenn dieser Filter auf einen TraceLogging-Anbieter angewendet wird, wird ignoriert, da TraceLogging-Ereignisse keine statischen Ereignis-IDs aufweisen.

Wenn Sie sich für die Verwendung dieses Filters entscheiden, müssen Sie dennoch EVENT_ENABLE_PROPERTY_STACK_TRACE in der ENABLE_TRACE_PARAMETERS-Struktur angeben, wenn sie den Anbieter für beliebige Stapel aktivieren, die von einem Anbieter erfasst werden sollen.

Die maximale Anzahl der in der EVENT_FILTER_EVENT_ID-Struktur zulässigen Ereignis-IDs wird durch MAX_EVENT_FILTER_EVENT_ID_COUNT , die in der Headerdatei "evntprov.h " definiert sind, auf 64 beschränkt.

Hinweis: Verfügbar unter Windows 10, Version 1709 und höher.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

Ein TraceLogging-Ereignisname.

Dieses Feature ermöglicht das Filtern der Stapelsammlung für TraceLogging-Ereignisse basierend auf den Ereignisnamen. Der bereitgestellte Filter enthält eine EVENT_FILTER_EVENT_NAME-Struktur, die ein Array von Ereignisnamen, Schlüsselwort (keyword) Bitmasken und ebene enthält, nach der gefiltert werden soll, sowie einen booleschen Wert, der angibt, ob Stapel für die beschriebenen Ereignisse gesammelt werden sollen oder nicht.

Wenn er auf einen Nicht-TraceLogging-Anbieter angewendet wird, wird dieser Filter ignoriert, da für diese Ereignisse keine Namen in der Nutzlast angegeben sind.

Wenn Sie sich für die Verwendung dieses Filters entscheiden, müssen Sie dennoch EVENT_ENABLE_PROPERTY_STACK_TRACE für die ENABLE_TRACE_PARAMETERS-Struktur angeben, wenn sie den Anbieter für alle Stapel aktivieren, die überhaupt von einem Anbieter erfasst werden können.

Hinweis: Verfügbar unter Windows 10, Version 1709 und höher.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

Ereignisebene und Schlüsselwort (keyword).

Dieses Feature ermöglicht das Filtern der Stapelsammlung nach Ereignissen basierend auf ihrer Ebene und Schlüsselwort (keyword). Der bereitgestellte Filter enthält eine EVENT_FILTER_LEVEL_KW-Struktur, die Schlüsselwort (keyword) Bitmasken und zu filternde Ebene enthält, sowie einen booleschen Wert, der angibt, ob Stapel für die beschriebenen Ereignisse gesammelt werden sollen oder nicht.

Wenn Sie sich für die Verwendung dieses Filters entscheiden, müssen Sie dennoch EVENT_ENABLE_PROPERTY_STACK_TRACE für die ENABLE_TRACE_PARAMETERS-Struktur angeben, wenn sie den Anbieter für alle Stapel aktivieren, die überhaupt von einem Anbieter erfasst werden können.

Hinweis: Verfügbar unter Windows 10, Version 1709 und höher.

Hinweise

Der Anbieter bestimmt das Layout der Daten und deren Zweck.

Auf Windows 8.1, Windows Server 2012 R2 und höher können Ereignisnutzlast-, Bereichs- und Stapellauffilter von der EnableTraceEx2-Funktion und den ENABLE_TRACE_PARAMETERS- und EVENT_FILTER_DESCRIPTOR-Strukturen verwendet werden, um nach bestimmten Bedingungen in einer Protokollierungssitzung zu filtern. Weitere Informationen zu Ereignisnutzlastfiltern finden Sie in den Funktionen EnableTraceEx2, TdhCreatePayloadFilter und TdhAggregatePayloadFilters sowie in den strukturen ENABLE_TRACE_PARAMETERS und PAYLOAD_FILTER_PREDICATE .

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Kopfzeile	evntprov.h