EnableTraceEx2-Funktion (evntrace.h)

  • Artikel

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

Diese Funktion ersetzt die Funktionen EnableTrace und EnableTraceEx .

Syntax

ULONG WMIAPI EnableTraceEx2(
  [in]           TRACEHANDLE              TraceHandle,
  [in]           LPCGUID                  ProviderId,
  [in]           ULONG                    ControlCode,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    Timeout,
  [in, optional] PENABLE_TRACE_PARAMETERS EnableParameters
);

Parameter

[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] ProviderId

Die Anbieter-ID (Steuerelement-GUID) des Ereignisanbieters, den Sie konfigurieren möchten.

[in] ControlCode

Sie können einen der folgenden Steuercodes angeben:

Wert Bedeutung
EVENT_CONTROL_CODE_DISABLE_PROVIDER Aktualisieren Sie die Sitzungskonfiguration, damit die Sitzung keine Ereignisse vom Anbieter empfängt.
EVENT_CONTROL_CODE_ENABLE_PROVIDER Aktualisieren Sie die Sitzungskonfiguration, damit die Sitzung die angeforderten Ereignisse vom Anbieter empfängt.
EVENT_CONTROL_CODE_CAPTURE_STATE Fordert an, dass der Anbieter seine Statusinformationen protokolliert.

[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 Level 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 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ü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-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üsselwort (keyword) Bits des Ereignisses mit allen bits übereinstimmen, die in diesem Wert festgelegt sind, 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] Timeout

Wenn Timeout 0 ist, beginnt diese Funktion mit der asynchronen Konfiguration des Anbieters und wird sofort zurückgegeben (d. h. es wird zurückgegeben, ohne auf den Abschluss der Anbieterrückrufe zu warten).

Andernfalls beginnt diese Funktion mit der Konfiguration des Anbieters und wartet dann auf den Abschluss der Konfiguration, einschließlich des Wartens auf den Abschluss aller Anbieterrückrufe. Wenn die Konfiguration vor dem angegebenen Timeout abgeschlossen ist, gibt diese Funktion ERROR_SUCCESS zurück. Andernfalls gibt diese Funktion ERROR_TIMEOUT zurück.

Um ewig zu warten, legen Sie auf UNENDLICH fest.

[in, optional] EnableParameters

Die Ablaufverfolgungsparameter, die zum Aktivieren des Anbieters verwendet werden. Ausführliche Informationen finden Sie unter ENABLE_TRACE_PARAMETERS.

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

    Ein Parameter ist falsch.

    Dies kann auftreten, wenn eine der folgenden Punkte zutrifft:

    • Die ProviderId ist NULL.
    • TraceHandle ist 0.

  • ERROR_TIMEOUT

    Der Timeoutwert ist abgelaufen, bevor der Rückruf aktiviert wurde. Ausführliche Informationen finden Sie im Timeoutparameter .

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

