Konfigurieren und Starten einer Event-Tracing-Sitzung
Um eine Event-Tracing-Sitzung zu konfigurieren, verwenden Sie die Struktur EVENT_TRACE_PROPERTIES, um die Eigenschaften der Sitzung festzulegen. Der Speicher, den Sie für die Struktur EVENT_TRACE_PROPERTIES zuweisen, muss groß genug sein, um auch die Namen der Sitzung und der Log-Dateien aufzunehmen, die der Struktur im Speicher folgen.
Nachdem Sie die Eigenschaften der Sitzung festgelegt haben, rufen Sie die Funktion StartTrace auf, um die Sitzung zu starten. Wenn die Funktion erfolgreich ist, enthält der Parameter SessionHandle das Sitzungshandle und die Eigenschaft LoggerNameOffset enthält den Offset zum Sitzungsnamen.
Um die Anbieter zu aktivieren, die Ereignisse in Ihrer Sitzung protokollieren sollen, rufen Sie die Funktion EnableTrace auf, um klassische Anbieter zu aktivieren, und die Funktion EnableTraceEx, um manifestbasierte Anbieter zu aktivieren. Um die Anbieter zu aktivieren, von denen Sie möchten, dass die Ereignisse in Ihrer Sitzung nach bestimmten Bedingungen gefiltert werden, rufen Sie unter Windows 8.1, Windows Server 2012 R2 und höher die Funktion EnableTraceEx2 auf.
Darüber hinaus können Sie mit einem Aufruf der Funktion TraceSetInformation zusätzliche Informationen zu einem Ereignis verfolgen. TraceSetInformation fügt zusätzliche Trace-Informationen in den erweiterten Datenbereich eines Ereignisses ein und kann Informationen wie die Trace-Versionsinfo oder die derzeit auf dem System registrierten Anbieter enthalten. Weitere Informationen finden Sie unter Abrufen zusätzlicher Daten für das Event-Tracing.
Bis zu acht Trace-Sitzungen können Ereignisse von demselben manifestbasierten Anbieter aktivieren und empfangen. Allerdings kann nur eine Trace-Sitzung einen klassischen Anbieter aktivieren. Wenn mehr als eine Trace-Sitzung versucht, einen klassischen Anbieter zu aktivieren, würde die erste Sitzung keine Ereignisse mehr empfangen, wenn die zweite Sitzung den Anbieter aktiviert. Wenn beispielsweise Sitzung A den Anbieter 1 aktiviert und anschließend Sitzung B den Anbieter 1 aktiviert, würde nur Sitzung B Ereignisse von Anbieter 1 empfangen.
Sie können jede der drei Funktionen verwenden, um einen Anbieter zu aktivieren, aber es kann zu Funktionseinbußen kommen, wenn Sie EnableTrace verwenden, um einen manifestbasierenden Anbieter zu aktivieren, weil Sie dann keinen MatchAllKeyword-Wert bereitstellen, keine erweiterten Datenelemente angeben können, die in das Ereignis aufgenommen werden sollen, und keine vom Anbieter definierten Filterdaten bereitstellen können. Weitere Informationen finden Sie im Abschnitt „Anmerkungen“ der jeweiligen Funktion.
Unter Windows 8.1, Windows Server 2012 R2 und höher können Ereignis-Payload-, Bereich- und Stack-Walk-Filter von der Funktion EnableTraceEx2 und den Strukturen ENABLE_TRACE_PARAMETERS und EVENT_FILTER_DESCRIPTOR verwendet werden, um nach bestimmten Bedingungen in einer Logger-Sitzung zu filtern. Weitere Informationen über Ereignis-Payload-Filter finden Sie in den Funktionen TdhCreatePayloadFilter und TdhAggregatePayloadFilters sowie in den Strukturen ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR und PAYLOAD_FILTER_PREDICATE.
Um die Stufe und die Schlüsselwörter für die Aktivierung eines manifestbasierten Anbieters zu bestimmen, verwenden Sie einen der folgenden Befehle:
- Logman query Anbieter-Name
- Wevtutil gp provider-name
Die Befehle listen nur die Stufe und die Schlüsselwörter auf. Der Anbieter muss alle Anforderungen an die Filterdaten für potenzielle Controller dokumentieren.
Um die manifestbasierten Anbieter aufzulisten, verwenden Sie Wevtutil ep.
Bei klassischen Anbietern ist es Sache des Anbieters, die von ihm unterstützten Schweregrade oder Aktivierungs-Flags zu dokumentieren und potenziellen Controllern zur Verfügung zu stellen. Wenn der Anbieter von einem Controller aktiviert werden möchte, sollte er 0 für den Schweregrad und die Aktivierungsflags akzeptieren und 0 als Anfrage zur Durchführung der Standardprotokollierung (was auch immer das sein mag) interpretieren.
Sie können den Anbieter aktivieren, bevor oder nachdem sich der Anbieter selbst registriert hat. Nachdem Sie den Anbieter aktiviert haben, ruft ETW die Callback-Funktion des Anbieters auf. Wenn der Anbieter nicht registriert ist, ruft ETW die Callback-Funktion des Anbieters auf, nachdem er sich selbst registriert hat.
Sie können auch die Funktion EnableTrace verwenden, um den Anbieter zu deaktivieren (d. h. um zu verhindern, dass er Ereignisse in Ihrer Sitzung protokolliert) oder um die Protokollierungsebene oder die Aktivierungsflags des Anbieters zu aktualisieren. Mit der Funktion EnableTraceEx können Sie den Anbieter deaktivieren oder die Stufe, Schlüsselwörter, erweiterten Daten und Filterdaten aktualisieren. Jedes Mal, wenn Sie die Funktion EnableTrace oder EnableTraceEx aufrufen, ruft ETW die Callback-Funktion des Anbieters auf. Der Anbieter bleibt für die Sitzung aktiviert, bis die Sitzung den Anbieter deaktiviert.
Um die Trace-Sitzung nach dem Sammeln von Ereignissen zu beenden, rufen Sie die Funktion ControlTrace auf und übergeben EVENT_TRACE_CONTROL_STOP als Steuercode. Um die zu stoppende Sitzung anzugeben, können Sie das Handle der Event-Tracing-Sitzung übergeben, das Sie bei einem früheren Aufruf der Funktion StartTrace abgerufen haben, oder den Namen einer zuvor gestarteten Sitzung. Achten Sie darauf, dass Sie alle Anbieter deaktivieren, bevor Sie die Sitzung beenden. Wenn Sie die Sitzung beenden, bevor Sie den Anbieter deaktiviert haben, wird ETW den Anbieter deaktivieren und versuchen, die Steuer-Callback-Funktion des Anbieters aufzurufen. Wenn die Anwendung, die die Sitzung gestartet hat, endet, ohne den Anbieter zu deaktivieren oder die Funktion ControlTrace aufzurufen, bleibt der Anbieter aktiviert.
Wenn ControlTrace erfolgreich ist, werden die Sitzungseigenschaften aktualisiert, um die endgültigen Eigenschaftswerte und die ausgeführten Statistiken für die Event-Tracing-Sitzung wiederzugeben.
Ein Beispiel, das eine Event-Tracing-Sitzung startet, finden Sie im Folgenden:
- Beispiel, das eine Sitzung erstellt und einen manifestbasierten Anbieter aktiviert – erstellt eine Trace-Sitzung, aktiviert einen manifestbasierten Anbieter, deaktiviert den Anbieter und beendet dann die Sitzung.
Einzelheiten zum Starten einer Trace-Sitzung finden Sie in einem der folgenden Abschnitte:
- Konfigurieren und Starten einer SystemTraceProvider-Sitzung
- Konfigurieren und Starten der NT-Kernel-Logger-Sitzung
- Konfigurieren und Starten einer AutoLogger-Sitzung
- Konfigurieren und Starten der globalen Logger-Sitzung
- Konfigurieren und Starten einer privaten Logger-Sitzung
Zugehörige Themen