Freigeben über

EnableTraceEx-Funktion (evntrace.h)

  • Artikel

Ein Ablaufverfolgungssitzungscontroller ruft EnableTraceEx auf, um zu konfigurieren, wie ein ETW-Ereignisanbieter Ereignisse in einer Ablaufverfolgungssitzung protokolliert.

Diese Funktion ist veraltet. Die Funktion EnableTraceEx2 ersetzt diese Funktion.

Syntax

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [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). Falls angegeben, wird dieser Wert als SourceId-Parameter beim Aufrufen des EnableCallback-Anbieters verwendet.

Hinweis

Es gibt nicht immer eine direkte Zuordnung zwischen einem Aufruf von EnableTrace und einem entsprechenden Aufruf des EnableCallback-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 Ablaufverfolgungs-Consumersitzung beendet wird, ruft ETW EnableCallback auf, obwohl kein entsprechender Aufruf von EnableTrace vorhanden war. In solchen Fällen wird EnableTrace aufgerufen, wobei SourceId auf GUID_NULL festgelegt ist.

TraceId

[in] IsEnabled

Legen Sie 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 Ereignisebene 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 schwereren 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 fehlerfreie Informationsereignisse
TRACE_LEVEL_VERBOSE (5) Detaillierte Diagnoseereignisse

Die TRACE_LEVEL Konstanten sind in evntrace.h definiert. Entsprechende WINMETA_LEVEL Konstanten werden in winmeta.h definiert.

[in] MatchAnyKeyword

64-Bit-Bit-Maske 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üsselwortbits des Ereignisses mit einem der in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwortbits festgelegt sind, zusätzlich zur Erfüllung der Kriterien Level und MatchAllKeyword .

[in] MatchAllKeyword

64-Bit-Bit-Bit-Maske von Schlüsselwörtern, die die Ereignisse einschränkt, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Schlüsselwortbits des Ereignisses mit allen in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwortbits 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 mindestens eins der folgenden Flags an. Legen Sie andernfalls EnableProperty auf 0 fest.

Hinweis

Mehrere dieser Flags deuten darauf hin, dass ETW zusätzliche Informationen in jedes Ereignis aufnehmen sollte. Die Daten werden in den Abschnitt des erweiterten Datenelements 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 das Schlüsselwort 0 aufweisen.

[in, optional] EnableFilterDesc

Eine EVENT_FILTER_DESCRIPTOR Struktur, die auf die Filterdaten verweist. Der Anbieter verwendet dies zum Filtern von Daten, 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 Ereignisdaten 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 sind einige häufige Fehler und deren Ursachen aufgeführt.

  • 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 als LocalSystem, LocalServiceoder NetworkService 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 der Performance Log Users Gruppe hinzu, oder sehen Sie sich EventAccessControl an.

    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 der Erfassung von Ereignissen von einem Anbieter zu beginnen, die Ebene oder schlüsselwörter der von einem Anbieter erfassten Ereignisse anzupassen oder um die Erfassung von Ereignissen von einem Anbieter zu beenden.

Diese Funktion ist veraltet. Für zusätzliche Funktionen sollte neuer Code EnableTraceEx2 verwenden.

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 Details zur Semantik der Konfiguration von Anbietern für eine Sitzung finden Sie in der Dokumentation zu EnableTraceEx2.

Anforderungen

Anforderung Wert
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

StartTrace

EnableTraceEx2