Das Aktivierungsverhalten für einen Anbieter hängt davon ab, welche APIs der Anbieter verwendet.

  • Ein Anbieter, der RegisterTraceGuids verwendet (z. B. ein Anbieter, der TMF-basiertes WPP oder MOF verwendet) verwendet das Legacy-Aktivierungssystem (manchmal auch als "klassische ETW" bezeichnet). Wenn ein Legacyanbieter für eine Sitzung aktiviert oder neu konfiguriert wird, benachrichtigt die ETW-Runtime den Anbieter und gewährt Zugriff auf die Ebene, die niedrigen 32 Bits der MatchAnyKeyword-Maske und die Sitzungs-ID. Der Anbieter verwendet dann seine eigene Logik, um zu entscheiden, welche Ereignisse aktiviert werden sollen, und sendet diese Ereignisse direkt an die angegebene Sitzung. Die zur Laufzeit an ETW gesendeten Ereignisdaten enthalten die Decodierungs-GUID und die Nachrichten-ID des Ereignisses, aber nicht die Steuerelement-GUID, ebene oder Schlüsselwörter des Ereignisses. ETW überprüft, ob der Anbieter über die erforderlichen Berechtigungen verfügt, und fügt die Ereignisdaten dann der angegebenen Sitzung hinzu.
    • Da die Ereignisse direkt an eine bestimmte Sitzung ohne Steuerungs-GUID, Ebene oder Schlüsselwort (keyword) Informationen gesendet werden, kann ETW keine zusätzliche Filterung oder Routing für Anbieter durchführen, die das Legacyaktivierungssystem verwenden. Jedes Ereignis kann an nicht mehr als eine Sitzung weitergeleitet werden.
  • Ein Anbieter, der EventRegister verwendet (z. B. ein manifestbasierter Anbieter oder ein TraceLogging-Anbieter), verwendet das moderne Aktivierungssystem (manchmal auch als "crimson ETW" bezeichnet). Wenn ein moderner Anbieter für eine Sitzung aktiviert oder neu konfiguriert wird, benachrichtigt die ETW-Runtime den Anbieter mit der Ebene, der 64-Bit-MatchAnyKeyword-Maske, der 64-Bit-MatchAllKeyword-Maske und allen vom Ablaufverfolgungscontroller angegebenen benutzerdefinierten anbieterseitigen Filterdaten. Der Anbieter verwendet dann seine eigene Logik, um zu entscheiden, welche Ereignisse aktiviert werden sollen, obwohl die meisten Anbieter nur die Logik von EventProviderEnabled duplizieren. Der Anbieter sendet die aktivierten Ereignisse zum Routing an ETW. Die an ETW gesendeten Ereignisdaten umfassen die Steuerelement-GUID, die Nachrichten-ID, die Ebene und die Schlüsselwörter des Ereignisses. ETW führt dann ggf. zusätzliche Filterung durch, wobei das Ereignis an die entsprechenden Sitzungen weitergeleitet wird.
    • Da die Ereignisse mit aussagekräftigen Informationen an ETW gesendet werden, kann ETW zusätzliche Filterung und Routing durchführen, bevor das Ereignis zur Sitzung hinzugefügt wird. Ereignisse können ggf. an mehrere Sitzungen weitergeleitet werden.

Für Anbieter, die das moderne Aktivierungssystem verwenden (d. h. Anbieter, die EventRegister verwenden), unterstützt ETW mehrere Features, die vom Ablaufverfolgungssitzungscontroller über EnableTraceEx2EnableParameters angefordert werden können. (Weitere Informationen finden Sie unter EVENT_FILTER_DESCRIPTOR .)

  • Schematisierte Filterung : Dies ist die herkömmliche Filtereinrichtung, die auch als anbieterseitige Filterung bezeichnet wird. Der Controller definiert einen benutzerdefinierten Satz von Filtern als binäres Objekt, das in EnableCallbackFilterData an den Anbieter übergeben wird. Es obliegt dem Controller und dem Anbieter, diese Filter zu definieren und zu interpretieren. Der Anbieter kann dann den Parameter EventWriteEx-Filter verwenden, um Sitzungen anzugeben, an die ein Ereignis aufgrund der anbieterseitigen Filterung nicht gesendet werden soll. 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.
  • Bereichsfilterung : Bestimmte Anbieter werden für eine Sitzung aktiviert oder nicht, je nachdem, ob sie die in den Bereichsfiltern angegebenen Kriterien erfüllen oder nicht. Es gibt mehrere Arten von Bereichsfiltern, die eine Filterung basierend auf der Prozess-ID (PID), dem Dateinamen der ausführbaren Datei, der App-ID und dem Namen des App-Pakets ermöglichen. Dieses Feature wird unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
  • Stackwalk-Filterung : Dadurch wird ETW benachrichtigt, nur einen Stapellauf für einen bestimmten Satz von Ereignis-IDs oder (für TraceLogging-Ereignisse) Ereignisnamen auszuführen. Dieses Feature wird unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
  • Attributfilterung: Bei Manifestanbietern können Ereignisse basierend auf Ereignisattributen wie Ebene, Schlüsselwort (keyword), Ereignis-ID oder Ereignisname gefiltert werden.
  • Filterung von Ereignisnutzlasten : Bei Manifestanbietern können Ereignisse direkt danach gefiltert werden, ob sie einen logischen Ausdruck basierend auf einem oder mehreren Prädikaten erfüllen oder nicht.

