StartHeapTrace

  • Artikel

Diese Funktion registriert und startet eine Heap-Tracing-Sitzung für einen Satz von angegebenen PIDs. Sie können mit dieser Funktion auch Stack Walking für bestimmte Heap-Ereignisse wie Zuweisung oder Löschung aktivieren.

Der Prozess, für den die Heap-Ablaufverfolgung aktiviert werden soll, muss vor dem Aufruf dieser Funktion erstellt werden. Um Heap-Ereignisse vom Anfang des Programms an zu erfassen, ist es ratsam, den Prozess mit dem CREATE_SUSPENDED-Flag zu starten, dann die Heap-Ablaufverfolgung für seine PID zu aktivieren und dann den Prozess fortzusetzen.

Die Heap-Ablaufverfolgung ist sehr ausführlich und kann schnell eine sehr große Ablaufverfolgungsdatei generieren. Ereignisse können leicht verloren gehen, wenn die Puffer der Sitzung zu klein oder zu gering sind. Es wird empfohlen, die Anzahl der Prozesse, für die die Heap-Ablaufverfolgung aktiviert ist, zu begrenzen, um keine Ereignisse zu verlieren. Die Aktivierung der Heap-Ablaufverfolgung kann sich auf die Leistung des Ablaufverfolgungsprozesses auswirken.

ULONG
WINAPI
StartHeapTrace(
    _Out_ PTRACEHANDLE TraceHandle,
    _Inout_ PEVENT_TRACE_PROPERTIES Properties,
    _In_z_ LPCWSTR wszSessionName,
    _In_reads_opt_(cPids) const ULONG Pids[],
    _In_  ULONG cPids,
    _In_reads_opt_(cStackTracingEventIds) const STACK_TRACING_EVENT_ID StackTracingEventIds[],
    _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 [in, out]
Speichert einen Zeiger auf eine EVENT_TRACE_PROPERTIES-Struktur. EVENT_TRACE_PROPERTIES konfiguriert bestimmte Aspekte des Sitzungsverhaltens.

Es ist nicht erforderlich, das Guid-Member festzulegen, da diese Funktion immer ihren eigenen Wert verwendet. Wenn Sie eine GUID angeben, wird diese nicht verwendet.

wszSessionName [in]
Der Sitzungsname, der an StartTrace übergeben werden soll.

Pids [in]
Ein Array von Prozess-IDs zum Aktivieren der Heap-Ablaufverfolgung.

cPids [in]
Die Größe des Pids-Arrays.

cStackTracingEventIds [in]
Die Größe des StackTracingEventIds-Arrays.

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

Keine

Funktionen

UpdateHeapTrace