ControlTraceW-Funktion (evntrace.h)
Die ControlTrace-Funktion löscht, fragt, aktualisiert oder beendet die angegebene Ereignisablaufverfolgungssitzung.
Syntax
ULONG WMIAPI ControlTraceW(
CONTROLTRACE_ID TraceId,
[in] LPCWSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Parameter
TraceId
[in] InstanceName
Name einer Ereignisablaufverfolgungssitzung oder NULL. Sie müssen InstanceName angeben, wenn TraceHandle 0 ist.
Um die NT-Kernelprotokollierungssitzung anzugeben, legen Sie InstanceName auf KERNEL_LOGGER_NAME fest.
[in, out] Properties
Zeiger auf eine initialisierte EVENT_TRACE_PROPERTIES-Struktur . Diese Struktur sollte auf null gesetzt werden, bevor Felder festgelegt werden.
Wenn ControlCodeEVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY oder EVENT_TRACE_CONTROL_FLUSH angibt, müssen Sie nur die Elemente Wnode.BufferSize, Wnode.Guid, LoggerNameOffset und LogFileNameOffset der EVENT_TRACE_PROPERTIES-Struktur festlegen. Wenn es sich bei der Sitzung um eine private Sitzung handelt, müssen Sie auch LogFileMode festlegen. Sie können den maximalen Sitzungsnamen (1024 Zeichen) und die maximale Protokolldateinamelänge (1024 Zeichen) verwenden, um die Puffergröße und die Offsets zu berechnen, falls nicht bekannt.
Wenn ControlCodeEVENT_TRACE_CONTROL_UPDATE angibt, müssen die Member bei der Eingabe die neuen Werte für die zu aktualisierenden Eigenschaften angeben. In der Ausgabe enthält Eigenschaften die Eigenschaften und Statistiken für die Ereignisablaufverfolgungssitzung. Sie können die folgenden Eigenschaften aktualisieren.
EnableFlags: Legen Sie diesen Member auf 0 fest, um alle Systemanbieter zu deaktivieren. Legen Sie diesen Wert auf einen Wert ungleich 0 fest, um die Systemanbieter anzugeben, die Sie aktivieren oder aktivieren möchten. Dies kann nur für Systemprotokollierungsvorgänge ungleich Null sein.
FlushTimer: Legen Sie diesen Member fest, wenn Sie die Wartezeit vor dem Leeren von Puffern ändern möchten. Wenn dieser Member 0 ist, wird das Element nicht aktualisiert.
LogFileNameOffset: Legen Sie dieses Element fest, wenn Sie zu einer anderen Protokolldatei wechseln oder eine Ablaufverfolgung im Puffermodus in eine neue Protokolldatei leeren möchten. Wenn dieser Member 0 ist, wird der Dateiname nicht aktualisiert. Wenn der Offset nicht 0 ist und Sie den Namen der Protokolldatei nicht ändern, gibt die Funktion einen Fehler zurück.
LogFileMode: Legen Sie dieses Element fest, wenn Sie EVENT_TRACE_REAL_TIME_MODE aktivieren und deaktivieren möchten. Legen Sie dieses Element auf 0 fest, um den Echtzeitaufwand zu deaktivieren. Legen Sie dieses Element auf EVENT_TRACE_REAL_TIME_MODE fest, und es wird OR mit den aktuellen Modi sein, um echtzeitaufwendig zu sein (Erstellen einer Sitzung, die auf den Datenträger aufzeichnet und Ereignisse in Echtzeit liefert).
MaximumBuffers: Legen Sie diesen Member fest, wenn Sie die maximale Anzahl von Puffern ändern möchten, die ETW verwendet. Wenn dieser Member 0 ist, wird das Element nicht aktualisiert.
Bei privaten Protokollierungssitzungen können Sie nur die Member LogFileNameOffset und FlushTimer aktualisieren.
Wenn Sie eine neu initialisierte EVENT_TRACE_PROPERTIES-Struktur verwenden, stellen Sie die Struktur auf null, und legen Sie Wnode.BufferSize, Wnode.Guid und Wnode.Flags und die zu aktualisierenden Werte fest.
Wenn Sie eine EVENT_TRACE_PROPERTIES-Struktur wiederverwenden (d. h. eine Struktur verwenden, die Sie zuvor an StartTrace oder ControlTrace übergeben haben), legen Sie das LogFileNameOffset-Element auf 0 fest, es sei denn, Sie ändern den Namen der Protokolldatei, und achten Sie darauf, EVENT_TRACE_PROPERTIES festzulegen. Wnode.Flags to WNODE_FLAG_TRACED_GUID.
Ab Windows 10, Version 1703: Für eine bessere Leistung in prozessübergreifenden Szenarien können Sie jetzt Filterinformationen für systemweite private Protokollierungen an ControlTrace übergeben. Sie müssen die EVENT_TRACE_PROPERTIES_V2-Struktur verwenden, um Filterinformationen einzuschließen. Weitere Informationen finden Sie unter Konfigurieren und Starten einer privaten Protokolliersitzung .
[in] ControlCode
Die Steuerungsfunktion wurde angefordert. Sie können einen der folgenden Werte angeben:
EVENT_TRACE_CONTROL_FLUSH: Leert die aktiven Puffer der Sitzung.
Dies kann mit einer In-Memory-Sitzung (einer Sitzung, die mit dem flag EVENT_TRACE_BUFFERING_MODE gestartet wurde) verwendet werden, um die Daten aus der Ablaufverfolgung in eine Datei zu schreiben.
Sie müssen normalerweise keine dateibasierten Sitzungen oder Echtzeitsitzungen leeren, da ETW einen Puffer automatisch leert, wenn er voll ist (d. h. wenn er keinen Platz für das nächste Ereignis hat), wenn der FlushTimer der Ablaufverfolgungssitzung abläuft oder wenn die Ablaufverfolgungssitzung geschlossen wird.
Windows 2000: Dieser Wert wird nicht unterstützt.
EVENT_TRACE_CONTROL_QUERY: Ruft Sitzungseigenschaften und Statistiken ab.
EVENT_TRACE_CONTROL_STOP: Beendet die Sitzung. Das Sitzungshandle ist nicht mehr gültig.
EVENT_TRACE_CONTROL_UPDATE: Aktualisiert die Sitzungseigenschaften.
EVENT_TRACE_CONTROL_INCREMENT_FILE: Wenn die Sitzung den hat, aktualisiert die
EVENT_TRACE_FILE_MODE_NEWFILESitzung, um sofort zur nächsten Datei zu wechseln, anstatt darauf zu warten, dass die vorherige Datei gefüllt wird. Wird ab Windows 10 Update vom Oktober 2018 unterstützt.EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: Ändert eine Dateimodussitzung in eine Echtzeitsitzung (ermöglicht die Echtzeitübermittlung und deaktiviert das Schreiben von Ereignissen in die ETL-Datei). Wird ab Windows 10 Update vom Oktober 2020 unterstützt.
Hinweis
Es ist nicht sicher, Puffer zu leeren oder eine Ablaufverfolgungssitzung von DllMain zu beenden (kann zu einem Deadlock führen).
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_BAD_LENGTH
Es trifft eine der folgenden Bedingungen zu:
- Das Wnode.BufferSize-Element von Properties gibt eine falsche Größe an.
- Eigenschaften verfügen nicht über genügend Speicherplatz, um eine Kopie des Sitzungsnamens und des Protokolldateinamens (falls verwendet) aufzunehmen.
ERROR_INVALID_PARAMETER
Es trifft eine der folgenden Bedingungen zu:
- Eigenschaften sind NULL.
- InstanceName und TraceHandlesind null.
- InstanceName ist NULL und TraceHandle ist kein gültiges Handle.
- Das LogFileNameOffset-Element von Properties ist ungültig.
- Das LoggerNameOffset-Element von Properties ist ungültig.
- Das LogFileMode-Element von Eigenschaften gibt eine Kombination von nicht gültigen Flags an.
- Das Wnode.Guid-Element von Properties ist SystemTraceControlGuid, aber der InstanceName-Parameter ist nicht
KERNEL_LOGGER_NAME.
ERROR_BAD_PATHNAME
Eine andere Sitzung verwendet bereits den Dateinamen, der vom LogFileNameOffset-Member der Properties-Struktur angegeben wird.
ERROR_MORE_DATA
Der Puffer für EVENT_TRACE_PROPERTIES ist zu klein, um alle Informationen für die Sitzung zu speichern. Wenn Sie die Eigenschafteninformationen der Sitzung nicht benötigen, können Sie diesen Fehler ignorieren. Wenn sie beim Beenden der Sitzung diesen Fehler erhalten, hat ETW die Sitzung bereits beendet, bevor dieser Fehler generiert wurde.
ERROR_ACCESS_DENIED
Nur Benutzer, die mit erhöhten Administratorrechten ausgeführt werden, Benutzer in der Gruppe Leistungsprotokollbenutzer und Dienste, die als LocalSystem, LocalService und NetworkService ausgeführt werden, können Ereignisablaufverfolgungssitzungen steuern. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, Ablaufverfolgungssitzungen zu steuern, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu. Nur Benutzer mit Administratorrechten und Diensten, die als LocalSystem ausgeführt werden, können eine NT-Kernelprotokollierungssitzung steuern.
Windows XP und Windows 2000: Jeder kann eine Ablaufverfolgungssitzung steuern.
ERROR_WMI_INSTANCE_NOT_FOUND
Die angegebene Sitzung wird nicht ausgeführt.
ERROR_ACTIVE_CONNECTIONS
Wenn von einem EVENT_TRACE_CONTROL_STOP-Aufruf zurückgegeben wird, bedeutet dies, dass die Sitzung bereits beendet wird.
Hinweise
Ereignisablaufverfolgungscontroller rufen diese Funktion auf.
Diese Funktion ersetzt die Funktionen FlushTrace, QueryTrace, StopTrace und UpdateTrace .
Hinweis
Der evntrace.h-Header definiert ControlTrace als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [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, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP |
| DLL | Sechost.dll unter Windows 8.1 und Windows Server 2012; Advapi32.dll unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für