TraceEventInstance-Funktion (evntrace.h)

Artikel
08/23/2023

Ein RegisterTraceGuids-basierter ("Classic")-Ereignisanbieter verwendet die TraceEventInstance-Funktion, um ein strukturiertes Ereignis mit einem instance Bezeichner an eine Ereignisablaufverfolgungssitzung zu senden.

Das Ereignis verwendet einen instance-Bezeichner, um das Ereignis einer Transaktion zuzuordnen. Diese Funktion kann auch verwendet werden, um hierarchische Beziehungen zwischen verwandten Ereignissen nachzuverfolgen.

Syntax

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Parameter

[in] TraceHandle

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

[in] EventTrace

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

Größe
Flags
RegHandle

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

Legen Sie zum Nachverfolgen hierarchischer Beziehungen zwischen verwandten Ereignissen auch das ParentRegHandle-Element fest.

[in] InstInfo

Zeiger auf eine EVENT_INSTANCE_INFO-Struktur, die das Registrierungshandle für diese Ereignisablaufverfolgungsklasse und den instance Bezeichner enthält. Verwenden Sie die CreateTraceInstanceId-Funktion , um die -Struktur zu initialisieren.

[in] ParentInstInfo

Zeiger auf eine EVENT_INSTANCE_INFO-Struktur, die das Registrierungshandle für die übergeordnete Ereignisablaufverfolgungsklasse und ihren instance Bezeichner enthält. Verwenden Sie die CreateTraceInstanceId-Funktion , um die -Struktur zu initialisieren. Legen Sie auf NULL fest, wenn Sie keine hierarchische Beziehung nachverfolgen.

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_FLAGS

Das Flags-Element des EVENT_INSTANCE_HEADER enthält keine WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

Es war nicht genügend Arbeitsspeicher vorhanden, um den Funktionsaufruf abzuschließen. Die Ursachen für diesen Fehlercode werden im folgenden Abschnitt hinweise beschrieben.
ERROR_INVALID_PARAMETER

Es trifft eine der folgenden Bedingungen zu:
- EventTrace ist NULL.
- pInstInfo ist NULL.
- Die Member von pInstInfo sind NULL.
- TraceHandle ist NULL.
- Der Size-Member des EVENT_INSTANCE_HEADER 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.

Windows 2000 und Windows XP: 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_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_INSTANCE_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 die CreateTraceInstanceId-Funktion aufrufen, um einen instance Bezeichner für die registrierte Ereignisablaufverfolgungsklasse zu erstellen.
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 TraceEvent-Funktion , um nicht verwandte Ereignisse nachzuverfolgen.

Windows XP: Funktioniert nicht ordnungsgemäß.

Beispiele

Ein Beispiel für das Generieren verwandter Ereignissätze mit CreateTraceInstanceId und TraceEventInstance finden Sie unter Ablaufverfolgungsereignisinstanzen.

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