Fungsi ControlTraceW (evntrace.h)
Fungsi ControlTrace memerah , mengkueri, memperbarui, atau menghentikan sesi pelacakan peristiwa yang ditentukan.
Sintaks
ULONG WMIAPI ControlTraceW(
[in] TRACEHANDLE TraceHandle,
[in] LPCWSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Parameter
[in] TraceHandle
Menangani ke sesi pelacakan peristiwa, atau 0. Anda harus menentukan TraceHandle bukan nol jika InstanceNameNULL. ETW mengabaikan handel jika InstanceName bukan NULL.
Fungsi StartTrace mengembalikan handel ini saat pelacakan baru dimulai. Untuk mendapatkan handel pelacakan yang ada, gunakan ControlTrace untuk mengkueri properti pelacakan berdasarkan nama pelacakan lalu dapatkan handel dari bidang Wnode.HistoricalContext dari data yang dikembalikan EVENT_TRACE_PROPERTIES .
[in] InstanceName
Nama sesi pelacakan peristiwa, atau NULL. Anda harus menentukan InstanceName jika TraceHandle adalah 0.
Untuk menentukan sesi NT Kernel Logger, atur InstanceName ke KERNEL_LOGGER_NAME.
[in, out] Properties
Penunjuk ke struktur EVENT_TRACE_PROPERTIES yang diinisialisasi. Struktur ini harus di-zeroed-out sebelum mengatur bidang apa pun.
Jika ControlCode menentukan EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY , atau EVENT_TRACE_CONTROL_FLUSH, Anda hanya perlu mengatur anggota Wnode.BufferSize, Wnode.Guid, LoggerNameOffset, dan LogFileNameOffset dari struktur EVENT_TRACE_PROPERTIES . Jika sesi adalah sesi privat, Anda juga perlu mengatur LogFileMode. Anda dapat menggunakan nama sesi maksimum (1024 karakter) dan panjang nama file log maksimum (1024 karakter) untuk menghitung ukuran buffer dan offset jika tidak diketahui.
Jika ControlCode menentukan EVENT_TRACE_CONTROL_UPDATE, pada input, anggota harus menentukan nilai baru untuk properti yang akan diperbarui. Pada output, Properti berisi properti dan statistik untuk sesi pelacakan peristiwa. Anda bisa memperbarui properti berikut ini.
EnableFlags: Atur anggota ini ke 0 untuk menonaktifkan semua penyedia sistem. Atur ini ke nilai bukan nol untuk menentukan penyedia sistem yang ingin Anda aktifkan atau tetap aktifkan. Ini mungkin bukan nol hanya untuk pencatat sistem.
FlushTimer: Atur anggota ini jika Anda ingin mengubah waktu untuk menunggu sebelum membersihkan buffer. Jika anggota ini adalah 0, anggota tidak diperbarui.
LogFileNameOffset: Atur anggota ini jika Anda ingin beralih ke file log lain atau untuk menghapus jejak mode buffering ke file log baru. Jika anggota ini adalah 0, nama file tidak diperbarui. Jika offset bukan nol dan Anda tidak mengubah nama file log, fungsi mengembalikan kesalahan.
LogFileMode: Atur anggota ini jika Anda ingin mengaktifkan dan menonaktifkan EVENT_TRACE_REAL_TIME_MODE . Untuk menonaktifkan penggunaan real time, atur anggota ini ke 0. Untuk mengaktifkan penggunaan real time (membuat sesi yang merekam ke disk serta mengirimkan peristiwa secara real time), atur anggota ini ke EVENT_TRACE_REAL_TIME_MODE dan itu akan or'd dengan mode saat ini.
MaximumBuffers: Atur anggota ini jika Anda ingin mengubah jumlah maksimum buffer yang digunakan ETW. Jika anggota ini adalah 0, anggota tidak diperbarui.
Untuk sesi pencatat privat, Anda hanya dapat memperbarui anggota LogFileNameOffset dan FlushTimer .
Jika Anda menggunakan struktur EVENT_TRACE_PROPERTIES yang baru diinisialisasi, nol-out struktur, lalu atur Wnode.BufferSize, Wnode.Guid, dan Wnode.Flags, dan nilai yang ingin Anda perbarui.
Jika Anda menggunakan kembali struktur EVENT_TRACE_PROPERTIES (yaitu menggunakan struktur yang sebelumnya Anda berikan ke StartTrace atau ControlTrace), pastikan untuk mengatur anggota LogFileNameOffset ke 0 kecuali Anda mengubah nama file log, dan pastikan untuk mengatur EVENT_TRACE_PROPERTIES. Wnode.Flags ke WNODE_FLAG_TRACED_GUID.
Dimulai dengan Windows 10, versi 1703: Untuk performa yang lebih baik dalam skenario lintas proses, Anda sekarang dapat meneruskan informasi pemfilteran ke ControlTrace untuk pencatat privat luas sistem. Anda harus menggunakan struktur EVENT_TRACE_PROPERTIES_V2 untuk menyertakan informasi pemfilteran. Lihat Mengonfigurasi dan Memulai Sesi Pencatat Privat untuk detail selengkapnya.
[in] ControlCode
Fungsi kontrol yang diminta. Anda dapat menentukan satu atau beberapa nilai berikut:
EVENT_TRACE_CONTROL_FLUSH: Membersihkan buffer aktif sesi.
Ini dapat digunakan dengan sesi dalam memori (sesi yang dimulai dengan bendera EVENT_TRACE_BUFFERING_MODE ) untuk menulis data dari jejak ke file.
Anda biasanya tidak perlu menghapus sesi berbasis file atau real-time karena ETW akan secara otomatis membersihkan buffer ketika penuh (yaitu ketika tidak memiliki ruang untuk peristiwa berikutnya), ketika FlushTimer sesi pelacakan kedaluwarsa, atau ketika sesi pelacakan ditutup.
Windows 2000: Nilai ini tidak didukung.
EVENT_TRACE_CONTROL_QUERY: Mengambil properti dan statistik sesi.
EVENT_TRACE_CONTROL_STOP: Menghentikan sesi. Handel sesi tidak lagi valid.
EVENT_TRACE_CONTROL_UPDATE: Updates properti sesi.
EVENT_TRACE_CONTROL_INCREMENT_FILE: Jika sesi memiliki
EVENT_TRACE_FILE_MODE_NEWFILE, perbarui sesi untuk segera beralih ke file berikutnya, daripada menunggu file sebelumnya terisi. Didukung mulai Windows 10 Pembaruan Oktober 2018.EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: Mengubah sesi mode file ke sesi real-time (memungkinkan pengiriman real time dan menonaktifkan penulisan peristiwa ke file ETL). Didukung dimulai dengan Windows 10 Pembaruan Oktober 2020.
Catatan
Tidak aman untuk membersihkan buffer atau menghentikan sesi pelacakan dari DllMain (dapat menyebabkan kebuntuan).
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem. Berikut ini adalah beberapa kesalahan umum dan penyebabnya.
ERROR_BAD_LENGTH
Salah satu hal berikut ini benar:
- Anggota Properti Wnode.BufferSizemenentukan ukuran yang salah.
- Properti tidak memiliki cukup ruang yang dialokasikan untuk menyimpan salinan nama sesi dan nama file log (jika digunakan).
ERROR_INVALID_PARAMETER
Salah satu hal berikut ini benar:
- Properti adalah NULL.
- InstanceName dan TraceHandle keduanya NULL.
- InstanceName adalah NULL dan TraceHandle bukan handel yang valid.
- Anggota LogFileNameOffsetproperti tidak valid.
- Anggota LoggerNameOffsetproperti tidak valid.
- Anggota Properti LogFileMode menentukan kombinasi bendera yang tidak valid.
- Anggota Wnode.Guidproperti adalahSystemTraceControlGuid, tetapi parameter InstanceName bukan
KERNEL_LOGGER_NAME.
ERROR_BAD_PATHNAME
Sesi lain sudah menggunakan nama file yang ditentukan oleh anggota LogFileNameOffset dari struktur Properti .
ERROR_MORE_DATA
Buffer untuk EVENT_TRACE_PROPERTIES terlalu kecil untuk menyimpan semua informasi untuk sesi. Jika Anda tidak memerlukan informasi properti sesi, Anda dapat mengabaikan kesalahan ini. Jika Anda menerima kesalahan ini saat menghentikan sesi, ETW akan menghentikan sesi sebelum menghasilkan kesalahan ini.
ERROR_ACCESS_DENIED
Hanya pengguna yang berjalan dengan hak istimewa administratif yang ditingkatkan, pengguna di grup Pengguna Log Performa, dan layanan yang berjalan sebagai LocalSystem, LocalService, NetworkService yang dapat mengontrol sesi pelacakan peristiwa. Untuk memberi pengguna terbatas kemampuan untuk mengontrol sesi pelacakan, tambahkan mereka ke grup Pengguna Log Performa. Hanya pengguna dengan hak administratif dan layanan yang berjalan sebagai LocalSystem yang dapat mengontrol sesi NT Kernel Logger.
Windows XP dan Windows 2000: Siapa pun dapat mengontrol sesi pelacakan.
ERROR_WMI_INSTANCE_NOT_FOUND
Sesi yang diberikan tidak berjalan.
ERROR_ACTIVE_CONNECTIONS
Ketika dikembalikan dari panggilan EVENT_TRACE_CONTROL_STOP, ini menunjukkan bahwa sesi sudah dalam proses berhenti.
Keterangan
Pengontrol pelacakan peristiwa memanggil fungsi ini.
Fungsi ini menggantikan fungsi FlushTrace, QueryTrace, StopTrace, dan UpdateTrace .
Catatan
Header evntrace.h mendefinisikan ControlTrace sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | evntrace.h |
| Pustaka | Sechost.lib pada Windows 8.1 dan Windows Server 2012 R2; Advapi32.lib pada Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista dan Windows XP |
| DLL | Sechost.dll pada Windows 8.1 dan Windows Server 2012; Advapi32.dll pada Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, dan Windows XP |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk