Freigeben über

ControlTraceA-Funktion (evntrace.h)

  • Artikel

Die ControlTrace-Funktion leert, fragt, aktualisiert oder beendet die angegebene Ereignisablaufverfolgungssitzung.

Syntax

ULONG WMIAPI ControlTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  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 den Wert 0 hat.

Um die NT Kernel Logger-Sitzung 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 die maximale Länge des Sitzungsnamens (1024 Zeichen) und die maximale Länge des Protokolldateinamens (1024 Zeichen) verwenden, um die Puffergröße und die Offsets zu berechnen, wenn sie nicht bekannt sind.

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 Properties die Eigenschaften und Statistiken für die Ereignisablaufverfolgungssitzung. Sie können die folgenden Eigenschaften aktualisieren.

  • EnableFlags: Legen Sie dieses Element 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 Systemprotokollierer ungleich 0 sein.

  • FlushTimer: Legen Sie diesen Member fest, wenn Sie die Zeit ändern möchten, um vor dem Leeren von Puffern zu warten. 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 null 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. Um echtzeitaufwendig zu deaktivieren, legen Sie dieses Element auf 0 fest. Legen Sie dieses Element auf EVENT_TRACE_REAL_TIME_MODE fest, und es wird mit den aktuellen Modi als OR'd verwendet, um echtzeitaufwendig zu sein (erstellen, um eine Sitzung zu erstellen, die auf dem 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.

Für private 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 sowie die Werte fest, die Sie aktualisieren möchten.

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 Protokolldateinamen, und legen Sie EVENT_TRACE_PROPERTIES fest. Wnode.Flags für 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 Protokollierungssitzung .

[in] ControlCode

Angeforderte Steuerungsfunktion. 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 automatisch einen Puffer leert, wenn er voll ist (d. h. wenn er keinen Platz für das nächste Ereignis hat), wenn 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 über verfügt, aktualisiert die EVENT_TRACE_FILE_MODE_NEWFILESitzung, um sofort zur nächsten Datei zu wechseln, anstatt darauf zu warten, dass die vorherige Datei ausgefüllt wird. Unterstützt ab Windows 10 Oktober 2018 Update.

  • 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). Unterstützt ab Windows 10 Update vom Oktober 2020.

Hinweis

Es ist nicht sicher, Puffer zu leeren oder eine Ablaufverfolgungssitzung aus 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 finden Sie einige häufige Fehler und deren Ursachen.

  • ERROR_BAD_LENGTH

    Es trifft eine der folgenden Bedingungen zu:

    • Der Wnode.BufferSize-Member 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) zu speichern.

  • ERROR_INVALID_PARAMETER

    Es trifft eine der folgenden Bedingungen zu:

    • Eigenschaften sind NULL.
    • InstanceName und TraceHandle sind beide 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 Properties gibt eine Kombination von Flags an, die ungültig ist.
    • 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-Element 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 wird.

  • ERROR_ACCESS_DENIED

    Nur Benutzer, die mit erhöhten Administratorrechten ausgeführt werden, Benutzer in der Gruppe Leistungsprotokollbenutzer und Dienste, die als LocalSystem, LocalService, 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.

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 Code, der nicht Codierungsneutral ist, 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

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace