StartKernelTrace

Diese Funktion registriert und startet eine Ablaufverfolgungssitzung für ein Kernelereignis. Sie können das Stackwalking mithilfe dieser Funktion auch für bestimmte Kernelereignisse aktivieren.

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

Parameter

TraceHandle [out]
Speichert ein Handle für eine Ereignisablaufverfolgungssitzung. Dieser Parameter wird auf Null gesetzt, wenn das Handle nicht gültig ist. Dieser Parameter sollte nicht mit INVALID_HANDLE_VALUE verglichen werden. Verwenden Sie dieses Handle nicht, wenn die Funktion fehlschlägt.

Properties [eingehend, ausgehend]
Speichert einen Zeiger auf eine EVENT_TRACE_PROPERTIES-Struktur. EVENT_TRACE_PROPERTIES konfiguriert bestimmte Aspekte des Sitzungsverhaltens.

Das erste Element der EVENT_TRACE_PROPERTIES-Struktur ist eine WNODE_HEADER-Struktur, die hier als Wnode bezeichnet wird.

Die folgenden EVENT_TRACE_PROPERTIES.Wnode-Elemente müssen festgelegt werden, um das Steuerelement für die Kernelablaufverfolgung zu konfigurieren.

BufferSize
Dieses Element enthält die Gesamtgröße des Arbeitsspeichers (in Bytes), der für die Eigenschaften für die Ereignisablaufverfolgung zugewiesen ist. Die Arbeitsspeichergröße muss genügend Speicherplatz zum Speichern der folgenden Daten umfassen:

• EVENT_TRACE_PROPERTIES-Struktur

• Zeichenfolge für den Sitzungsnamen

• Zeichenfolge für den Protokolldateinamen

Guid
Jede Ablaufverfolgungssitzung muss über eine definierte GUID verfügen, um auf die Sitzung zu verweisen.

Für eine NT-Kernelloggersitzung muss dieses Element auf „SystemTraceControlGuid“ festgelegt sein. Weitere Informationen zu Protokollierungsmoduskonstanten finden Sie unter NT-Kernelloggerkonstanten.

ClientContext
Dieses Element legt die Zeitauflösung fest, die verwendet wird, wenn der Protokollierungszeitstempel für jedes Ereignis berechnet wird. Der Standardwert für dieses Element ist ein Abfrageleistungszähler.

Sie können einen der folgenden Werte angeben:

• 1: Abfrageleistungszähler (Query performance counter, QPC): Der QPC stellt einen Zeitstempel mit hoher Auflösung (Hundertstel Nanosekunde) bereit, der Abruf ist jedoch vergleichsweise teurer. Verwenden Sie diese Auflösung, wenn Sie über hohe Ereignisraten verfügen oder der Consumer Ereignisse aus verschiedenen Puffern zusammenführt. Auf älteren Computern ist der Zeitstempel möglicherweise nicht genau, da der Zähler aufgrund von Hardwarefehlern manchmal Elemente überspringt.

• 2: Systemzeit: Die Systemzeit bietet einen Zeitstempel mit niedriger Auflösung (Zehntel Millisekunde), der Abruf ist jedoch vergleichsweise günstiger. Wenn das Ereignisvolumen hoch ist, ist die Auflösung für die Systemzeit möglicherweise nicht gut genug, um die Sequenz von Ereignissen zu ermitteln. In diesem Fall hat eine Reihe von Ereignissen den gleichen Zeitstempel, aber die Reihenfolge, in der die ETW die Ereignisse bereitstellt, ist möglicherweise nicht richtig.

• 3: CPU-Zykluszähler: Der CPU-Zähler stellt den Zeitstempel mit der höchsten Auflösung bereit, und der Abruf ist am günstigsten. Der CPU-Zähler ist jedoch unzuverlässig und sollte nicht in der Produktion verwendet werden. Bei einigen Computern ändert sich beispielsweise die Timerfrequenz aufgrund von Wärme- und Leistungsänderungen (zusätzlich zum Beenden in einigen Zuständen). Wenn Ihre Hardware diesen Uhrtyp nicht unterstützt, verwendet die ETW die Systemzeit. Unter Windows Server 2003, Windows XP mit SP1 und Windows XP wird dieser Wert nicht unterstützt. Er wurde unter Windows Server 2003 mit SP1 und Windows XP mit SP2 eingeführt.

