Fungsi EventWrite (evntprov.h)

Artikel
03/11/2023

Menulis peristiwa ETW yang menggunakan ID aktivitas utas saat ini.

Sintaks

ULONG EVNTAPI EventWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [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] 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.

Menampilkan nilai

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 EventWrite secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWrite, 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.

EventWrite akan merutekan peristiwa ke sesi pelacakan yang sesuai berdasarkan ProviderId (ditentukan dari RegHandle), Tingkat, 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 EventWrite.

EventWrite mengatur ID aktivitas peristiwa ke ID aktivitas utas saat ini. EventWrite tidak menyertakan ID aktivitas terkait dalam peristiwa tersebut. Untuk menentukan ID aktivitas yang berbeda atau menambahkan ID aktivitas terkait, gunakan EventWriteTransfer.

EventWrite setara dengan EventWriteEx dengan 0 untuk Filter, 0 untuk Bendera, NULL untuk ActivityId, dan NULL untuk RelatedActivityId.

Persyaratan


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