Hinweis

Obwohl ETW leistungsstarke Nutzlast- und Attributfilterung unterstützt, sollten Ereignisse in erster Linie auf Der Grundlage von Bereichsfiltern oder über steuerungsbasierte GUID, Ebene und Schlüsselwort (keyword) gefiltert werden. Anbieter führen in der Regel Steuerungs-GUID, Level und Schlüsselwort (keyword) Filterung direkt im Code des Anbieters aus, bevor das Ereignis generiert oder an ETW gesendet wird. In den meisten Anbietern haben Ereignisse, die nach Ebene oder Schlüsselwort (keyword) deaktiviert sind, fast keine Auswirkungen auf die Systemleistung. Ebenso haben Anbieter, die durch Bereichsfilter deaktiviert sind, fast keine Auswirkungen auf die Systemleistung. Andere Filterarten (basierend auf Nutzlast oder anderen Attributen als Ebene und Schlüsselwort (keyword)) werden in der Regel ausgeführt, nachdem der Anbieter das Ereignis generiert und an die ETW-Laufzeit gesendet hat, was bedeutet, dass das Ereignis Auswirkungen auf die Systemleistung hat (die CPU-Zeit, die das Ereignis vorbereitet und an ETW gesendet hat), auch wenn die ETW-Filterung bestimmt, dass das Ereignis von keiner Sitzung aufgezeichnet werden soll. Diese Art der Filterung ist nur effektiv, um das Volumen von Ablaufverfolgungsdaten zu reduzieren, und ist nicht so effektiv, um den CPU-Overhead der Ablaufverfolgung zu reduzieren.

Jedes Mal, wenn EnableTraceEx2 aufgerufen wird, werden die Filter für den Anbieter in dieser Sitzung durch die neuen Parameter ersetzt, die durch die parameter definiert werden, die an die EnableTraceEx2-Funktion übergeben werden. Mehrere Filter, die in einem einzelnen EnableTraceEx2-Aufruf übergeben werden, können mit einem additiven Effekt kombiniert werden, aber Filter, die in einem nachfolgenden Aufruf übergeben werden, ersetzen den vorherigen Satz von Filtern.

Um die Filterung zu deaktivieren und damit alle Anbieter/Ereignisse in der Protokollierungssitzung zu aktivieren, rufen Sie EnableTraceEx2 auf, wobei der Parameter EnableParameters auf eine ENABLE_TRACE_PARAMETERS Struktur zeigt, wobei das FilterDescCount-Element auf 0 festgelegt ist.

Jeder an die EnableTraceEx2-Funktion übergebene Filter wird von einem Type-Member im EVENT_FILTER_DESCRIPTOR angegeben. Ein Array von EVENT_FILTER_DESCRIPTOR Strukturen wird in der ENABLE_TRACE_PARAMETERS-Struktur übergeben, die im EnableParameters-Parameter an die EnableTraceEx2-Funktion übergeben wird.

Jeder Filtertyp (ein bestimmtes Type-Element ) kann nur einmal in einem Aufruf der EnableTraceEx2-Funktion angezeigt werden. Bei einigen Filtertypen können mehrere Bedingungen in einen einzelnen Filter eingeschlossen werden. Die maximale Anzahl von Filtern, die in einen Aufruf von EnableTraceEx2 eingeschlossen werden können, wird durch MAX_EVENT_FILTERS_COUNT festgelegt (definiert in der Headerdatei Evntprov.h ; der Wert kann sich in zukünftigen Versionen des Windows SDK ändern).