Flags
Dieses Element muss WNODE_FLAG_TRACED_GUID enthalten, um anzugeben, dass die Struktur Ereignisablaufverfolgungsinformationen enthält und die Informationen an einen Logger gesendet werden. WNODE_FLAG_TRACED_GUID ist in „Evntrace.h“ definiert.

Die folgenden EVENT_TRACE_PROPERTIES-Elemente müssen ebenfalls festgelegt sein:

LogFileMode
Gibt an, welche Protokollierungsmodi in der Sitzung für die Kernelereignisablaufverfolgung verwendet werden sollen. Sie können dieses Element verwenden, um anzugeben, dass Ereignisse in eine Protokolldatei, einen Echtzeitconsumer oder beides geschrieben werden sollen.

Dieses Element kann auch verwendet werden, um anzugeben, dass die Sitzung eine private Loggersitzung ist. Es können mehrere Modi angegeben werden. Eine Liste der verfügbaren Modi finden Sie unter Protokollierungsmoduskonstanten.

Hinweis: Geben Sie keine Echtzeitprotokollierung an, es sei denn, es gibt Echtzeitconsumer, die bereit sind, die Ereignisse zu verarbeiten. Wenn keine Echtzeitconsumer vorhanden sind, werden die Ereignisse in eine Wiedergabedatei geschrieben. Die Größe der Wiedergabedatei ist begrenzt. Wenn der Grenzwert erreicht wird, werden keine neuen Ereignisse in der Protokolldatei oder der Wiedergabedatei protokolliert. Wenn Sie STATUS_LOG_FILE_FULL verwenden, tritt bei den Protokollierungsfunktionen ein Fehler auf.

EnableFlags
Dieses Element wird nur für NT-Kernelloggersitzungen verwendet. Es identifiziert für den Kernellogger, welche Ereignisse nachverfolgt werden sollen. Durch Die Verwendung logischer OR-Elemente kann dieses Element mindestens einen Wert enthalten. Zusätzlich zu den angegebenen Ereignissen protokolliert der Kernellogger auch Hardwarekonfigurationsereignisse.

Die folgenden Flags für die Ablaufverfolgungssteuerung sind zusätzlich zu den von EVENT_TRACE_PROPERTIES bereitgestellten Flags verfügbar:

• EVENT_TRACE_FLAG_DISPATCHER

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC

LogFileNameOffset
Diese Zahl stellt den Offset vom Anfang des Speichers, der der Struktur zugewiesen ist, zur Struktur des Starts der NULL-terminierten Zeichenfolge dar, die den Protokolldateinamen enthält.

Es gelten die folgenden Bedingungen:

• Die Dateinamenerweiterung sollte „.etl“ sein.

• Alle Ordner im Pfad müssen vorhanden sein.

• Der Pfad kann relativ, absolut, lokal oder remote sein.

• Der Pfad darf keine Umgebungsvariablen enthalten, da diese Variablen nicht erweitert werden.

• Die Benutzer*innen, die die Ablaufverfolgung initiieren, müssen über Schreibberechtigungen im Ordner verfügen.

• Der Protokolldateiname ist auf 1024 Zeichen beschränkt.

• Wenn Sie LogFileMode auf EVENT_TRACE_PRIVATE_LOGGER_MODE oder EVENT_TRACE_FILE_MODE_NEWFILE festlegen, müssen Sie genügend Arbeitsspeicher zuweisen, um den Prozessbezeichner, der an den Dateinamen für private Loggersitzungen angefügt wird, und die sequenzielle Nummer einzuschließen, die zu Protokolldateien hinzugefügt wird, die mithilfe des neuen Dateiprotokollmodus erstellt wurden.

• Wenn Sie Protokollereignisse nicht in einer Protokolldatei protokollieren möchten (z. B. nur Angabe von EVENT_TRACE_REAL_TIME_MODE), legen Sie LogFileNameOffset auf null (0) fest. Wenn Sie nur die Echtzeitprotokollierung angeben und auch einen Offset mit einem gültigen Protokolldateinamen bereitstellen, wird der Protokolldateiname verwendet, um eine sequenzielle Protokolldatei und Protokollereignisse in der Protokolldatei zu erstellen. Die sequenzielle Protokolldatei wird auch erstellt, wenn LogFileMode null (0) ist und Sie einen Offset mit einem gültigen Protokolldateinamen bereitstellen.

• Wenn Sie Ereignisse in einer Protokolldatei protokollieren möchten, müssen Sie genügend Arbeitsspeicher für diese Struktur zuweisen, um den Protokolldateinamen und den Sitzungsnamen nach der Struktur einzuschließen. Der Protokolldateiname muss dem Sitzungsnamen im Arbeitsspeicher folgen.

• Ablaufverfolgungsdateien werden mithilfe des Standardsicherheitsdeskriptors erstellt, d. h. die Protokolldatei verfügt über dieselbe ACL wie das übergeordnete Verzeichnis. Wenn Sie den Zugriff auf die Dateien einschränken möchten, erstellen Sie ein übergeordnetes Verzeichnis mit den entsprechenden ACLs.

LoggerNameOffset
Dieses Element stellt den Offset vom Anfang des Speichers, der der Struktur zugewiesen ist, zur Struktur des Starts der NULL-terminierten Zeichenfolge dar, die den Sitzungsnamen enthält.

Es gelten die folgenden Bedingungen:

• Der Sitzungsname ist auf 1024 Zeichen begrenzt.

• Beim Sitzungsnamen wird die Groß- und Kleinschreibung nicht beachtet, und er muss eindeutig sein.

• Wenn Speicher für diese Struktur zugewiesen wird, muss genügend Speicher reserviert werden, um den Sitzungsnamen und den Protokolldateinamen nach der Struktur einzuschließen.

• Der Sitzungsname muss vor dem Protokolldateinamen im Arbeitsspeicher kommen. Der Protokolldateiname muss in den Offsetbereich kopiert werden. Diese Funktion schreibt den von KERNEL_LOGGER_NAME definierten Sitzungsnamen.

Gemäß dem ausgewählten Protokolldateityp kann es erforderlich sein, das MaximumFileSize-Element festzulegen.

Hinweis: Es ist nicht erforderlich, den Loggernamen im LoggerNameOffset festzulegen, da diese Funktion immer den KERNEL_LOGGER_NAME-Wert zum Aufrufen von „StartKernelTrace“ verwendet. Diese Funktion überprüft, ob Wnode.GuidSystemTraceControlGuid entspricht. Falls dies nicht der Fall ist, wird ERROR_INVALID_PARAMETER zurückgegeben. Wenn Wnode.GuidKernelRundownGuid entspricht, sollte der Loggername angegeben werden. KernelRundownGuid ist die Steuerelement-GUID, die verwendet wird, um Ereignisse wie vorhandene Prozessinformationen, Threadinformationen und pro Vorgang geladene Bilder sowie die Hardwarekonfiguration wie CPU, Videos, Datenträger, Netzwerkkarten, Dienste, Leistungsversorgung, Plug & Play und Datenträger-IDE-Kanäle zu protokollieren.

Rückgabewert

ERROR_SUCCESS zeigt Erfolg an.

Mögliche Fehlerwerte sind in der folgenden Tabelle beschrieben.

Fehlerwert	Beschreibung
ERROR_ALREADY_EXISTS	Auf dem System läuft nur eine einzige Instanz des Kernel-Loggers. Wenn diese Funktion zu starten versucht, nachdem eine andere Komponente die Kernel-Protokollierung gestartet hat, wird möglicherweise dieser Fehler zurückgegeben.
ERROR_INVALID_FLAGS	Zeigt möglicherweise an, dass ungültige Ablaufverfolgungsflags in Properties.EnableFlags vorhanden sind.
ERROR_OUT_OF_MEMORY	Zeigt möglicherweise einen Fehler beim Zuweisen von Speicher für EVENT_TRACE_PROPERTIES an.

Wenn die Funktion aus einem anderen als den aufgeführten Gründen fehlschlägt, wird ein Systemfehlercode zurückgegeben.

Bemerkungen

Wenn StackTracingEventIds Ereignisse enthalten, die im Feld EVENT_TRACE_PROPERTIES.EnableFlags nicht aktiviert sind oder von der Kernelablaufverfolgungssteuerung nicht entschlüsselt werden konnten, werden diese Flags ignoriert, und es wird kein Fehlercode zurückgegeben.

Anforderungen:

Versionen: Verfügbar ab Windows Vista. Diese Struktur wird über Windows Performance Analyzer bereitgestellt.

Header: In „KernelTraceControl.h“ deklariert. „KernelTraceControl.h“ einschließen.

Bibliothek: In „KernelTraceControl.dll“ enthalten.

Zugehörige Themen

Funktionen

Benutzerdefinierte Injektion von Systeminformationen