Freigeben über

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(
                 CONTROLTRACE_ID          TraceId,
  [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

TraceId

[in] ProviderId

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

[in] ControlCode

Sie können einen der folgenden Steuerelementcodes angeben:

Wert Bedeutung
EVENT_CONTROL_CODE_DISABLE_PROVIDER Aktualisieren Sie die Sitzungskonfiguration, sodass die Sitzung keine Ereignisse vom Anbieter empfängt.
EVENT_CONTROL_CODE_ENABLE_PROVIDER Aktualisieren Sie die Sitzungskonfiguration so, dass 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 Ereignisstufe 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 Besprechung der MatchAnyKeyword- und MatchAllKeyword- Kriterien.

Microsoft definiert die Semantik der Ebenen 1 bis 5, wie unten dargestellt. Niedrigere Werte deuten auf schwerwiegendere Ereignisse hin. Jeder Wert von Level ermöglicht die angegebene Ebene und alle schwereren Ebenen. Wenn Sie z. B. TRACE_LEVEL_WARNINGangeben, erhält Der Verbraucher 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 werden in evntrace.hdefiniert. Entsprechende WINMETA_LEVEL Konstanten werden in winmeta.hdefiniert.

[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üsselwortbits des Ereignisses der in diesem Wert festgelegten Bits übereinstimmen oder wenn das Ereignis keine Stichwortbits festgelegt hat, zusätzlich zur Besprechung der Level und MatchAllKeyword Kriterien.

[in] MatchAllKeyword

64-Bit-Bit-Bitmaske von Schlüsselwörtern, die die Ereignisse einschränken, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Schlüsselwortbits des Ereignisses alle der in diesem Wert festgelegten Bits übereinstimmen oder wenn das Ereignis keine Stichwortbits festgelegt hat, zusätzlich zur Besprechung der Level und MatchAnyKeyword Kriterien.

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. sie wird zurückgegeben, ohne auf den Abschluss von Anbieterrückrufen zu warten).

Andernfalls beginnt diese Funktion mit der Konfiguration des Anbieters und beginnt dann, auf den Abschluss der Konfiguration zu warten, einschließlich des Wartens auf alle Anbieterrückrufe. Wenn die Konfiguration vor dem angegebenen Timeout abgeschlossen ist, gibt diese Funktion ERROR_SUCCESSzurück. Andernfalls gibt diese Funktion ERROR_TIMEOUTzurück.

Um für immer zu warten, legen Sie auf INFINITE.

[in, optional] EnableParameters

Die Ablaufverfolgungsparameter, die zum Aktivieren des Anbieters verwendet werden. Weitere 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 finden Sie einige häufige Fehler und deren Ursachen.

  • ERROR_INVALID_PARAMETER

    Ein Parameter ist falsch.

    Dies kann auftreten, wenn eine der folgenden Bedingungen zutrifft:

    • Die ProviderId- ist NULL-.
    • Die TraceHandle- ist 0.

  • ERROR_TIMEOUT

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

  • 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, Benutzern in der gruppe Performance Log Users und Dienste, die 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 zum Aktivieren eines Ereignisanbieters zu gewähren, fügen Sie sie der gruppe Performance Log Users hinzu, oder sehen Sie EventAccessControl-.

    Windows XP und Windows 2000: Jeder kann einen Ereignisanbieter aktivieren.

Bemerkungen

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, um 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.

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

  • Ein Anbieter, der RegisterTraceGuids verwendet, (z. B. ein Anbieter mit TMF-basiertem WPP oder MOF) verwendet das Legacy-Aktivierungssystem (manchmal auch als "klassisches ETW" bezeichnet). Wenn ein Legacyanbieter für eine Sitzung aktiviert oder neu konfiguriert wird, benachrichtigt die ETW-Laufzeit den Anbieter und bietet Zugriff auf die Ebene, die niedrigen 32 Bits des MatchAnyKeyword-Masken und die Sitzungs-ID. Der Anbieter verwendet dann eine eigene Logik, um zu entscheiden, welche Ereignisse aktiviert werden sollen, und sendet diese Ereignisse direkt an die angegebene Sitzung. Die ereignisdaten, die zur Laufzeit an ETW gesendet werden, umfassen 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 dann die Ereignisdaten zur angegebenen Sitzung hinzu.
    • Da die Ereignisse direkt an eine bestimmte Sitzung ohne Steuerelement-GUID, Ebenen- oder Schlüsselwortinformationen gesendet werden, kann ETW keine zusätzliche Filterung oder Weiterleitung für Anbieter durchführen, die das Legacyaktivierungssystem verwenden. Jedes Ereignis kann 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-Laufzeit den Anbieter mit der Ebene, die 64-Bit-MatchAnyKeyword-Maske, das 64-Bit-MatchAllKeyword-Mask und alle benutzerdefinierten anbieterseitigen Filterdaten, die vom Ablaufverfolgungscontroller angegeben werden. Der Anbieter verwendet dann eine eigene Logik, um zu entscheiden, welche Ereignisse aktiviert werden sollen, obwohl die meisten Anbieter nur die Logik von EventProviderEnabledduplizieren. Der Anbieter sendet die aktivierten Ereignisse zum Routing an ETW. Die an ETW gesendeten Ereignisdaten umfassen die Steuerelement-GUID, Nachrichten-ID, Ebene und Schlüsselwörter des Ereignisses. ETW führt dann nach Bedarf zusätzliche Filterung durch, um das Ereignis an die entsprechenden Sitzungen weiterzuleiten.
    • Da die Ereignisse mit beschreibenden 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 bei Bedarf an mehrere Sitzungen weitergeleitet werden.

Für Anbieter, die das moderne Enablement-System verwenden (d. h. Anbieter mit EventRegister), unterstützt ETW mehrere Features, die vom Ablaufverfolgungssitzungscontroller über EnableTraceEx2EnableParametersangefordert werden können. (Einzelheiten finden Sie unter EVENT_FILTER_DESCRIPTOR.)

  • schematisierte Filterung – Dies ist die herkömmliche Filtereinrichtung, auch als anbieterseitige Filterung bezeichnet. Der Controller definiert einen benutzerdefinierten Satz von Filtern als binäres Objekt, das in EnableCallbackFilterData-an den Anbieter übergeben wird. Es obliegt dem Verantwortlichen und Anbieter, diese Filter zu definieren und zu interpretieren. Der Anbieter kann dann den parameter EventWriteExFilter verwenden, um Sitzungen anzugeben, an die ein Ereignis aufgrund der anbieterseitigen Filterung nicht gesendet werden soll. Dies erfordert eine enge Kopplung des Controllers und anbieters, da der Typ und das Format des binären Objekts, das gefiltert werden kann, nicht definiert ist. Die TdhEnumerateProviderFilters Funktion kann verwendet werden, um die in einem Manifest definierten Filter abzurufen.
  • Bereichsfilterung – Bestimmte Anbieter sind für eine Sitzung aktiviert oder nicht aktiviert, je nachdem, ob sie den durch die Bereichsfilter angegebenen Kriterien entsprechen. Es gibt mehrere Arten von Bereichsfiltern, die das Filtern basierend auf der Prozess-ID (PID), dem ausführbaren Dateinamen, der App-ID und dem Namen des App-Pakets zulassen. 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, Ereignis-ID oder Ereignisname gefiltert werden.
  • Ereignisnutzlastfilterung – Bei Manifestanbietern können Ereignisse direkt gefiltert werden, je nachdem, ob sie einen logischen Ausdruck basierend auf einem oder mehreren Prädikaten erfüllen.

Anmerkung

Obwohl ETW leistungsstarke Nutzlast- und Attributfilter unterstützt, sollten Ereignisse in erster Linie basierende Bereichsfilter oder über die Steuerelement-GUID, -Ebene und -Schlüsselwort gefiltert werden. Anbieter führen in der Regel Steuerelement-GUID-, Level- und Schlüsselwortfilter 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 deaktiviert sind, fast keine Auswirkungen auf die Systemleistung. Ebenso haben Anbieter, die durch Bereichsfilter deaktiviert sind, fast keine Auswirkungen auf die Systemleistung. Andere Arten von Filtern (basierend auf Nutzlast oder Attributen außer Ebene und Schlüsselwort) werden normalerweise 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 nicht von Sitzungen aufgezeichnet werden sollte. Diese Art von Filterung ist nur effektiv bei der Reduzierung des Ablaufverfolgungsdatenvolumens und ist nicht so effektiv, um den CPU-Aufwand 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 an die EnableTraceEx2 Funktion übergebenen Parameter definiert sind. Mehrere Filter, die in einem einzelnen EnableTraceEx2 Aufruf übergeben werden, können mit einem additiven Effekt kombiniert werden, aber in einem nachfolgenden Aufruf übergebene Filter werden die vorherigen Filtergruppen ersetzt.

Um die Filterung zu deaktivieren und dadurch alle Anbieter/Ereignisse in der Protokollierungssitzung zu aktivieren, rufen Sie EnableTraceEx2- mit dem EnableParameters-Parameter auf eine ENABLE_TRACE_PARAMETERS Struktur auf, wobei der FilterDescCount Member auf 0 festgelegt ist.

Jeder Filter, der an die EnableTraceEx2--Funktion übergeben wird, wird durch ein Type Member in der EVENT_FILTER_DESCRIPTORangegeben. An array of EVENT_FILTER_DESCRIPTOR structures is passed in the ENABLE_TRACE_PARAMETERS structure passed in the EnableParameters parameter to the EnableTraceEx2 function.

Jeder Filtertyp (ein bestimmter Type Member) kann nur einmal in einem Aufruf der EnableTraceEx2--Funktion angezeigt werden. Einige Filtertypen ermöglichen das Einbeziehen mehrerer Bedingungen in einen einzelnen Filter. Die maximale Anzahl von Filtern, die in einem Aufruf von EnableTraceEx2- enthalten sein können, wird durch MAX_EVENT_FILTERS_COUNT festgelegt (definiert in der Evntprov.h Headerdatei; der Wert kann sich in zukünftigen Versionen des Windows SDK ändern).

Jeder Filtertyp verfügt über eigene Größen- oder Entitätsbeschränkungen basierend auf dem spezifischen Type Member 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: Vom Anbieter und Controller definiert

  • EVENT_FILTER_TYPE_PID

    • Filtergrößenbeschränkung: MAX_EVENT_FILTER_DATA_SIZE (1024)
    • Anzahl zulässiger 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 relative Paket-App-IDs (PRAIDs) enthalten kann, die durch Semikolons getrennt sind.

  • EVENT_FILTER_TYPE_PAYLOAD

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

  • EVENT_FILTER_TYPE_EVENT_ID

    • Filtergrößenbeschränkung: Nicht definiert
    • Anzahl zulässiger Elemente: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

  • EVENT_FILTER_TYPE_STACKWALK

    • Filtergrößenbeschränkung: Nicht definiert
    • Anzahl zulässiger Elemente: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

Schlüsselwörter definieren Ereigniskategorien. Wenn der Anbieter z. B. InitializationKeyword = 0x1 (Schlüsselwort bit 0), FileOperationKeyword = 0x2 (Schlüsselwort bit 1) und CalculationKeyword = 0x4 (Schlüsselwort bit 2) definiert, können Sie MatchAnyKeyword- auf (InitializationKeyword | CalculationKeyword) = 5 zum Empfangen von Initialisierungs- und Berechnungsereignissen, jedoch nicht für Dateiereignisse.

Bei Verwendung mit modernen (manifestbasierten oder TraceLogging-) -Anbietern wird ein MatchAnyKeyword- Wert von 0 mit einem MatchAnyKeyword- Wert von 0xFFFFFFFFFFFFFFFFbehandelt, d. h. es werden alle Ereignisstichwörter aktiviert. Dieses Verhalten gilt jedoch nicht für Ältere (MOF- oder TMF-basierte WPP-)-Anbieter. Um alle Ereignisstichwörter eines Legacyanbieters zu aktivieren, legen Sie MatchAnyKeyword- auf 0xFFFFFFFFfest. Um alle Ereignisstichwörter sowohl von älteren als auch modernen Anbietern zu aktivieren, legen Sie MatchAnyKeyword- auf 0xFFFFFFFFFFFFFFFFfest.

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

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

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

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

Unter Windows 8.1 können Windows Server 2012 R2 und höher Ereignisnutzlast, Umfang und Stapelexemplarfilter von der EnableTraceEx2--Funktion und der ENABLE_TRACE_PARAMETERS- und EVENT_FILTER_DESCRIPTOR Strukturen verwendet werden, um nach bestimmten Bedingungen in einer Loggersitzung zu filtern. Weitere Informationen zu Ereignisnutzlastfiltern finden Sie im TdhCreatePayloadFilter-und TdhAggregatePayloadFilters Funktionen und der ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTORund PAYLOAD_FILTER_PREDICATE Strukturen.

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

Ab Windows 11 können Ereignisse des Systemablaufverfolgungsanbieters mithilfe von EnableTraceEx2aktiviert werden.

Bis zu acht Ablaufverfolgungssitzungen können Ereignisse vom gleichen modernen (manifestbasierten oder TraceLogging-) -Anbieter aktivieren und empfangen. Allerdings kann nur eine Ablaufverfolgungssitzung einen älteren Anbieter (MOF, TMF-based WPP) aktivieren. Wenn mehrere Sitzungen versuchen, einen Legacyanbieter zu aktivieren, würde die erste Sitzung den Empfang von Ereignissen beenden, wenn die zweite Sitzung denselben Anbieter aktiviert. Wenn beispielsweise "Session A" einen Legacyanbieter aktiviert und dann "Session B" denselben Anbieter aktiviert hat, empfängt nur Session 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, endet, ohne den Anbieter zu deaktivieren, bleibt der Anbieter aktiviert.

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

  • logman query providers provider-name
  • wevtutil gp Anbietername

Bei klassischen Anbietern liegt es an dem Anbieter, zu dokumentieren und potenziellen Controllern die Schweregrade zur Verfügung zu stellen oder flags zu aktivieren, die es unterstützt. 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 (was auch immer sein kann) interpretieren.

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

  • Der parameter Level ist identisch mit dem Festlegen des EnableLevel-Parameters in EnableTrace.
  • Die MatchAnyKeyword- entspricht dem Festlegen des EnableFlag-Parameters in EnableTrace- mit der Ausnahme, dass der Schlüsselwortwert 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 Aktivierungsflagge abzurufen.
  • Der andere Parameter wird nicht verwendet.

Beispiele

Das folgende Beispiel zeigt die Verwendung des EnableTraceEx2- mit Nutzlastfiltern mithilfe der TdhCreatePayloadFilter und TdhAggregatePayloadFilters Funktionen zum Filtern nach bestimmten Bedingungen in einer Loggersitzung.

#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

Anforderung Wert
mindestens unterstützte Client- Windows 7 [Desktop-Apps | UWP-Apps]
mindestens unterstützte Server- Windows Server 2008 R2 [Desktop-Apps | UWP-Apps]
Zielplattform- Fenster
Header- evntrace.h
Library 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

Siehe auch

StartTrace-

ControlTrace-

EnableCallback-

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_DESCRIPTOR