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

StartTrace

EnableTraceEx2