EnableTraceEx-Funktion (evntrace.h)
Ein Ablaufverfolgungssitzungscontroller ruft EnableTraceEx auf, um zu konfigurieren, wie ein ETW-Ereignisanbieter Ereignisse in einer Ablaufverfolgungssitzung protokolliert.
Diese Funktion ist veraltet. Die EnableTraceEx2-Funktion ersetzt diese Funktion.
Syntax
ULONG WMIAPI EnableTraceEx(
[in] LPCGUID ProviderId,
[in, optional] LPCGUID SourceId,
[in] TRACEHANDLE TraceHandle,
[in] ULONG IsEnabled,
[in] UCHAR Level,
[in] ULONGLONG MatchAnyKeyword,
[in] ULONGLONG MatchAllKeyword,
[in] ULONG EnableProperty,
[in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);
Parameter
[in] ProviderId
Die Anbieter-ID (Steuerelement-GUID) des Ereignisanbieters, den Sie konfigurieren möchten.
[in, optional] SourceId
Eine GUID, die die Quelle dieser Konfigurationsanforderung eindeutig identifizieren kann, oder NULL , wenn keine Quellidentität erforderlich ist (entspricht dem Festlegen von SourceId auf &GUID_NULL
). Wenn angegeben, wird dieser Wert als SourceId-Parameter verwendet, wenn die EnableCallback-Funktion des Anbieters aufgerufen wird.
Hinweis
Es gibt nicht immer eine direkte Zuordnung zwischen einem Aufruf von EnableTrace und einem entsprechenden Aufruf von EnableCallback des Anbieters. Wenn Beispielsweise EnableTrace für einen Anbieter aufgerufen wird, der noch nicht registriert wurde, wird der Aufruf von EnableCallback zurückgestellt, bis die Registrierung erfolgt, und wenn eine Ablaufverfolgungsconsumersitzung beendet wird, ruft ETW EnableCallback auf, obwohl kein entsprechender Aufruf von EnableTrace erfolgt ist. In solchen Fällen wird EnableTrace aufgerufen, wobei SourceId auf GUID_NULL festgelegt ist.
[in] TraceHandle
Handle der Ereignisablaufverfolgungssitzung, für die Sie den Anbieter konfigurieren.
Die StartTrace-Funktion gibt dieses Handle zurück, wenn eine neue Ablaufverfolgung gestartet wird. Um das Handle einer vorhandenen Ablaufverfolgung abzurufen, verwenden Sie ControlTrace , um die Ablaufverfolgungseigenschaften basierend auf dem Namen der Ablaufverfolgung abzufragen und dann das Handle aus dem Wnode.HistoricalContext-Feld der zurückgegebenen EVENT_TRACE_PROPERTIES
Daten abzurufen.
[in] IsEnabled
Legen Sie diese Einstellung auf 1 fest, um den Empfang von Ereignissen vom Anbieter zu aktivieren oder die Einstellungen anzupassen, die beim Empfangen von Ereignissen vom Anbieter verwendet werden (z. B. zum Ändern der Ebene und der Schlüsselwörter). Legen Sie auf 0 fest, um den Empfang von Ereignissen vom Anbieter zu deaktivieren.
[in] Level
Ein -Wert, der die maximale Ebene von Ereignissen angibt, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Ebene des Ereignisses kleiner oder gleich diesem Wert ist, zusätzlich zur Erfüllung der Kriterien MatchAnyKeyword und MatchAllKeyword .
Microsoft definiert die Semantik der Ebenen 1 bis 5 wie unten gezeigt. Niedrigere Werte weisen auf schwerwiegendere Ereignisse hin. Jeder Wert von EnableLevel aktiviert die angegebene Ebene und alle schwerwiegenderen Ebenen. Wenn Sie beispielsweise angeben TRACE_LEVEL_WARNING
, erhält Ihr Consumer Warnungen, Fehler und kritische Ereignisse.
Wert | Bedeutung |
---|---|
TRACE_LEVEL_CRITICAL (1) | Ungewöhnliche Beendigungs- oder Beendigungsereignisse |
TRACE_LEVEL_ERROR (2) | Schwerwiegende Fehlerereignisse |
TRACE_LEVEL_WARNING (3) | Warnungsereignisse wie Zuordnungsfehler |
TRACE_LEVEL_INFORMATION (4) | Nicht fehlerbezogene Informationsereignisse |
TRACE_LEVEL_VERBOSE (5) | Detaillierte Diagnoseereignisse |
Die TRACE_LEVEL
Konstanten sind in evntrace.h definiert. Äquivalente WINMETA_LEVEL
Konstanten werden in winmeta.h definiert.
[in] MatchAnyKeyword
64-Bit-Bit-Bitmaske von Schlüsselwörtern, die die Kategorien von Ereignissen bestimmen, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Schlüsselwort (keyword) Bits des Ereignisses mit einem der in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwort (keyword) Bits festgelegt sind, zusätzlich zur Erfüllung der Kriterien Level und MatchAllKeyword.
[in] MatchAllKeyword
64-Bit-Bit-Bitmaske mit Schlüsselwörtern, die die Ereignisse einschränkt, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Schlüsselwort (keyword) Bits des Ereignisses mit allen in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwort (keyword) Bits festgelegt sind, zusätzlich zur Erfüllung der Kriterien Level und MatchAnyKeyword.
Dieser Wert wird häufig auf 0 festgelegt.
[in] EnableProperty
Flags, die spezielle Verhaltensweisen angeben, die die ETW-Runtime beim Sammeln von Ereignissen von diesem Anbieter aktivieren soll. Um spezielle Verhaltensweisen zu aktivieren, geben Sie eines oder mehrere der folgenden Flags an. Legen Sie andernfalls EnableProperty auf 0 fest.
Hinweis
Mehrere dieser Flags weisen darauf hin, dass ETW zusätzliche Informationen in jedes Ereignis aufnehmen sollte. Die Daten werden in den erweiterten Datenelementabschnitt des Ereignisses geschrieben.
Wert | Bedeutung |
---|---|
EVENT_ENABLE_PROPERTY_SID | Schließen Sie die Sicherheits-ID (SID) des Benutzers in die erweiterten Daten ein. |
EVENT_ENABLE_PROPERTY_TS_ID | Schließen Sie den Terminalsitzungsbezeichner in die erweiterten Daten ein. |
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 | Die Ablaufverfolgungssitzung sollte keine Ereignisse aufzeichnen, die den Schlüsselwort (keyword) 0 aufweisen. |
[in, optional] EnableFilterDesc
Eine EVENT_FILTER_DESCRIPTOR Struktur, die auf die Filterdaten verweist. Der Anbieter verwendet dies, um Daten zu filtern, um zu verhindern, dass Ereignisse, die nicht den Filterkriterien entsprechen, in die Sitzung geschrieben werden. Der Anbieter bestimmt das Layout der Daten und wie er den Filter auf die Daten des Ereignisses anwendet. Eine Sitzung kann nur einen Filter an den Anbieter übergeben.
Eine Sitzung kann die TdhEnumerateProviderFilters-Funktion aufrufen, um die Filter zu suchen, für die ein Anbieter Unterstützung registriert hat.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes. Im Folgenden finden Sie einige häufige Fehler und deren Ursachen.
ERROR_INVALID_PARAMETER
Es trifft eine der folgenden Bedingungen zu:
- ProviderId ist NULL.
- TraceHandle ist NULL.
ERROR_INVALID_FUNCTION
Sie können die Ebene nicht aktualisieren, wenn der Anbieter nicht registriert ist.
ERROR_NO_SYSTEM_RESOURCES
Die Anzahl der Ablaufverfolgungssitzungen, die den Anbieter aktivieren können, wurde überschritten.
ERROR_ACCESS_DENIED
Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe und Dienste, die
Performance Log Users
alsLocalSystem
,LocalService
oderNetworkService
ausgeführt werden, können Ereignisanbieter für eine prozessübergreifende Sitzung aktivieren. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, einen Ereignisanbieter zu aktivieren, fügen Sie diesen derPerformance Log Users
Gruppe hinzu, oder lesen Sie EventAccessControl.Windows XP und Windows 2000: Jeder kann einen Ereignisanbieter aktivieren.
Hinweise
Ereignisablaufverfolgungscontroller rufen diese Funktion auf, um die Ereignisanbieter zu konfigurieren, die Ereignisse in die Sitzung schreiben. Beispielsweise kann ein Controller diese Funktion aufrufen, um mit dem Sammeln von Ereignissen von einem Anbieter zu beginnen, die Ebene oder schlüsselwörter der ereignisse anzupassen, die von einem Anbieter erfasst werden, oder um das Sammeln von Ereignissen von einem Anbieter zu beenden.
Diese Funktion ist veraltet. Für zusätzliche Funktionen sollte für neuen Code EnableTraceEx2 verwendet werden.
In den meisten Fällen kann ein Aufruf von EnableTraceEx wie folgt in EnableTraceEx2 konvertiert werden:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
NULL, // SourceId
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // EnableProperty
NULL); // EnableFilterDesc
// Updated equivalent code:
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
NULL); // EnableParameters
In komplexeren Szenarien kann ein Aufruf von EnableTraceEx wie folgt in EnableTraceEx2 konvertiert werden:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
SourceId,
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
EnableProperty,
EnableFilterDesc);
// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
ENABLE_TRACE_PARAMETERS_VERSION_2,
EnableProperty,
0, // ControlFlags
SourceId ? *SourceId : GUID_NULL,
EnableFilterDesc,
EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
&EnableParameters);
Weitere Informationen zur Semantik der Konfiguration von Anbietern für eine Sitzung finden Sie in der Dokumentation zu EnableTraceEx2.
Anforderungen
Unterstützte Mindestversion (Client) | Windows Vista [Desktop-Apps | UWP-Apps] |
Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
Zielplattform | Windows |
Kopfzeile | evntrace.h |
Bibliothek | Advapi32.lib |
DLL | Advapi32.dll |
Weitere Informationen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für