StartKernelTrace
Fungsi ini mendaftar dan memulai sesi pelacakan peristiwa kernel. Anda juga dapat mengaktifkan stackwalking untuk peristiwa kernel tertentu menggunakan fungsi ini.
ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);
Parameter
TraceHandle [out]
Menyimpan handel ke sesi pelacakan peristiwa. Parameter ini diatur ke nol jika handel tidak valid. Parameter ini tidak boleh dibandingkan dengan INVALID_HANDLE_VALUE. Jangan gunakan handel ini jika fungsi gagal.
Properti [masuk, keluar]
Menyimpan pointer ke struktur EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES mengonfigurasi aspek perilaku sesi tertentu.
Anggota pertama dari struktur EVENT_TRACE_PROPERTIES adalah struktur WNODE_HEADER, yang disebut di sini sebagai Wnode.
Berikut ini EVENT_TRACE_PROPERTIES. Anggota Wnode harus diatur untuk mengonfigurasi kontrol pelacakan kernel.
BufferSize
Anggota ini berisi ukuran total, dalam byte, memori yang dialokasikan untuk properti sesi pelacakan peristiwa. Ukuran memori harus mencakup cukup ruang untuk menyimpan data berikut:
Struktur EVENT_TRACE_PROPERTIES.
String nama sesi.
String nama file log.
Guid
Setiap sesi pelacakan harus memiliki GUID yang ditentukan untuk mereferensikan sesi.
Untuk sesi pencatat kernel NT, anggota ini harus diatur ke SystemTraceControlGuid. Untuk informasi selengkapnya tentang konstanta mode pengelogan, lihat Konstanta Pencatat Kernel NT.
ClientContext
Anggota ini mengatur resolusi jam yang digunakan saat stempel waktu pengelogan untuk setiap peristiwa dihitung. Nilai default untuk anggota ini adalah penghitung kinerja kueri.
Anda dapat menentukan satu atau beberapa nilai berikut:
1: Penghitung kinerja kueri (QPC). QPC menyediakan stempel waktu resolusi tinggi (100 nanodetik), tetapi relatif lebih mahal untuk diambil. Gunakan resolusi ini jika Anda memiliki tingkat peristiwa tinggi atau jika konsumen menggabungkan peristiwa dari buffer yang berbeda. Pada komputer yang lebih lama, stempel waktu mungkin tidak akurat karena penghitung terkadang melompat ke depan karena kesalahan perangkat keras.
2: Waktu sistem. Waktu sistem menyediakan stempel waktu resolusi rendah (10 milidetik), tetapi relatif lebih murah untuk diambil. Jika volume peristiwa tinggi, resolusi untuk waktu sistem mungkin tidak cukup baik untuk menentukan urutan peristiwa. Dalam hal ini, serangkaian peristiwa akan memiliki stempel waktu yang sama, tetapi urutan di mana ETW mengirimkan peristiwa mungkin tidak benar.
3: Penghitung siklus CPU. Penghitung CPU menyediakan stempel waktu resolusi tertinggi dan merupakan yang paling murah untuk diambil. Namun, penghitung CPU tidak dapat diandalkan dan tidak boleh digunakan dalam produksi. Misalnya, pada beberapa komputer, timer mengubah frekuensi karena perubahan termal dan daya, selain berhenti di beberapa status. Jika perangkat keras Anda tidak mendukung tipe jam ini, ETW menggunakan waktu sistem. Di Windows Server 2003, Windows XP dengan SP1, dan Windows XP, nilai ini tidak didukung. Ini diperkenalkan di Windows Server 2003 dengan SP1 dan Windows XP dengan SP2.
Bendera
Anggota ini harus berisi WNODE_FLAG_TRACED_GUID untuk menunjukkan bahwa struktur berisi informasi pelacakan peristiwa dan informasi dikirim ke pencatat. WNODE_FLAG_TRACED_GUID didefinisikan dalam Evntrace.h.
Anggota EVENT_TRACE_PROPERTIES berikut juga harus diatur:
LogFileMode
Menunjukkan mode pengelogan mana yang akan digunakan dalam sesi pelacakan peristiwa kernel. Anda dapat menggunakan anggota ini untuk menentukan bahwa peristiwa akan ditulis ke file log, konsumen real-time, atau keduanya.
Anggota ini juga dapat digunakan untuk menentukan bahwa sesi tersebut adalah sesi pencatat privat. Satu atau beberapa mode dapat ditentukan. Untuk daftar mode yang mungkin, lihat Konstanta Mode Pengelogan.
Catatan Jangan tentukan pengelogan real-time kecuali ada konsumen real-time yang siap mengonsumsi peristiwa. Jika tidak ada konsumen real-time, peristiwa ditulis ke file pemutaran. Ukuran file pemutaran terbatas. Jika batas tercapai, tidak ada peristiwa baru yang dicatat ke file log atau file pemutaran. Fungsi pengelogan gagal dengan STATUS_LOG_FILE_FULL.
EnableFlags
Anggota ini hanya digunakan untuk sesi pencatat kernel NT. Ini mengidentifikasi ke pencatat kernel peristiwa mana yang akan dilacak. Dengan menggunakan LOGICAL OR, anggota ini dapat berisi satu atau beberapa nilai. Selain peristiwa yang ditentukan, pencatat kernel juga mencatat peristiwa konfigurasi perangkat keras.
Bendera kontrol jejak berikut tersedia selain bendera yang disediakan oleh EVENT_TRACE_PROPERTIES:
LogFileNameOffset
Angka ini menunjukkan offset dari awal memori yang dialokasikan ke struktur ke awal string yang dihentikan null yang berisi nama file log.
Pertimbangan berikut berlaku:
Ekstensi nama file harus .etl.
Semua folder di jalur harus ada.
Jalurnya bisa relatif, absolut, lokal, atau jarak jauh.
Jalur tidak boleh berisi variabel lingkungan, karena variabel tersebut tidak diperluas.
Pengguna yang memulai pelacakan harus memiliki izin tulis pada folder.
Nama file log dibatasi hingga 1024 karakter.
Jika Anda mengatur LogFileMode ke EVENT_TRACE_PRIVATE_LOGGER_MODE atau EVENT_TRACE_FILE_MODE_NEWFILE, pastikan untuk mengalokasikan cukup memori untuk menyertakan pengidentifikasi proses yang ditambahkan ke nama file untuk sesi pencatat privat dan nomor berurutan yang ditambahkan ke file log yang dibuat menggunakan mode log file baru.
Jika Anda tidak ingin mencatat peristiwa ke file log (misalnya, Anda hanya menentukan EVENT_TRACE_REAL_TIME_MODE), atur LogFileNameOffset ke nol. Jika Anda hanya menentukan pengelogan real time dan juga menyediakan offset dengan nama file log yang valid, nama file log digunakan untuk membuat file log berurutan dan mencatat peristiwa ke file log. File log berurutan juga dibuat jika LogFileMode adalah nol dan Anda memberikan offset dengan nama file log yang valid.
Jika Anda ingin mencatat peristiwa ke file log, Anda harus mengalokasikan cukup memori agar struktur ini menyertakan nama file log dan nama sesi mengikuti struktur. Nama file log harus mengikuti nama sesi dalam memori.
File pelacakan dibuat menggunakan deskriptor keamanan default, yang berarti bahwa file log akan memiliki ACL yang sama dengan direktori induk. Jika Anda ingin membatasi akses ke file, buat direktori induk dengan ACL yang sesuai.
LoggerNameOffset
Anggota ini mewakili offset dari awal memori yang dialokasikan ke struktur hingga awal string yang dihentikan null yang berisi nama sesi.
Pertimbangan berikut berlaku:
Nama sesi dibatasi hingga 1024 karakter.
Nama sesi tidak peka huruf besar/kecil dan harus unik.
Ketika mengalokasikan memori untuk struktur ini, memori yang cukup harus dicadangkan untuk menyertakan nama sesi dan nama file log mengikuti struktur.
Nama sesi harus muncul sebelum nama file log dalam memori. Nama file log harus disalin ke area offset. Fungsi ini menulis nama sesi yang ditentukan oleh KERNEL_LOGGER_NAME.
Menurut jenis file log yang dipilih, mungkin perlu untuk mengatur anggota MaximumFileSize .
Catatan Tidak perlu mengatur nama pencatat di LoggerNameOffset karena fungsi ini selalu menggunakan nilai KERNEL_LOGGER_NAME untuk memanggil StartKernelTrace. Fungsi ini memeriksa apakah Wnode.Guid sesuai dengan SystemTraceControlGuid; jika tidak, ia mengembalikan ERROR_INVALID_PARAMETER. Jika Wnode.Guid sesuai dengan KernelRundownGuid, nama pencatat harus ditentukan. KernelRundownGuid adalah GUID kontrol yang digunakan untuk mencatat peristiwa seperti informasi proses yang ada, informasi utas, gambar yang dimuat per proses, dan konfigurasi perangkat keras seperti CPU, video, disk, kartu jaringan, layanan, daya, Plug and Play, dan saluran IDE disk.
Tampilkan Nilai
ERROR_SUCCESS menunjukkan keberhasilan.
Nilai kesalahan yang mungkin dijelaskan dalam tabel berikut ini.
| Nilai Kesalahan | Deskripsi |
|---|---|
ERROR_ALREADY_EXISTS |
Hanya satu instans pencatat kernel yang berjalan pada sistem. Jika fungsi ini mencoba untuk memulai setelah komponen lain memulai pengelogan kernel, kesalahan ini mungkin dikembalikan. |
ERROR_INVALID_FLAGS |
Mungkin menunjukkan bahwa ada bendera pelacakan yang tidak valid di Properties.EnableFlags. |
ERROR_OUT_OF_MEMORY |
Mungkin menunjukkan kegagalan mengalokasikan memori untuk EVENT_TRACE_PROPERTIES. |
Jika fungsi gagal karena alasan selain yang tercantum, kode kesalahan sistem dikembalikan.
Keterangan
Jika StackTracingEventIds berisi peristiwa yang tidak diaktifkan di EVENT_TRACE_PROPERTIES. Bidang EnableFlags atau tidak dapat didekode oleh Kernel Trace Control, bendera tersebut diabaikan, dan tidak ada kode kesalahan yang dikembalikan.
Persyaratan:
Versi: Tersedia dimulai di Windows Vista. Struktur ini didistribusikan dengan Penganalisis Kinerja Windows.
Header: Dinyatakan dalam KernelTraceControl.h. Sertakan KernelTraceControl.h.
Perpustakaan: Terkandung dalam KernelTraceControl.dll.