Fungsi EventWriteEx (evntprov.h)

Artikel
08/23/2023

Menulis peristiwa ETW dengan ID aktivitas, ID aktivitas terkait opsional, filter sesi, dan opsi khusus.

Sintaks

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

Handel pendaftaran penyedia. Handel berasal dari EventRegister. Peristiwa yang dihasilkan akan menggunakan ProviderId yang terkait dengan handel.

[in] EventDescriptor

EVENT_DESCRIPTOR dengan informasi peristiwa (metadata) termasuk ID, Versi, Tingkat, Kata Kunci, Saluran, Opcode, dan Tugas.

Penting

ProviderId, Level, dan Keyword adalah sarana utama untuk memfilter peristiwa. Jenis pemfilteran lainnya dimungkinkan tetapi memiliki overhead yang jauh lebih tinggi. Selalu tetapkan tingkat bukan nol dan kata kunci untuk setiap peristiwa.

[in] Filter

Nilai bitmask 64-bit. Setiap bit yang ditetapkan menunjukkan bahwa peristiwa ini harus dikecualikan dari sesi pelacakan tertentu.

Parameter Filter digunakan dengan penyedia peristiwa yang melakukan pemfilteran peristiwa kustom berdasarkan FilterData dari EnableCallback.

Atur Filter ke nol jika Anda tidak mendukung filter peristiwa kustom atau jika peristiwa harus ditulis ke semua sesi pelacakan. Jika tidak, atur Filter ke bitwise-OR pengidentifikasi sesi yang SEHARUSNYA TIDAK menerima peristiwa.

[in] Flags

Atur Bendera ke nol untuk penanganan peristiwa normal.

Atur Bendera ke kombinasi nilai EVENT_WRITE_FLAG untuk penanganan peristiwa khusus.

EVENT_WRITE_FLAG_INPRIVATE (0x2)

Menunjukkan bahwa peristiwa ini harus dikecualikan dari pencatat apa pun yang telah mengatur opsi EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE .

[in, optional] ActivityId

Penunjuk opsional ke ID aktivitas 128-bit untuk peristiwa ini. Jika ini non-NULL, EventWriteEx akan menggunakan nilai yang ditentukan untuk ID aktivitas peristiwa. Jika ini ADALAH NULL, EventWriteEx akan menggunakan ID aktivitas utas saat ini.

Alat pemrosesan pelacakan dapat menggunakan ID aktivitas acara untuk mengatur peristiwa ke dalam grup yang disebut aktivitas. Untuk informasi tambahan tentang ID aktivitas, lihat EventActivityIdControl.

[in, optional] RelatedActivityId

Penunjuk opsional ke ID aktivitas 128-bit yang merupakan induk aktivitas acara ini. Jika ini non-NULL, EventWriteEx akan menggunakan nilai yang ditentukan untuk ID aktivitas terkait peristiwa. Jika ini ADALAH NULL, peristiwa tidak akan memiliki ID aktivitas terkait. ID aktivitas terkait biasanya diatur pada peristiwa MULAI aktivitas (peristiwa pertama aktivitas, dicatat dengan Opcode = START).

Alat pemrosesan pelacakan dapat menggunakan ID aktivitas terkait peristiwa untuk menentukan hubungan antara aktivitas, misalnya aktivitas terkait adalah induk dari aktivitas yang baru dimulai. Untuk informasi tambahan tentang ID aktivitas terkait, lihat EventActivityIdControl.

[in] UserDataCount

Jumlah struktur EVENT_DATA_DESCRIPTOR di UserData. Jumlah maksimum adalah 128.

[in, optional] UserData

Array userDataCountEVENT_DATA_DESCRIPTOR struktur yang menjelaskan data yang akan disertakan dalam peristiwa tersebut. UserData mungkin NULL jika UserDataCount adalah nol.

Setiap EVENT_DATA_DESCRIPTOR menjelaskan satu blok memori yang akan disertakan dalam peristiwa tersebut. Blok yang ditentukan akan digabungkan secara berurutan tanpa padding atau perataan untuk membentuk konten peristiwa. Jika menggunakan pendekodean berbasis manifes, konten peristiwa harus cocok dengan tata letak yang ditentukan dalam templat yang terkait dengan peristiwa dalam manifes.

Nilai kembali

Mengembalikan ERROR_SUCCESS jika berhasil atau kode kesalahan. Kemungkinan kode kesalahan meliputi yang berikut ini:

ERROR_INVALID_PARAMETER: Satu atau beberapa parameter tidak valid.
ERROR_INVALID_HANDLE: Handel pendaftaran penyedia tidak valid.
ERROR_ARITHMETIC_OVERFLOW: Ukuran peristiwa lebih besar dari maksimum yang diizinkan (64KB - header).
ERROR_MORE_DATA: Ukuran buffer sesi terlalu kecil untuk peristiwa tersebut.
ERROR_NOT_ENOUGH_MEMORY: Terjadi ketika buffer yang diisi mencoba memerah ke disk, tetapi IO disk tidak terjadi cukup cepat. Ini terjadi ketika disk lambat dan lalu lintas peristiwa padat. Akhirnya, tidak ada lagi buffer gratis (kosong) dan acara dihilangkan.
STATUS_LOG_FILE_FULL: File pemutaran real-time penuh. Peristiwa tidak dicatat ke sesi sampai konsumen real-time mengonsumsi peristiwa dari file pemutaran.

Kode kesalahan terutama ditujukan untuk digunakan dalam skenario penelusuran kesalahan dan diagnostik. Sebagian besar kode produksi harus terus berjalan dan terus melaporkan peristiwa bahkan jika peristiwa ETW tidak dapat ditulis, sehingga build rilis biasanya harus mengabaikan kode kesalahan.

Keterangan

Sebagian besar penyedia peristiwa tidak akan memanggil EventWriteEx secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWriteEx, dan EventUnregister. Misalnya, Anda dapat menulis manifes peristiwa lalu menggunakan Pengkompilasi Pesan untuk menghasilkan kode C/C++ untuk peristiwa tersebut, atau Anda mungkin menggunakan TraceLogging untuk menghindari kebutuhan manifes.

EventWriteEx akan merutekan peristiwa ke sesi pelacakan yang sesuai berdasarkan ProviderId (ditentukan dari RegHandle), Level, Kata Kunci, dan karakteristik peristiwa lainnya. Jika tidak ada sesi jejak yang merekam peristiwa ini, fungsi ini tidak akan melakukan apa-apa dan mengembalikan ERROR_SUCCESS.

Untuk mengurangi dampak performa peristiwa yang tidak direkam oleh sesi pelacakan apa pun, Anda dapat memanggil EventEnabled untuk menentukan apakah ada sesi pelacakan yang merekam peristiwa Anda sebelum menyiapkan data dan memanggil EventWriteEx.

Penyedia dapat menentukan filter yang digunakan sesi untuk memfilter peristiwa berdasarkan data peristiwa. Filter inti didasarkan pada tingkat dan kata kunci. Penyedia peristiwa dapat mendukung filter yang lebih kompleks. Penyedia peristiwa dapat menerima informasi filter dari parameter FilterDataenableCallback. Penyedia dapat mengevaluasi filter dan menggunakan parameter FilterEventWriteEx untuk menunjukkan bahwa sesi pelacakan tertentu tidak melewati filter dan karenanya tidak boleh menerima peristiwa.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 R2 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	evntprov.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll