ENABLE_TRACE_PARAMETERS-Struktur (evntrace.h)

Artikel
08/23/2023

Die ENABLE_TRACE_PARAMETERS-Struktur enthält Informationen, die zum Aktivieren eines Anbieters über EnableTraceEx2 verwendet werden.

Syntax

typedef struct _ENABLE_TRACE_PARAMETERS {
  ULONG                    Version;
  ULONG                    EnableProperty;
  ULONG                    ControlFlags;
  GUID                     SourceId;
  PEVENT_FILTER_DESCRIPTOR EnableFilterDesc;
  ULONG                    FilterDescCount;
} ENABLE_TRACE_PARAMETERS, *PENABLE_TRACE_PARAMETERS;

Member

Version

Legen Sie auf ENABLE_TRACE_PARAMETERS_VERSION_2 (2) fest.

EnableProperty

Optionale Einstellungen, die ETW beim Schreiben des Ereignisses einschließen kann. Einige Einstellungen schreiben zusätzliche Daten in den Erweiterten Datenelementabschnitt jedes Ereignisses. Andere Einstellungen steuern, welche Ereignisse in die Ablaufverfolgung einbezogen werden. Um diese optionalen Einstellungen zu verwenden, geben Sie mindestens eins der folgenden Flags an. Legen Sie andernfalls auf 0 fest.

EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0

Filtert Ereignisse heraus, bei denen die Schlüsselwort (keyword) des Ereignisses ist0.

Unterstützt Windows 10, Version 1507 und höher. Dies wird auch unter Windows 8.1 und Windows 7 mit SP1 über einen Patch unterstützt.
EVENT_ENABLE_PROPERTY_PROVIDER_GROUP

Gibt an, dass dieser Aufruf von EnableTraceEx2 eine Anbietergruppe anstelle eines einzelnen Ereignisanbieters aktivieren soll.

Unterstützt Windows 10, Version 1507 und höher. Dies wird auch unter Windows 8.1 und Windows 7 mit SP1 über einen Patch unterstützt.
EVENT_ENABLE_PROPERTY_PROCESS_START_KEY

Fügen Sie den Prozessstartschlüssel in die erweiterten Daten ein.

Der Prozessstartschlüssel ist eine Sequenznummer, die den Prozess identifiziert. Während die Prozess-ID innerhalb einer Sitzung wiederverwendet werden kann, ist der Prozessstartschlüssel in der aktuellen Startsitzung garantiert eindeutig.

Unterstützt Windows 10, Version 1507 und höher. Dies wird auch unter Windows 8.1 und Windows 7 mit SP1 über einen Patch unterstützt.
EVENT_ENABLE_PROPERTY_EVENT_KEY

Fügen Sie den Ereignisschlüssel in die erweiterten Daten ein.

Der Ereignisschlüssel ist ein eindeutiger Bezeichner für das Ereignis instance, der in mehreren Ablaufverfolgungssitzungen konstant ist, die dieses Ereignis lauschen. Es kann verwendet werden, um gleichzeitige Ablaufverfolgungssitzungen zu korrelieren.

Unterstützt Windows 10, Version 1507 und höher.
EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE

Filtert alle Ereignisse heraus, die entweder als InPrivate-Ereignis gekennzeichnet sind oder aus einem Prozess stammen, der als InPrivate markiert ist.

InPrivate impliziert, dass das Ereignis oder der Prozess einige Daten enthält, die als privat oder persönlich gelten würden. Der Prozess oder das Ereignis muss sich als InPrivate festlegen, damit dies funktioniert.

Unterstützt Windows 10, Version 1507 und höher.
EVENT_ENABLE_PROPERTY_SID

Schließen Sie die Sicherheits-ID (SID) des Benutzers in die erweiterten Daten des Ereignisses ein.

Unterstützt unter Windows Vista und höher.
EVENT_ENABLE_PROPERTY_TS_ID

Schließen Sie den Terminalsitzungsbezeichner in die erweiterten Daten des Ereignisses ein.

Unterstützt unter Windows Vista und höher.
EVENT_ENABLE_PROPERTY_STACK_TRACE

Fügen Sie den erweiterten Daten von Ereignissen, die mit EventWrite geschrieben wurden, eine Aufrufstapelablaufverfolgung hinzu.

Hinweis

ETW löscht das Ereignis, wenn die Gesamtereignisgröße 64K überschreitet. Wenn der Anbieter Ereignisse in der Größe von maximal 64 KB protokolliert, ist es möglich, dass die Aktivierung der Stapelerfassung dazu führt, dass das Ereignis verloren geht.

Wenn der Stapel länger als die maximale Anzahl von Frames (192) ist, werden die Frames vom unteren Rand des Stapels ausgeschnitten.

Für Consumer umfassen die Ereignisse das EVENT_EXTENDED_ITEM_STACK_TRACE32 oder EVENT_EXTENDED_ITEM_STACK_TRACE64 erweiterte Element. Beachten Sie, dass die Ablaufverfolgung auf 64-Bit-Computern beide 64-Bit-Stapel enthält, auch wenn die Ablaufverfolgung von einem 32-Bit-Ablaufverfolgungscontroller gestartet wurde.

Unterstützt unter Windows 7 und höher.

ControlFlags

Reserviert. Auf 0 festlegen.

SourceId

Eine GUID, die den Aufrufer eindeutig identifiziert, der den Anbieter aktiviert oder deaktiviert. Wenn der Anbieter EnableCallback nicht implementiert, wird die GUID nicht verwendet.

EnableFilterDesc

Ein Zeiger auf ein Array von EVENT_FILTER_DESCRIPTOR Strukturen, das auf die Filterdaten zeigt. Die Anzahl der Elemente im Array wird im Element FilterDescCount angegeben. Es kann nur ein Deskriptor für jeden Filtertyp vorhanden sein, der vom Type-Member der EVENT_FILTER_DESCRIPTOR-Struktur angegeben wird.

FilterDescCount

Die Anzahl der Elemente (Filter) im EVENT_FILTER_DESCRIPTOR Arrays, auf das vom EnableFilterDesc-Member verwiesen wird.

Das FilterDescCount-Element sollte mit der Anzahl EVENT_FILTER_DESCRIPTOR Strukturen in dem Array übereinstimmen, auf das vom EnableFilterDesc-Element verwiesen wird.

Hinweise

Die ENABLE_TRACE_PARAMETERS-Struktur ist eine Struktur der Version 2 und ersetzt die ENABLE_TRACE_PARAMETERS_V1-Struktur .

Windows 8.1, Windows Server 2012 R2 und höher: Ereignisnutzlast-, Bereichs- und Stapellauffilter können 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 EVENT_FILTER_DESCRIPTOR und PAYLOAD_FILTER_PREDICATE .

In der Regel können Sie auf 64-Bit-Computern den Kernelstapel in bestimmten Kontexten nicht erfassen, wenn Seitenfehler nicht zulässig sind. Um das Durchlaufen des Kernelstapels auf x64 zu aktivieren, legen Sie den Registrierungswert der DisablePagingExecutive Speicherverwaltung auf 1 fest. Der DisablePagingExecutive Registrierungswert befindet sich unter dem folgenden Registrierungsschlüssel: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management. Dies sollte nur für temporäre Diagnosezwecke erfolgen, da dadurch die Arbeitsspeicherauslastung des Systems erhöht wird.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Kopfzeile	evntrace.h