Jeder Filtertyp verfügt über eigene Größen- oder Entitätsgrenzwerte basierend auf dem spezifischen Type-Element in der EVENT_FILTER_DESCRIPTOR-Struktur . Die folgende Liste gibt diese Grenzwerte an.

  • EVENT_FILTER_TYPE_SCHEMATIZED

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl der zulässigen Elemente: Durch Anbieter und Controller definiert

  • EVENT_FILTER_TYPE_PID

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl der zulässigen Elemente: MAX_EVENT_FILTER_PID_COUNT (8)

  • EVENT_FILTER_TYPE_EXECUTABLE_NAME

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl der zulässigen Elemente: Eine einzelne Zeichenfolge, die mehrere ausführbare Dateinamen enthalten kann, die durch Semikolons getrennt sind.

  • EVENT_FILTER_TYPE_PACKAGE_ID

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl der zulässigen Elemente: Eine einzelne Zeichenfolge, die mehrere Paket-IDs enthalten kann, die durch Semikolons getrennt sind.

  • EVENT_FILTER_TYPE_PACKAGE_APP_ID

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl der zulässigen Elemente: Eine einzelne Zeichenfolge, die mehrere durch Semikolons getrennte paketbezogene App-IDs (PRAIDs) enthalten kann.

  • EVENT_FILTER_TYPE_PAYLOAD

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_PAYLOAD_SIZE (4096)
    • Anzahl der zulässigen Elemente: 1

  • EVENT_FILTER_TYPE_EVENT_ID

    • Filtergrößenlimit: Nicht definiert
    • Anzahl der zulässigen Elemente: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

  • EVENT_FILTER_TYPE_STACKWALK

    • Filtergrößenlimit: Nicht definiert
    • Anzahl der zulässigen Elemente: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

Schlüsselwörter definieren Ereigniskategorien. Wenn der Anbieter beispielsweise InitializationKeyword = 0x1 (Schlüsselwort (keyword) Bit 0), FileOperationKeyword = 0x2 (Schlüsselwort (keyword) Bit 1) und CalculationKeyword = 0x4 (Schlüsselwort (keyword) Bit 2) definiert, können Sie MatchAnyKeyword festlegen. to (InitializationKeyword | CalculationKeyword) = 5, um Initialisierungs- und Berechnungsereignisse zu empfangen, aber keine Dateiereignisse.

Bei Verwendung mit modernen (manifestbasierten oder TraceLogging)-Anbietern wird ein MatchAnyKeyword-Wert von 0 gleich behandelt wie ein MatchAnyKeyword-Wert von 0xFFFFFFFFFFFFFFFF, d. h. er aktiviert alle Ereignisschlüsselwörter. Dieses Verhalten gilt jedoch nicht für Ältere (MOF- oder TMF-basierte WPP-Anbieter). Um alle Ereignisschlüsselwörter eines Legacyanbieters zu aktivieren, legen Sie MatchAnyKeyword auf fest 0xFFFFFFFF. Um alle Ereignisschlüsselwörter von Legacy- und modernen Anbietern zu aktivieren, legen Sie MatchAnyKeyword auf fest 0xFFFFFFFFFFFFFFFF.

Wenn der Schlüsselwort (keyword) eines Ereignisses null ist, schreibt der Anbieter das Ereignis unabhängig von den Masken MatchAnyKeyword und MatchAllKeyword in die Sitzung. (Dieses Verhalten kann mithilfe des flags EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 deaktiviert werden.)

Um anzugeben, dass Sie eine Anbietergruppe aktivieren möchten, verwenden Sie das EVENT_ENABLE_PROPERTY_PROVIDER_GROUP Flag für das EnableProperty-Element von EnableParameters.

Wenn Sie EnableTraceEx2 aufrufen, ist der Anbieter möglicherweise bereits registriert. Wenn der Anbieter bereits registriert ist, ruft ETW die Rückruffunktion des Anbieters (falls vorhanden) auf, und die Sitzung empfängt Ereignisse. Wenn der Anbieter noch nicht registriert ist, ruft ETW die Rückruffunktion des Anbieters (falls vorhanden) sofort nach der Registrierung des Anbieters auf, und die Sitzung beginnt dann mit dem Empfang von Ereignissen. Wenn der Anbieter noch nicht registriert ist, erhält die Rückruffunktion des Anbieters die Quell-ID nicht.

Wenn der Anbieter registriert und bereits für Ihre Sitzung aktiviert ist, können Sie EnableTraceEx2 erneut aufrufen, um die Parameter Level, MatchAnyKeyword, MatchAllKeyword und enableProperty und EnableFilterDesc von EnableParameters zu aktualisieren.

Unter 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 TdhCreatePayloadFilter und TdhAggregatePayloadFilters sowie in den Strukturen ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR und PAYLOAD_FILTER_PREDICATE .

Spezielle Systemablaufverfolgungsanbieterereignisse können von EnableTraceEx2 nicht aktiviert oder deaktiviert werden. Sie können nur über das Feld EnableFlags von EVENT_TRACE_PROPERTIES aktiviert werden, wenn die Ablaufverfolgung zum ersten Mal von StartTrace gestartet wird.

Ab Windows 11 können Systemablaufverfolgungsanbieterereignisse mithilfe von EnableTraceEx2 aktiviert werden.

Bis zu acht Ablaufverfolgungssitzungen können Ereignisse vom gleichen modernen Anbieter (manifestbasiert oder TraceLogging) aktivieren und empfangen. Allerdings kann nur eine Ablaufverfolgungssitzung einen Legacyanbieter (MOF, TMF-basiertes WPP) aktivieren. Wenn mehr als eine Sitzung versucht, einen Legacyanbieter zu aktivieren, empfängt die erste Sitzung keine Ereignisse mehr, wenn die zweite Sitzung denselben Anbieter aktiviert. Wenn beispielsweise Sitzung A einen Legacyanbieter aktiviert hat und Sitzung B dann denselben Anbieter aktiviert hat, empfängt nur Sitzung B Ereignisse von diesem Anbieter.

Ein Anbieter bleibt für die Sitzung aktiviert, bis die Sitzung den Anbieter deaktiviert. Wenn die Anwendung, die die Sitzung gestartet hat, ohne den Anbieter zu deaktivieren, beendet wird, bleibt der Anbieter aktiviert.

Verwenden Sie einen der folgenden Befehle, um die Ebene und die Schlüsselwörter zu bestimmen, die zum Aktivieren eines manifestbasierten Anbieters verwendet werden:

  • Anbietername der Logman-Abfrageanbieter
  • wevtutil gp provider-name

Bei klassischen Anbietern liegt es beim Anbieter, die unterstützten Schweregrade oder Aktivierungsflags zu dokumentieren und potenziellen Controllern zur Verfügung zu stellen. Wenn der Anbieter von einem Controller aktiviert werden möchte, sollte der Anbieter 0 für den Schweregrad akzeptieren und Flags aktivieren und 0 als Anforderung zum Ausführen der Standardprotokollierung interpretieren (was auch immer dies sein mag).

Wenn Sie EnableTraceEx2 verwenden, um einen klassischen Anbieter zu aktivieren, erfolgt die folgende Übersetzung:

  • Der Level-Parameter entspricht dem Festlegen des EnableLevel-Parameters in EnableTrace.
  • MatchAnyKeyword entspricht dem Festlegen des EnableFlag-Parameters in EnableTrace, mit der Ausnahme, dass der Schlüsselwort (keyword) Wert von einem 64-Bit-Wert auf einen 32-Bit-Wert abgeschnitten wird.
  • Im ControlCallback-Rückruf kann der Anbieter GetTraceEnableLevel aufrufen, um die Ebene abzurufen, und GetTraceEnableFlags , um das Enable-Flag abzurufen.
  • Der andere Parameter wird nicht verwendet.

Beispiele

Das folgende Beispiel zeigt die Verwendung von EnableTraceEx2 mit Nutzlastfiltern, die die Funktionen TdhCreatePayloadFilter und TdhAggregatePayloadFilters verwenden, um nach bestimmten Bedingungen in einer Protokollierungssitzung zu filtern.

#define INITGUID
#include <windows.h>
#include <stdlib.h>
#include <stdio.h>
#include <strsafe.h>
#include <evntrace.h>
#include <tdh.h>

#define MAXIMUM_SESSION_NAME 1024

#define PATH_TO_MANIFEST_FILE L"c:\\ExampleManifest.man"

//
// The following definitions would be found in the include file generated by
// message compiler from the manifest file.
//

