EventWriteEx-Funktion (evntprov.h)
Schreibt ein ETW-Ereignis mit einer Aktivitäts-ID, einer optionalen zugehörigen Aktivitäts-ID, Sitzungsfiltern und speziellen Optionen.
Syntax
ULONG EVNTAPI EventWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parameter
[in] RegHandle
Registrierungshandle des Anbieters. Das Handle stammt aus EventRegister. Das generierte Ereignis verwendet die dem Handle zugeordnete ProviderId.
[in] EventDescriptor
EVENT_DESCRIPTOR mit Ereignisinformationen (Metadaten), einschließlich ID, Version, Ebene, Schlüsselwort, Kanal, Opcode und Task.
Wichtig
ProviderId, Level und Keyword sind die wichtigsten Mittel zum Filtern von Ereignissen. Andere Filterarten sind möglich, haben aber einen viel höheren Aufwand. Weisen Sie jedem Ereignis immer eine Ebene ungleich null zu und Schlüsselwort (keyword).
[in] Filter
Ein 64-Bit-Bit-Wert. Jedes festgelegte Bit gibt an, dass dieses Ereignis von einer bestimmten Ablaufverfolgungssitzung ausgeschlossen werden soll.
Der Parameter Filter wird mit Ereignisanbietern verwendet, die benutzerdefinierte Ereignisfilterung basierend auf filterData aus EnableCallback ausführen.
Legen Sie Filter auf Null fest, wenn Sie keine benutzerdefinierten Ereignisfilter unterstützen oder wenn das Ereignis in alle Ablaufverfolgungssitzungen geschrieben werden soll. Legen Sie andernfalls Filter auf den bitweisen OR der Bezeichner von Sitzungen fest, die das Ereignis NICHT empfangen sollen.
[in] Flags
Legen Sie Flags für die normale Ereignisbehandlung auf 0 (null) fest.
Legen Sie Flags auf eine Kombination aus EVENT_WRITE_FLAG Werten für die spezielle Ereignisbehandlung fest.
EVENT_WRITE_FLAG_INPRIVATE (0x2)
Gibt an, dass dieses Ereignis von jeder Protokollierung ausgeschlossen werden soll, die die Option EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE festgelegt hat.
[in, optional] ActivityId
Ein optionaler Zeiger auf eine 128-Bit-Aktivitäts-ID für dieses Ereignis. Wenn dies nicht NULL ist, verwendet EventWriteEx den angegebenen Wert für die Aktivitäts-ID des Ereignisses. Wenn dies NULL ist, verwendet EventWriteEx die Aktivitäts-ID des aktuellen Threads.
Ablaufverfolgungsverarbeitungstools können die Aktivitäts-ID des Ereignisses verwenden, um Ereignisse in Gruppen zu organisieren, die als Aktivitäten bezeichnet werden. Weitere Informationen zur Aktivitäts-ID finden Sie unter EventActivityIdControl.
[in, optional] RelatedActivityId
Ein optionaler Zeiger auf eine 128-Bit-Aktivitäts-ID, die das übergeordnete Element der Aktivität dieses Ereignisses ist. Wenn dies nicht NULL ist, verwendet EventWriteEx den angegebenen Wert für die zugehörige Aktivitäts-ID des Ereignisses. Wenn dies NULL ist, weist das Ereignis keine zugehörige Aktivitäts-ID auf. Die zugehörige Aktivitäts-ID wird normalerweise für das START-Ereignis der Aktivität festgelegt (das erste Ereignis der Aktivität, protokolliert mit Opcode = START).
Ablaufverfolgungsverarbeitungstools können die zugehörige Aktivitäts-ID des Ereignisses verwenden, um die Beziehung zwischen Aktivitäten zu bestimmen, z. B. ist die zugehörige Aktivität das übergeordnete Element der neu gestarteten Aktivität. Weitere Informationen zur zugehörigen Aktivitäts-ID finden Sie unter EventActivityIdControl.
[in] UserDataCount
Anzahl der EVENT_DATA_DESCRIPTOR Strukturen in UserData. Die maximale Anzahl ist 128.
[in, optional] UserData
Ein Array von UserDataCountEVENT_DATA_DESCRIPTOR Strukturen, die die Daten beschreiben, die in das Ereignis eingeschlossen werden sollen. UserData kann NULL sein, wenn UserDataCount null ist.
Jeder EVENT_DATA_DESCRIPTOR beschreibt einen Speicherblock, der in das Ereignis eingeschlossen werden soll. Die angegebenen Blöcke werden in der Reihenfolge verkettet, ohne dass der Inhalt des Ereignisses aufgefüllt oder ausgerichtet ist. Bei Verwendung der manifestbasierten Decodierung muss der Ereignisinhalt mit dem Layout übereinstimmen, das in der Vorlage angegeben ist, die dem Ereignis im Manifest zugeordnet ist.
Rückgabewert
Gibt ERROR_SUCCESS zurück, wenn erfolgreich oder ein Fehlercode vorhanden ist. Mögliche Fehlercodes sind:
- ERROR_INVALID_PARAMETER: Mindestens ein Parameter ist ungültig.
- ERROR_INVALID_HANDLE: Das Registrierungshandle des Anbieters ist ungültig.
- ERROR_ARITHMETIC_OVERFLOW: Die Ereignisgröße ist größer als das zulässige Maximum (64 KB – Header).
- ERROR_MORE_DATA: Die Sitzungspuffergröße ist für das Ereignis zu klein.
- ERROR_NOT_ENOUGH_MEMORY: Tritt auf, wenn gefüllte Puffer versuchen, auf den Datenträger zu leeren, Datenträger-IOs jedoch nicht schnell genug ausgeführt werden. Dies geschieht, wenn der Datenträger langsam ist und der Ereignisdatenverkehr hoch ist. Schließlich gibt es keine freien (leeren) Puffer mehr, und das Ereignis wird gelöscht.
- STATUS_LOG_FILE_FULL: Die Echtzeitwiedergabedatei ist voll. Ereignisse werden erst in der Sitzung protokolliert, wenn ein Echtzeitconsumer die Ereignisse aus der Wiedergabedatei nutzt.
Der Fehlercode ist in erster Linie für die Verwendung in Debug- und Diagnoseszenarien vorgesehen. Der meiste Produktionscode sollte weiterhin ausgeführt werden und weiterhin Ereignisse melden, auch wenn ein ETW-Ereignis nicht geschrieben werden konnte. Daher sollten Releasebuilds den Fehlercode in der Regel ignorieren.
Hinweise
Die meisten Ereignisanbieter rufen EventWriteEx nicht direkt auf. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWriteEx und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden.
EventWriteEx leitet das Ereignis an die entsprechenden Ablaufverfolgungssitzungen basierend auf der ProviderId (ermittelt aus regHandle), Level, Keyword und anderen Ereignismerkmalen weiter. Wenn dieses Ereignis nicht von Ablaufverfolgungssitzungen aufgezeichnet wird, führt diese Funktion nichts aus und gibt ERROR_SUCCESS zurück.
Um die Auswirkungen auf die Leistung von Ereignissen zu reduzieren, die nicht von einer Ablaufverfolgungssitzung aufgezeichnet werden, können Sie EventEnabled aufrufen, um zu bestimmen, ob eine Ablaufverfolgungssitzung Ihr Ereignis vor dem Vorbereiten der Daten und aufrufen EventWriteEx aufzeichnet.
Ein Anbieter kann Filter definieren, die eine Sitzung verwendet, um Ereignisse basierend auf Ereignisdaten zu filtern. Die Kernfilter basieren auf Ebene und Schlüsselwörtern. Ereignisanbieter können komplexere Filter unterstützen. Der Ereignisanbieter kann Filterinformationen vom FilterData-Parameter von EnableCallback empfangen. Der Anbieter kann den Filter auswerten und den Filter-Parameter von EventWriteEx verwenden, um anzugeben, dass bestimmte Ablaufverfolgungssitzungen den Filter nicht bestanden haben und daher das Ereignis nicht empfangen sollten.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 7 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 R2 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | evntprov.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |