PEVENT_RECORD_CALLBACK fungsi panggilan balik (evntrace.h)

Artikel
03/11/2023

Konsumen menerapkan panggilan balik ini untuk menerima peristiwa dari sesi pemrosesan jejak.

Jenis PEVENT_RECORD_CALLBACK menentukan penunjuk ke fungsi panggilan balik ini. EventRecordCallback adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi.

Sintaks

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

Parameter

[in] EventRecord

Arahkan ke struktur EVENT_RECORD yang berisi informasi peristiwa.

Menampilkan nilai

Tidak ada

Keterangan

Untuk menentukan fungsi yang dipanggil ETW untuk mengirimkan peristiwa, atur anggota EventRecordCallback, Context, dan ProcessTraceMode dari struktur EVENT_TRACE_LOGFILE yang Anda berikan ke fungsi OpenTrace .

Atur EventRecordCallback ke alamat fungsi panggilan balik Anda.
Atur Konteks ke nilai yang harus disertakan dalam bidang UserContext dari setiap EVENT_RECORD yang disediakan untuk panggilan balik Anda.
Atur ProcessTraceMode ke bendera yang akan digunakan saat memproses jejak. Untuk menggunakan EventRecordCallback, Anda harus menyertakan PROCESS_TRACE_MODE_EVENT_RECORD dalam nilai ProcessTraceMode .

Catatan

Jika fungsi EventRecordCallback Anda menerima data yang rusak dari ProcessTrace, periksa kembali bendera yang ditentukan di ProcessTraceMode bidang EVENT_TRACE_LOGFILE struktur yang disediakan untuk OpenTrace. EVENT_TRACE_LOGFILEBidang EventCallback dan EventRecordCallback tumpang tindih dengan anggota serikat. ProcessTraceMode Jika bidang menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera, ProcessTrace akan memanggil panggilan balik Anda menggunakan tanda tangan fungsi EventRecordCallback. Jika tidak, ProcessTrace akan memanggil panggilan balik Anda menggunakan tanda tangan fungsi EventCallback .

Setelah menggunakan OpenTrace untuk membuat sesi pemrosesan jejak, panggil fungsi ProcessTrace untuk mulai menerima peristiwa.

Ketika ProcessTrace mulai memproses peristiwa dari pelacakan, processTrace dapat memanggil panggilan balik Anda dengan satu atau beberapa peristiwa sintetis yang berisi data tentang jejak (metadata) daripada data dari peristiwa yang dicatat. Peristiwa sintetis ini memiliki EventHeader.ProviderId yang diatur ke EventTraceGuid dan EventHeader.EventDescriptor.Opcode yang ditetapkan berdasarkan konten peristiwa sintetis. Misalnya, peristiwa pertama dari setiap file pelacakan akan menjadi peristiwa sintetis dengan Opcode 0 yang berisi informasi TRACE_LOGFILE_HEADER .

Semua peristiwa lain yang Anda terima berisi data peristiwa khusus penyedia. Anda menggunakan anggota EventHeader.ProviderId dan EventHeader.EventDescriptordari EVENT_RECORD untuk menentukan jenis peristiwa yang Anda terima.

Jika peristiwa berasal dari penyedia terkenal dan Anda tahu tata letak data, Anda dapat menggunakan sistem Anda sendiri untuk mendekode peristiwa.
Jika bidang EventHeader.Flags menyertakan EVENT_HEADER_FLAG_TRACE_MESSAGE bendera, peristiwa tersebut adalah pesan WPP. Jika informasi decoding yang sesuai (file TMF atau PDB) tersedia, peristiwa dapat didekode menggunakan TdhGetProperty atau TdhGetWppProperty.
Jika tidak, peristiwa tersebut mungkin merupakan peristiwa berbasis MOF, berbasis manifes, atau TraceLogging. Jika informasi pendekodean yang sesuai tersedia, peristiwa dapat didekode menggunakan TdhGetEventInformation.
- Jika peristiwa menggunakan decoding berbasis MOF, TdhGetEventInformation akan mencari informasi pendekodean peristiwa di penyimpanan data WMI sistem.
- Jika peristiwa menggunakan decoding berbasis manifes, TdhGetEventInformation akan mencari informasi pendekodean peristiwa dalam manifes terdaftar sistem atau dalam manifes atau biner yang dimuat ke dalam konteks decoding per proses oleh TdhLoadManifest atau TdhLoadManifestFromBinary.
- Jika peristiwa menggunakan decoding berbasis TraceLogging, TdhGetEventInformation akan menggunakan informasi decoding dari dalam peristiwa.

Dalam kebanyakan kasus, peristiwa akan dikirimkan ke panggilan balik Anda dalam urutan terjadinya (urutan tanda waktu). Namun, dalam keadaan tertentu, peristiwa mungkin tidak dikirimkan dalam urutan aslinya.

Jika jejak menggunakan waktu sistem untuk tanda waktu sesi (yaitu sesi pelacakan dimulai dengan properties.Wnode.ClientContext diatur ke 2) dan jam sistem disesuaikan mundur saat sesi mengumpulkan peristiwa, beberapa peristiwa mungkin dikirimkan secara tidak berurutan. Untuk menghindari hal ini, atur ClientContext ke 0 untuk mendapatkan tanda waktu default (waktu QPC).
Jika jejak dikumpulkan menggunakan tanda waktu dari jam yang tidak tepat, maka peristiwa dengan tanda waktu yang sama dari CPU yang berbeda dapat dikirimkan secara tidak berurutan. Ini paling sering terjadi ketika jejak menggunakan waktu sistem untuk tanda waktu sesi karena waktu sistem berdetak. Masalah ini dapat dihindari dengan memulai sesi dengan EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING bendera LogFileMode , meskipun ini dapat berdampak negatif pada performa pelacakan yang substansial. Dimulai dengan Windows 10: Jenis jam waktu sistem menggunakan GetSystemTimePreciseAsFileTime untuk mengurangi kemungkinan masalah ini.
Jika jejak rusak, dihasilkan menggunakan API tingkat rendah yang tidak mempertahankan aturan tanda waktu yang diharapkan dalam file, atau menggunakan opsi penimpaan tanda waktu saat menulis peristiwa, beberapa peristiwa mungkin dikirimkan secara tidak berurutan.

Detail teknis: Peristiwa disimpan dalam buffer. Setiap buffer ditetapkan ke aliran buffer, biasanya satu aliran untuk setiap CPU. Implementasi ProcessTrace mengasumsikan bahwa semua peristiwa dalam buffer diurutkan berdasarkan tanda waktu dan bahwa setiap buffer berisi peristiwa untuk satu rentang waktu yang tidak tumpang tindih dengan rentang buffer lain dalam aliran buffer tersebut. Ketika asumsi ini tidak terpenuhi, ProcessTracedapat mengirimkan peristiwa secara tidak berurutan.

Ketika sesi pengumpulan jejak real-time tidak memiliki sesi pemrosesan jejak terkait, peristiwa yang dikumpulkan akan di-buffer oleh sistem sampai buffer penuh. Ketika sesi pemrosesan jejak terhubung ke sesi pengumpulan jejak real-time, sesi pemrosesan jejak akan menerima peristiwa sintetis untuk sesi, lalu peristiwa yang di-buffer, dan kemudian akan mulai menerima peristiwa real-time yang baru dihasilkan. Jika sesi pemrosesan real-time kedua terhubung ke sesi pengumpulan jejak yang sama, sesi tersebut akan menerima peristiwa sintetis dan peristiwa real-time yang baru dihasilkan (sesi pemrosesan jejak kedua tidak akan menerima peristiwa yang lebih lama).

Penting

Saat memproses peristiwa dari sesi real-time, jika panggilan balik pemrosesan membutuhkan terlalu banyak waktu untuk memproses setiap peristiwa dan peristiwa tiba terlalu cepat, itu akan tertinggal. Sistem akan menyangga peristiwa untuk mencegah kehilangan data tetapi ini meningkatkan penggunaan sumber daya sistem (misalnya memori dan penggunaan disk). Hindari masalah ini dengan menggunakan filter sesi (misalnya filter tingkat dan kata kunci untuk setiap penyedia) untuk mengurangi laju peristiwa masuk, melakukan pemfilteran awal dalam panggilan balik Anda untuk melewati peristiwa yang tidak memerlukan pemrosesan penuh, dan mengoptimalkan panggilan balik Anda untuk kembali secepat mungkin untuk menghindari pemblokiran utas pemrosesan.

Untuk detail tambahan tentang menginterpretasikan data peristiwa, lihat Mengonsumsi Peristiwa dan Mengambil Data Peristiwa Menggunakan TDH.

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	evntrace.h