// Provider Example-Provider Event Count 2
EXTERN_C __declspec(selectany) const GUID EXAMPLE_PROVIDER = {0x37a59b93, 0xbb25, 0x4cee, {0x97, 0xaa, 0x8b, 0x6a, 0xcd, 0xc, 0x4d, 0xf8}};

//
// Event Descriptors
//
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_1 = { 0x1, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_1_value 0x1
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_2 = { 0x2, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_2_value 0x2

//
// (End of snippet from include file)
//

// Allocate an EVENT_TRACE_PROPERTIES structure and set the needed logging session properties
PEVENT_TRACE_PROPERTIES AllocateTraceProperties(
    _In_opt_ PCWSTR LoggerName,
    _In_opt_ PCWSTR LogFileName
)
{
    PEVENT_TRACE_PROPERTIES TraceProperties = NULL;
    ULONG BufferSize;

    BufferSize = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME + MAX_PATH) * sizeof(WCHAR);

    TraceProperties = (PEVENT_TRACE_PROPERTIES)malloc(BufferSize);
    if (TraceProperties == NULL) {
        printf("Unable to allocate %d bytes for properties structure.\n", BufferSize);
        goto Exit;
    }

    //
    // Set the session properties.
    //
    ZeroMemory(TraceProperties, BufferSize);
    TraceProperties->Wnode.BufferSize = BufferSize;
    TraceProperties->Wnode.Flags = WNODE_FLAG_TRACED_GUID;
    TraceProperties->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
    TraceProperties->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME * sizeof(WCHAR));

    if (LoggerName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LoggerNameOffset),
            MAXIMUM_SESSION_NAME,
            LoggerName);
    }

    if (LogFileName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LogFileNameOffset),
            MAX_PATH,
            LogFileName);
    }

Exit:
    return TraceProperties;
}

// Free the EVENT_TRACE_PROPERTIES structure previously allocated
VOID FreeTraceProperties(
    _In_ PEVENT_TRACE_PROPERTIES TraceProperties
)
{
    free(TraceProperties);
    return;
}

// Set the values needed in a PAYLOAD_FILTER_PREDICATE for a single payload filter
FORCEINLINE VOID PayloadPredicateCreate(
    _Out_ PAYLOAD_FILTER_PREDICATE* Predicate,
    _In_ PCWSTR FieldName,
    USHORT CompareOp,
    PCWSTR Value
)
{
    Predicate->FieldName = (PWSTR)FieldName;
    Predicate->CompareOp = CompareOp;
    Predicate->Value = (PWSTR)Value;
    return;
}

int __cdecl wmain()
{
    UINT i;
    PVOID EventFilters[2];
    EVENT_FILTER_DESCRIPTOR FilterDescriptor;
    UINT PredicateCount;
    PAYLOAD_FILTER_PREDICATE Predicates[3];
    ULONG FilterCount;
    ULONG Status = ERROR_SUCCESS;
    TRACEHANDLE SessionHandle = 0;
    PEVENT_TRACE_PROPERTIES TraceProperties;
    BOOLEAN TraceStarted = FALSE;
    PCWSTR LoggerName = L"MyTrace";
    ENABLE_TRACE_PARAMETERS EnableParameters;

    ZeroMemory(EventFilters, sizeof(EventFilters));
    ZeroMemory(Predicates, sizeof(Predicates));
    TraceProperties = NULL;
    FilterCount = 0;

    //
    // Load the manifest for the provider
    //
    Status = TdhLoadManifest((PWSTR)PATH_TO_MANIFEST_FILE);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    //
    // INCLUDE Example_Event_1 IF
    //     Example_Event_1.Initiator == "User" AND
    //     7 <= Example_Event_1.Level <= 16
    //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        (PWSTR)L"Initiator",
        PAYLOADFIELD_IS,
        (PWSTR)L"User");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Level",
        PAYLOADFIELD_BETWEEN,
        L"7,16");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_1,
        FALSE,      // Match all predicates (AND)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    // INCLUDE Example_Event_2 IF
    //      Example_Event_2.Title CONTAINS "UNI" OR
    //      Example_Event_2.InstanceId == {0E95CFBC-58D4-44BA-BE40-E63A853536DF} OR
    //      Example_Event_2.ErrorCode != 0      //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Title",
        PAYLOADFIELD_CONTAINS,
        L"UNI");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"InstanceId",
        PAYLOADFIELD_IS,
        L" {0E95CFBC-58D4-44BA-BE40-E63A853536DF}");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"ErrorCode",
        PAYLOADFIELD_NE,
        L"0");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_2,
        FALSE,      // Match any predicates (OR)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Combine the interim filters into a final filter descriptor.
    //
    Status = TdhAggregatePayloadFilters(
        FilterCount,
        EventFilters,
        NULL,
        &FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhAggregatePayloadFilters() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the interim filters
    //
    for (i = 0; i < FilterCount; i++) {

        Status = TdhDeletePayloadFilter(&EventFilters[i]);
        if (Status != ERROR_SUCCESS) {
            printf("TdhDeletePayloadFilter() failed with %lu\n", Status);
            goto Exit;
        }
    }

    //
    // Create a new trace session
    //
    //
    // Allocate EVENT_TRACE_PROPERTIES structure and perform some
    // basic initialization.
    //
    // N.B. LoggerName will be populated during StartTrace call.
    //
    TraceProperties = AllocateTraceProperties(NULL, L"SystemTrace.etl");
    if (TraceProperties == NULL) {
        Status = ERROR_OUTOFMEMORY;
        goto Exit;
    }

    TraceProperties->LogFileMode = EVENT_TRACE_FILE_MODE_SEQUENTIAL | EVENT_TRACE_SYSTEM_LOGGER_MODE;
    TraceProperties->MaximumFileSize = 100; // Limit file size to 100MB max
    TraceProperties->BufferSize = 512; // Use 512KB trace buffers
    TraceProperties->MinimumBuffers = 8;
    TraceProperties->MaximumBuffers = 64;

    Status = StartTraceW(&SessionHandle, LoggerName, TraceProperties);
    if (Status != ERROR_SUCCESS) {
        printf("StartTrace() failed with %lu\n", Status);
        goto Exit;
    }

    TraceStarted = TRUE;

    //
    // Enable the provider to a trace session with filtering enabled on the
    // provider
    //
    ZeroMemory(&EnableParameters, sizeof(EnableParameters));
    EnableParameters.Version = ENABLE_TRACE_PARAMETERS_VERSION_2;
    EnableParameters.EnableFilterDesc = &FilterDescriptor;
    EnableParameters.FilterDescCount = 1;

    Status = EnableTraceEx2(
        SessionHandle,
        &EXAMPLE_PROVIDER,
        EVENT_CONTROL_CODE_ENABLE_PROVIDER,
        TRACE_LEVEL_VERBOSE,
        0,
        0,
        0,
        &EnableParameters);
    if (Status != ERROR_SUCCESS) {
        printf("EnableTraceEx2() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the payload descriptor
    //
    Status = TdhCleanupPayloadEventFilterDescriptor(&FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCleanupPayloadEventFilterDescriptor() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Collect trace for 30 seconds
    //
    Sleep(30 * 1000);

Exit:

    //
    // Stop tracing.
    //
    if (TraceStarted != FALSE) {
        Status = ControlTraceW(SessionHandle, NULL, TraceProperties, EVENT_TRACE_CONTROL_STOP);
        if (Status != ERROR_SUCCESS) {
            printf("StopTrace() failed with %lu\n", Status);
        }
    }

    if (TraceProperties != NULL) {
        FreeTraceProperties(TraceProperties);
    }

    TdhUnloadManifest((PWSTR)PATH_TO_MANIFEST_FILE);

    return Status;
}

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 7 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Sechost.lib unter Windows 8.1 und Windows Server 2012 R2; Advapi32.lib unter Windows 8, Windows Server 2012, Windows 7 und Windows Server 2008 R2
DLL Sechost.dll unter Windows 8.1 und Windows Server 2012 R2; Advapi32.dll unter Windows 8, Windows Server 2012, Windows 7 und Windows Server 2008 R2

Weitere Informationen

StartTrace

ControlTrace

EnableCallback

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_DESCRIPTOR