struktur EVENT_TRACE_PROPERTIES (evntrace.h)
Struktur EVENT_TRACE_PROPERTIES berisi informasi tentang sesi pelacakan peristiwa. Anda menggunakan struktur ini dengan API seperti StartTrace dan ControlTrace saat menentukan, memperbarui, atau mengkueri properti sesi.
Catatan
Ini adalah struktur versi-1. Opsi tambahan didukung oleh EVENT_TRACE_PROPERTIES_V2 (misalnya FilterDesc dan V2Options).
Sintaks
typedef struct _EVENT_TRACE_PROPERTIES {
WNODE_HEADER Wnode;
ULONG BufferSize;
ULONG MinimumBuffers;
ULONG MaximumBuffers;
ULONG MaximumFileSize;
ULONG LogFileMode;
ULONG FlushTimer;
ULONG EnableFlags;
union {
LONG AgeLimit;
LONG FlushThreshold;
} DUMMYUNIONNAME;
ULONG NumberOfBuffers;
ULONG FreeBuffers;
ULONG EventsLost;
ULONG BuffersWritten;
ULONG LogBuffersLost;
ULONG RealTimeBuffersLost;
HANDLE LoggerThreadId;
ULONG LogFileNameOffset;
ULONG LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;
Anggota
Wnode
Struktur WNODE_HEADER . Anda harus menentukan anggota BufferSize, Flags, dan Guid . Anda dapat secara opsional menentukan anggota ClientContext .
BufferSize
Kilobyte memori yang dialokasikan untuk setiap buffer sesi pelacakan peristiwa. Ukuran buffer minimum adalah 4 (4KB). Ukuran buffer maksimum adalah 16384 (16MB). Sebagian besar sesi pelacakan harus menggunakan ukuran buffer 64KB atau kurang untuk menghindari membuang-buang memori dan ruang disk. Sebelum Windows 8: Ukuran buffer maksimum adalah 1024 (1MB).
Ukuran buffer yang lebih kecil mengurangi penggunaan memori sesi dan dapat membantu mengurangi ukuran file log. Ukuran buffer yang lebih besar mendukung pengumpulan peristiwa yang lebih besar karena ETW tidak memecah peristiwa di seluruh batas buffer dan karenanya tidak dapat mengumpulkan peristiwa yang lebih besar dari ukuran buffer. Dalam skenario yang melibatkan throughput data yang sangat tinggi, ukuran buffer yang lebih besar juga dapat mengurangi overhead CPU.
- Sesi dengan peristiwa kecil dan tingkat peristiwa rendah (beberapa KB/dtk) harus menggunakan ukuran buffer kecil (4KB hingga 16KB).
- Sesi dengan peristiwa kecil dan tingkat peristiwa sedang harus menggunakan ukuran buffer sedang (16KB hingga 32KB).
- Sesi dengan peristiwa besar atau tingkat peristiwa tinggi (beberapa MB/dtk) harus menggunakan ukuran buffer besar (64KB hingga 128KB).
- Dalam kasus yang jarang terjadi ketika sejumlah besar memori harus dicadangkan untuk jejak diagnostik dengan ratusan megabyte data per detik, ukuran buffer besar (256KB hingga 1024KB) dapat mengurangi overhead CPU.
Catatan
Terlepas dari ukuran buffer, ETW tidak dapat mengumpulkan peristiwa yang lebih besar dari 64KB.
ETW dapat menyesuaikan BufferSize yang diminta ke atas dalam skenario tertentu. Misalnya, saat menulis file pelacakan ke disk, ETW dapat meningkatkan ukuran buffer ke kelipatan ukuran blok fisik disk.
Penting
BufferSize adalah salah satu parameter terpenting untuk sesi pelacakan. Buffer besar biasanya membuang memori dan ruang disk. Sesi pelacakan dengan buffer besar (256KB atau lebih besar) harus digunakan hanya untuk penyelidikan atau pengujian diagnostik, bukan untuk pelacakan produksi.
Tip
Jangan gunakan BufferSize untuk mengontrol penggunaan memori sesi pelacakan. Sebagai gantinya, pilih ukuran buffer berdasarkan ukuran peristiwa dan tingkat peristiwa sesi Anda, lalu gunakan parameter MinimumBuffers dan MaximumBuffers untuk menyesuaikan penggunaan memori sesi.
MinimumBuffers
Jumlah minimum buffer yang disediakan untuk kumpulan buffer sesi pelacakan.
ETW dapat menyesuaikan nilai ini dalam skenario tertentu.
- Jika mode pengelogan
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGmenyertakan bendera, ETW akan memesan setidaknya 2 buffer. - Jika mode pengelogan tidak menyertakan
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGbendera, ETW akan mencadangkan setidaknya 2 buffer untuk setiap prosesor logis. - Jika nilai ini lebih besar dari batas yang ditentukan ETW, ETW dapat menguranginya ke batas untuk menghindari penggunaan memori yang berlebihan.
Untuk mode file dan jejak real-time dengan tingkat peristiwa sedang, sebagian besar pengguna harus meminimalkan penggunaan memori dengan mengatur MinimumBuffers ke 0 atau minimum kecil (misalnya 4 atau 8), memungkinkan ETW untuk menyesuaikan nilai ke atas berdasarkan jumlah prosesor. ETW akan memesan (disesuaikan) jumlah minimum buffer ketika pelacakan dimulai. Jika buffer diisi lebih cepat daripada yang dapat diproses, ETW akan mencoba mengalokasikan buffer tambahan, hingga angka yang ditentukan oleh MaximumBuffers.
Untuk jejak mode buffering (melingkar dalam memori), pengguna harus mengatur parameter MinimumBuffers sesuai dengan jumlah total memori yang Anda inginkan untuk dicadangkan ETW untuk sesi tersebut. Ini biasanya dihitung berdasarkan tingkat peristiwa yang diharapkan dan jumlah waktu yang Anda inginkan untuk menutupi jejak. Misalnya, jika Anda mengharapkan tingkat data 16KB per detik dan Anda ingin jejak Anda merekam setidaknya 60 detik data, Anda akan membutuhkan 960KB. Dengan asumsi ukuran buffer 32KB, Anda akan mengatur MinimumBuffers ke 30 (total 960KB / 32KB per buffer = 30 buffer). ETW akan memesan (disesuaikan) jumlah minimum buffer ketika pelacakan dimulai. Ketika semua buffer terisi, ETW akan menggunakan kembali buffer terisi tertua untuk peristiwa baru. Perhatikan bahwa ETW tidak akan mengalokasikan buffer tambahan (ETW mengabaikan MaximumBuffers untuk jejak mode buffering).
MaximumBuffers
Jumlah maksimum buffer yang akan dialokasikan untuk kumpulan buffer sesi pelacakan.
ETW dapat menyesuaikan nilai ini dalam skenario tertentu.
- Jika nilai ini kurang dari nilai MinimumBuffers yang disesuaikan, ETW dapat meningkatkannya ke nilai yang sesuai sama dengan atau lebih besar dari MinimumBuffers.
- Jika nilai ini lebih besar dari batas yang ditentukan ETW, ETW dapat menguranginya ke batas.
Sebagian besar pengguna harus mulai menyetel sesi mereka dengan mengatur MinimumBuffers dan MaximumBuffers ke nilai yang sama. Anda kemudian dapat meningkatkan nilai MaximumBuffers jika jejak menghilangkan peristiwa selama puncak laju peristiwa.
ETW tidak dapat mengalokasikan buffer sesuai permintaan jika peristiwa dihasilkan oleh driver yang berjalan pada IRQL tinggi. Jika sesi pelacakan Anda perlu merekam peristiwa dari penyedia mode kernel IRQL tinggi, mungkin perlu menggunakan nilai MinimumBuffers yang lebih tinggi untuk memaksa buffer dialokasikan sebelumnya.
Catatan
ETW mengabaikan MaximumBuffers untuk sesi mode buffering (sesi yang menyertakan mode EVENT_TRACE_BUFFERING_MODEpengelogan ). Sesi mode buffering selalu mengalokasikan MinimumBuffers di awal koleksi jejak dan tidak pernah mengalokasikan buffer tambahan.
MaximumFileSize
Ukuran maksimum file yang digunakan untuk mencatat peristiwa, dalam megabyte, atau nol tanpa batas ukuran. Biasanya, Anda menggunakan anggota ini untuk membatasi ukuran file log melingkar saat Anda mengatur LogFileMode ke EVENT_TRACE_FILE_MODE_CIRCULAR. Anggota ini harus diatur ke nilai bukan nol jika LogFileMode berisi EVENT_TRACE_FILE_MODE_PREALLOCATE, EVENT_TRACE_FILE_MODE_CIRCULAR atau EVENT_TRACE_FILE_MODE_NEWFILE.
Jika Anda menggunakan drive sistem (drive yang berisi sistem operasi) untuk pengelogan, ETW memeriksa ruang disk tambahan sebesar 200MB, terlepas dari apakah Anda menggunakan parameter ukuran file maksimum. Oleh karena itu, jika Anda menentukan 100MB sebagai ukuran file maksimum untuk file pelacakan di drive sistem, Anda harus memiliki ruang kosong 300MB pada drive.
LogFileMode
Bendera pengelogan untuk sesi pelacakan peristiwa. Anda menggunakan anggota ini untuk menentukan apakah Anda ingin peristiwa ditulis ke buffer melingkar dalam memori, file log, atau konsumen real-time. Anda juga dapat menggunakan anggota ini untuk menentukan karakteristik sesi lainnya, misalnya bahwa sesi tersebut adalah sesi pencatat privat. Untuk daftar bendera yang mungkin, lihat Konstanta Mode Pengelogan.
Buffer ETW peristiwa untuk sesi real-time ketika tidak ada konsumen real-time untuk sesi tersebut. Perhatikan bahwa buffering ini terbatas. Jika batas tercapai, peristiwa baru akan diabaikan dan fungsi pengelogan gagal dengan STATUS_LOG_FILE_FULL. Sebelum Windows Vista: Jika tidak ada konsumen real time, peristiwa dibuang dan pengelogan berlanjut.
Jangan memulai sesi pengelogan real-time kecuali konsumen real-time akan menggunakan peristiwa tersebut. Sesi real time tanpa konsumen akan membuang sumber daya sistem (CPU, memori, dan ruang disk untuk buffering peristiwa).
Jika konsumen mulai memproses peristiwa real-time, peristiwa buffer dikonsumsi terlebih dahulu. Setelah semua peristiwa buffer dikonsumsi, sesi akan mulai melaporkan peristiwa baru.
FlushTimer
Seberapa sering, dalam hitungan detik, buffer pelacakan yang tidak kosong dibersihkan. Waktu flush minimum adalah 1 detik.
- Untuk sesi mode file: Mengatur FlushTimer ke 0 akan menonaktifkan flush berbasis waktu (flush akan terjadi ketika buffer diisi, ketika sesi dihentikan, atau ketika sesi secara eksplisit dihapus). Sebagian besar jejak mode file harus mengatur FlushTimer ke 0 untuk menghindari ruang yang terbuang dalam file pelacakan (yaitu agar ruang disk tidak terbuang sia-sia menyimpan buffer yang sebagian besar kosong). Anda mungkin ingin mengatur timer ke nilai non-nol jika ada kemungkinan jejak mungkin tidak ditutup (misalnya jika Anda ingin memastikan untuk mendapatkan peristiwa bahkan jika sistem crash).
- Untuk sesi real-time: Mengatur FlushTimer ke 0 akan mengaktifkan batas waktu default 1 detik. Sesi real time harus mengatur timer flush berdasarkan seberapa cepat data perlu diterima. Perhatikan bahwa nilai timer yang lebih tinggi akan mengurangi overhead CPU untuk pelacakan. Sebagian besar jejak real-time harus dimulai dengan timer 5 atau 10 detik dan menyetel timer berdasarkan kebutuhan.
- Untuk sesi buffered (melingkar dalam memori), FlushTimer tidak digunakan. Data pelacakan hanya akan dibersihkan sesuai permintaan (yaitu dihapus ke file melalui ControlTrace).
EnableFlags
Sesi pencatat sistem dapat mengatur EnableFlags untuk menunjukkan peristiwa SystemTraceProvider mana yang harus disertakan dalam jejak.
Catatan
EnableFlags hanya valid untuk pencatat sistem, yaitu sesi pelacakan yang dimulai menggunakan bendera mode pencatat EVENT_TRACE_SYSTEM_LOGGER_MODE , KERNEL_LOGGER_NAME nama sesi, SystemTraceControlGuid GUID sesi, atau GlobalLoggerGuid GUID sesi.
Anggota ini bisa berisi satu atau beberapa nilai berikut. Selain peristiwa yang Anda tentukan, kecuali Anda menentukan EVENT_TRACE_FLAG_NO_SYSCONFIG, pencatat juga merekam peristiwa konfigurasi perangkat keras pada Windows XP dan peristiwa konfigurasi sistem di Windows Server 2003 atau yang lebih baru.
EVENT_TRACE_FLAG_ALPC (0x00100000)
Mengaktifkan jenis peristiwa ALPC .
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_CSWITCH (0x00000010)
Mengaktifkan jenis peristiwa Utas berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_DBGPRINT (0x00040000)
Memungkinkan panggilan DbgPrint dan DbgPrintEx dikonversi ke peristiwa ETW.
EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)
Mengaktifkan jenis peristiwa FileIo berikut (Anda juga harus mengaktifkan EVENT_TRACE_FLAG_DISK_IO):
EVENT_TRACE_FLAG_DISK_IO (0x00000100)
Mengaktifkan jenis peristiwa DiskIo berikut:
EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)
Mengaktifkan jenis peristiwa DiskIo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_DISPATCHER (0x00000800)
Mengaktifkan jenis peristiwa Utas berikut:
Nilai ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
EVENT_TRACE_FLAG_DPC (0x00000020)
Mengaktifkan jenis peristiwa PerfInfo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_DRIVER (0x00800000)
Mengaktifkan jenis peristiwa DiskIo berikut:
- DriverCompleteRequest
- DriverCompleteRequestReturn
- DriverCompletionRoutine
- DriverMajorFunctionCall
- DriverMajorFunctionReturn
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_FILE_IO (0x02000000)
Mengaktifkan jenis peristiwa FileIo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)
Mengaktifkan jenis peristiwa FileIo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)
Mengaktifkan jenis peristiwa Gambar berikut:
EVENT_TRACE_FLAG_INTERRUPT (0x00000040)
Mengaktifkan jenis peristiwa PerfInfo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_JOB (0x00080000)
Nilai ini didukung pada Windows 10
EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)
Mengaktifkan jenis peristiwa PageFault_V2 berikut:
EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)
Mengaktifkan jenis peristiwa PageFault_V2 berikut:
EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)
EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)
Jangan lakukan rundown konfigurasi sistem.
Nilai ini didukung pada Windows 8, Windows Server 2012, dan yang lebih baru.
EVENT_TRACE_FLAG_PROCESS (0x00000001)
Mengaktifkan jenis peristiwa Proses berikut:
EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)
Mengaktifkan jenis peristiwa Process_V2 berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_PROFILE (0x01000000)
Mengaktifkan jenis peristiwa PerfInfo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_REGISTRY (0x00020000)
Mengaktifkan jenis peristiwa Registri .
EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)
Mengaktifkan jenis peristiwa SplitIo .
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)
Mengaktifkan jenis peristiwa PerfInfo berikut:
Nilai ini didukung pada Windows Vista dan yang lebih baru.
EVENT_TRACE_FLAG_THREAD (0x00000002)
Mengaktifkan jenis peristiwa Utas berikut:
EVENT_TRACE_FLAG_VAMAP (0x00008000)
Mengaktifkan jenis peristiwa peta dan batalkan peta (tidak termasuk file gambar).
Nilai ini didukung pada Windows 8, Windows Server 2012, dan yang lebih baru.
EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)
Mengaktifkan jenis peristiwa PageFault_V2 berikut:
Nilai ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.
DUMMYUNIONNAME
DUMMYUNIONNAME.AgeLimit
Tidak digunakan.
Windows 2000: Penundaan waktu sebelum buffer yang tidak digunakan dikosongkan, dalam hitungan menit. Defaultnya adalah 15 menit.
DUMMYUNIONNAME.FlushThreshold
NumberOfBuffers
Pada output, jumlah buffer yang dialokasikan untuk kumpulan buffer sesi pelacakan peristiwa.
FreeBuffers
Pada output, jumlah buffer yang dialokasikan tetapi tidak digunakan dalam kumpulan buffer sesi pelacakan peristiwa.
EventsLost
Pada output, jumlah peristiwa yang tidak direkam.
BuffersWritten
Pada output, jumlah buffer yang ditulis.
LogBuffersLost
Pada output, jumlah buffer yang tidak dapat ditulis ke file log.
RealTimeBuffersLost
Pada output, jumlah buffer yang tidak dapat dikirimkan secara real-time kepada konsumen.
LoggerThreadId
Pada output, pengidentifikasi utas untuk sesi pelacakan peristiwa.
LogFileNameOffset
Offset (dalam byte) dari awal memori yang dialokasikan struktur ini ke awal string yang dihentikan nul yang berisi nama file log.
Nama file biasanya memiliki .etl ekstensi. Semua folder di jalur harus sudah ada (ETW tidak akan membuat folder untuk Anda). Jalurnya bisa relatif, absolut, lokal, atau jarak jauh. Variabel lingkungan di jalur tidak akan diperluas. Pengguna harus memiliki izin untuk menulis ke folder.
Nama file log dibatasi hingga 1.024 karakter. Jika Anda mengatur LogFileMode ke EVENT_TRACE_PRIVATE_LOGGER_MODE atau EVENT_TRACE_FILE_MODE_NEWFILE, pastikan untuk mencadangkan cukup memori untuk menyertakan pengidentifikasi proses yang akan 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, jika Anda hanya menentukan EVENT_TRACE_REAL_TIME_MODE ), atur LogFileNameOffset ke 0. Jika Anda hanya menentukan pengelogan real time dan juga memberikan offset dengan nama file log yang valid, ETW akan menggunakan nama file log untuk membuat file log berurutan dan mencatat peristiwa ke file log selain mengirim peristiwa ke konsumen real-time. ETW juga membuat file log berurutan jika LogFileMode adalah 0 dan Anda memberikan offset dengan nama file log yang valid.
Jika Anda ingin mencatat peristiwa ke file log, Anda harus mencadangkan cukup memori agar struktur ini menyertakan nama file log dan nama sesi mengikuti struktur. Nama file log harus mengikuti nama sesi dalam memori. Lihat komentar untuk contoh.
File pelacakan dibuat menggunakan deskriptor keamanan default, yang berarti bahwa file log akan memiliki ACL yang sama dengan direktori induk. Jika Anda ingin akses ke file dibatasi, buat direktori induk dengan ACL yang sesuai.
LoggerNameOffset
Offset (dalam byte) dari awal memori struktur yang dialokasikan ke awal string yang dihentikan nul yang berisi nama sesi.
Penting
Gunakan nama deskriptif untuk sesi Anda sehingga kepemilikan dan penggunaan sesi dapat ditentukan dari nama sesi. Jangan gunakan GUID atau nilai non-deskriptif lainnya. Jangan tambahkan digit acak untuk membuat nama sesi Anda unik. Sesi ETW adalah sumber daya terbatas sehingga komponen Anda tidak boleh memulai beberapa sesi. Jika sesi komponen Anda sudah berjalan saat komponen dimulai, komponen Anda harus membersihkan sesi tanpa induk daripada membuat sesi kedua.
Nama sesi dibatasi hingga 1.024 karakter. Nama sesi tidak peka huruf besar/kecil. Sistem tidak akan memulai sesi baru jika sesi lain dengan nama yang sama sudah berjalan.
Windows 2000: Nama sesi peka huruf besar/kecil. Akibatnya, sesi dengan nama yang berbeda hanya jika diizinkan. Namun, untuk mengurangi kebingungan, Anda harus memastikan nama sesi Anda unik.
Keterangan
Ketika Anda mengalokasikan memori untuk struktur ini, Anda harus mengalokasikan cukup memori untuk menyertakan nama sesi dan nama file log mengikuti struktur. Nama sesi harus muncul sebelum nama file log dalam memori. Anda harus menyalin nama file log ke offset tetapi Anda tidak menyalin nama sesi ke offset. Fungsi StartTrace menyalin nama untuk Anda.
Pastikan untuk menginisialisasi memori untuk struktur ini ke nol sebelum mengatur anggota mana pun. Contohnya:
typedef struct EventTracePropertyData {
EVENT_TRACE_PROPERTIES Props;
WCHAR LoggerName[128];
WCHAR LogFileName[1024];
} EventTracePropertyData;
EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);
Peristiwa dari penyedia ditulis ke buffer sesi. Ketika buffer dalam file atau sesi real-time penuh (atau ketika FlushTimer kedaluwarsa), sesi menghapus buffer baik dengan menulis peristiwa ke file log, mengirimkannya ke konsumen real-time, atau keduanya. Jika buffer sesi diisi lebih cepat daripada yang dapat dibersihkan, buffer baru dialokasikan dan ditambahkan ke kumpulan buffer sesi, hingga MaximumBuffers. Di luar batas ini, sesi membuang peristiwa masuk hingga buffer tersedia. Setiap sesi menyimpan catatan jumlah peristiwa yang dibuang (lihat anggota EventsLost ).
Untuk melihat statistik sesi, seperti EventsLost saat sesi berjalan, panggil fungsi ControlTrace dan atur parameter ControlCode ke EVENT_TRACE_CONTROL_QUERY.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Header | evntrace.h |