TraceEvent-Funktion (evntrace.h)

Artikel
08/23/2023

Ein RegisterTraceGuids-basierter ("Classic")-Ereignisanbieter verwendet die TraceEvent-Funktion , um ein strukturiertes Ereignis an eine Ereignisablaufverfolgungssitzung zu senden.

Syntax

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Parameter

[in] TraceHandle

Behandeln Sie die Ereignisablaufverfolgungssitzung, die das Ereignis aufzeichnet. Der Anbieter ruft das Handle ab, wenn er die GetTraceLoggerHandle-Funktion in seiner ControlCallback-Implementierung aufruft.

[in] EventTrace

Zeiger auf eine EVENT_TRACE_HEADER-Struktur . Ereignisspezifische Daten werden optional an die -Struktur angefügt. Das größte Ereignis, das Sie protokollieren können, ist etwas kleiner als 64.000. Sie müssen Werte für die folgenden Member der EVENT_TRACE_HEADER-Struktur angeben.

Größe
Guid oder GuidPtr
Flags

Abhängig von der Komplexität der Informationen, die Ihr Anbieter bereitstellt, sollten Sie auch die Angabe von Werten für die folgenden Member in Betracht ziehen.

Class.Type
Class.Level

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_INVALID_FLAG_NUMBER

Der Flags-Member der EVENT_TRACE_HEADER-Struktur ist falsch.
ERROR_INVALID_HANDLE

TraceHandle ist ungültig oder gibt das Nt Kernel Logger-Sitzungshandle an.
ERROR_NOT_ENOUGH_MEMORY

Es sind nicht genügend freie Puffer zum Schreiben der Sitzung vorhanden. Dieser Fall kann während hoher Ereignisraten auftreten, weil das Datenträgersubsystem überlastet ist oder nicht genügend Puffer vorhanden sind. Anstatt zu blockieren, bis mehr Puffer verfügbar sind, verwirft TraceEvent das Ereignis.

Sie sollten die Anzahl und Größe der Puffer für die Sitzung erhöhen oder die Anzahl oder Größe der zu schreibenden Ereignisse verringern.

Windows 2000: Nicht unterstützt.
ERROR_OUTOFMEMORY

Das Ereignis wird verworfen, da, obwohl der Pufferpool seine maximale Größe nicht erreicht hat, nicht genügend Arbeitsspeicher verfügbar ist, um einen zusätzlichen Puffer zuzuweisen, und es ist kein Puffer für den Empfang des Ereignisses verfügbar.
ERROR_INVALID_PARAMETER

Es trifft eine der folgenden Bedingungen zu:
- TraceHandle ist NULL.
- EventTrace ist NULL.
- Der Size-Member der EVENT_TRACE_HEADER-Struktur ist falsch.
ERROR_MORE_DATA

Daten aus einem einzelnen Ereignis können sich nicht über mehrere Puffer erstrecken. Ein Ablaufverfolgungsereignis ist auf die Größe des Puffers der Ereignisablaufverfolgungssitzung abzüglich der Größe der EVENT_TRACE_HEADER-Struktur beschränkt.

Hinweise

MOF-basierte ETW-Anbieter rufen diese Funktion auf.

Hinweis

Die meisten Entwickler rufen diese Funktion nicht auf. Diese API unterstützt MOF-basierte ETW, aber MOF-basierte ETW ist zugunsten von manifestbasiertem ETW veraltet. Darüber hinaus verwenden die meisten MOF-basierten Anbieter Wrapperfunktionen, die von MC.exe generiert werden, anstatt etw-APIs direkt aufzurufen.

Bevor der Anbieter diese Funktion aufrufen kann, muss der Anbieter

Muss die RegisterTraceGuids-Funktion aufrufen, um sich selbst und die Ereignisablaufverfolgungsklasse zu registrieren.
Muss aktiviert sein. Ein Controller ruft die EnableTrace-Funktion auf, um einen Anbieter zu aktivieren.

Das Ereignis wird entweder in eine Protokolldatei geschrieben, in Echtzeit an Consumer der Ereignisablaufverfolgung gesendet oder beides. Das LogFileMode-Element der EVENT_TRACE_PROPERTIES-Struktur , die an startTrace übergeben wird, definiert, wohin das Ereignis gesendet wird.

Die Ablaufverfolgungsereignisse werden in der Reihenfolge geschrieben, in der sie auftreten.

Verwenden Sie die Funktion TraceEventInstance , um eine Reihe verwandter Ereignisse nachzuverfolgen.

Unter Windows Vista sollten Sie die EventWrite-Funktion verwenden, um Ereignisse zu protokollieren.

Beispiele

Ein Beispiel, das TraceEvent verwendet, finden Sie unter Ablaufverfolgungsereignisse.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	evntrace.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll

Weitere Informationen