TraceEvent-Funktion (evntrace.h)

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.

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

Weitere Informationen

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance