struktur EVENT_FILTER_DESCRIPTOR (evntprov.h)

Artikel
08/23/2023

Struktur EVENT_FILTER_DESCRIPTOR menentukan data filter yang diteruskan sesi ke fungsi panggilan balik aktifkan penyedia.

Sintaks

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

Anggota

Ptr

Penunjuk ke data filter untuk jenis filter yang ditentukan dalam anggota Jenis .

Jika anggota Jenis diatur ke EVENT_FILTER_TYPE_PID, anggota Ptr menunjuk ke array ID proses (PID).

Jika anggota Jenis diatur ke EVENT_FILTER_TYPE_EVENT_ID, anggota Ptr menunjuk ke struktur EVENT_FILTER_EVENT_ID yang berisi array ID peristiwa dan nilai Boolean yang menentukan apakah pelacakan diaktifkan atau dinonaktifkan untuk ID peristiwa yang ditentukan.

Jika anggota Jenis diatur ke EVENT_FILTER_TYPE_STACKWALK, anggota Ptr menunjuk ke struktur EVENT_FILTER_EVENT_ID yang berisi array ID peristiwa dan nilai Boolean yang menentukan apakah pelacakan tumpukan diaktifkan atau dinonaktifkan untuk ID peristiwa yang ditentukan.

Jika anggota Jenis diatur ke EVENT_FILTER_TYPE_SCHEMATIZED, lihat struktur EVENT_FILTER_HEADER untuk detail tentang membuat filter.

Size

Ukuran data, dalam byte.

Batas ukuran data maksimum bervariasi berdasarkan anggota Jenis yang ditentukan (jenis filter). Ukuran data maksimum, dalam byte, untuk banyak jenis filter terbatas pada MAX_EVENT_FILTER_DATA_SIZE, yang ditentukan dalam file header evntprov.h ke 1024.

Type

Nilai yang ditentukan penyedia yang mengidentifikasi filter. Untuk filter yang ditentukan dalam manifes instrumentasi, atur anggota ini ke EVENT_FILTER_TYPE_SCHEMATIZED.

Nilai yang mungkin untuk anggota ini ditentukan dalam file header evntprov.h .

EVENT_FILTER_TYPE_NONE (0x00000000)

Tidak ada filter.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

Filter skema.

Ini adalah penyiapan pemfilteran tradisional yang juga disebut pemfilteran sisi penyedia. Pengontrol mendefinisikan sekumpulan filter kustom sebagai objek biner yang diteruskan ke penyedia dalam panggilan EnableTrace, EnableTraceEx, atau EnableTraceEx2 . Ini tidak sesuai pada pengontrol dan penyedia untuk menentukan dan menginterpretasikan filter ini dan pengontrol hanya boleh mencatat peristiwa yang berlaku. Ini memerlukan koupling dekat pengontrol dan penyedia karena jenis dan format objek biner dari apa yang dapat difilter tidak ditentukan. Fungsi TdhEnumerateProviderFilters dapat digunakan untuk mengambil filter yang ditentukan dalam manifes.

Untuk informasi selengkapnya tentang filter skema, lihat Menentukan Filter.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

Dicadangkan untuk penggunaan internal.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

Digunakan untuk mengambil rundown sesi pelacakan tertentu. Parameter ControlCode yang diteruskan ke fungsi EnableTraceEx harus diatur ke EVENT_CONTROL_CODE_CAPTURE_STATE dan parameter ProviderId harus systemTraceControlGuid. Struktur EVENT_FILTER_DESCRIPTOR harus menunjuk ke satu TRACEHANDLE yang mewakili sesi ETW saat ini. Rundown akan dilakukan untuk sesi tertentu.
EVENT_FILTER_TYPE_PID (0x80000004)

ID proses. Ini adalah salah satu filter cakupan.

Memfilter peristiwa ETW berdasarkan ID proses akan menghasilkan aliran peristiwa (file atau real-time) yang berisi peristiwa dari penyedia hanya dalam proses yang ditentukan. Ini hanya akan memungkinkan penyedia dalam proses yang PID-nya disediakan. Daftar PID adalah PID dari proses yang berjalan pada saat EnableTraceEx2 dipanggil dan akan mengaktifkan penyedia di semua proses (yang PID-nya disediakan) pada waktu tertentu. Daftar PID tidak akan disimpan dalam sesi. Jadi ketika proses dihentikan dan kemudian muncul kembali, penyedia di dalamnya tidak akan diaktifkan secara otomatis ke sesi pelacakan. Blob filter berbasis PID hanya berlaku untuk sesi pencatat mode kernel karena sesi pencatat privat berjalan di dalam proses mode pengguna.

Jumlah maksimum ID proses yang dapat difilter dibatasi oleh MAX_EVENT_FILTER_PID_COUNT ditentukan dalam file header evntprov.h menjadi 8.

Jika filter ID proses disediakan, maka penyedia hanya akan diaktifkan dalam proses mode pengguna. Jika penyedia yang sama didaftarkan oleh driver mode kernel, penyedia tidak akan diaktifkan.

Ini digunakan dengan EVENT_TRACE_PROPERTIES_V2 untuk pencatat privat luas sistem.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

Nama file yang dapat dieksekusi. Ini adalah salah satu filter cakupan.

Ini digunakan dengan EVENT_TRACE_PROPERTIES_V2 untuk pencatat privat luas sistem.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

ID paket. Ini adalah salah satu filter cakupan

Ini dapat digunakan untuk memfilter penyedia ke peristiwa yang dipancarkan dari paket aplikasi Windows Store tertentu.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

ID aplikasi relatif paket (PRAID). Ini adalah salah satu filter cakupan

Ini dapat digunakan untuk memfilter penyedia ke peristiwa yang dipancarkan dari paket aplikasi Windows Store tertentu.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

Payload peristiwa (konten peristiwa).

Ukuran data maksimum, dalam byte, untuk filter payload peristiwa terbatas pada MAX_EVENT_FILTER_PAYLOAD_SIZE yang ditentukan dalam file header evntprov.h ke 4096.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

ID kejadian.

Fitur ini memungkinkan pengaktifan atau penonaktifan pemfilteran untuk daftar peristiwa. Filter yang disediakan mencakup struktur EVENT_FILTER_EVENT_ID yang berisi array ID peristiwa dan nilai Boolean yang menunjukkan apakah akan mengaktifkan atau menonaktifkan dari pemfilteran untuk peristiwa yang ditentukan. Setiap panggilan tulis peristiwa akan melalui array ini dengan cepat untuk mengetahui apakah mengaktifkan atau menonaktifkan pengelogan peristiwa.

Ketika diterapkan ke penyedia TraceLogging, filter ini akan diabaikan karena peristiwa TraceLogging tidak memiliki ID peristiwa statis.

Jumlah maksimum ID peristiwa yang diizinkan dalam struktur EVENT_FILTER_EVENT_ID dibatasi oleh MAX_EVENT_FILTER_EVENT_ID_COUNT ditentukan dalam file header evntprov.h menjadi 64.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

Nama peristiwa TraceLogging.

Fitur ini memungkinkan pengaktifan atau penonaktifan peristiwa TraceLogging berdasarkan namanya. Filter yang disediakan mencakup struktur EVENT_FILTER_EVENT_NAME yang berisi array nama peristiwa, bitmask kata kunci, dan tingkat untuk difilter, dan nilai Boolean yang menunjukkan apakah akan mengaktifkan atau menonaktifkan peristiwa yang dijelaskan. Saat diterapkan ke penyedia non-TraceLogging, filter ini diabaikan karena peristiwa tersebut tidak memiliki nama yang ditentukan dalam payload mereka.

Catatan: Tersedia di Windows 10, versi 1709 dan yang lebih baru.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

Jalan setumpuk.

Ketika stack walking diaktifkan untuk penyedia, tumpukan diambil untuk semua peristiwa yang dihasilkan oleh penyedia. Sebagian besar waktu, pengguna hanya tertarik pada tumpukan hanya dari sejumlah peristiwa tertentu.

Fitur ini memungkinkan pengaktifan atau penonaktifan tumpukan berjalan pada daftar peristiwa. Filter yang disediakan mencakup struktur EVENT_FILTER_EVENT_ID yang berisi array ID peristiwa dan nilai Boolean yang menunjukkan apakah akan mengaktifkan atau menonaktifkan pengambilan tumpukan untuk peristiwa yang ditentukan. Setiap panggilan tulis peristiwa akan melalui array ini dengan cepat untuk mengetahui apakah tumpukan harus ditangkap atau tidak.

Saat diterapkan ke penyedia TraceLogging, filter ini akan diabaikan karena peristiwa TraceLogging tidak memiliki ID peristiwa statis.

Jika Anda memilih untuk menggunakan filter ini, Anda masih harus menentukan EVENT_ENABLE_PROPERTY_STACK_TRACE dalam struktur ENABLE_TRACE_PARAMETERS saat mengaktifkan penyedia untuk tumpukan apa pun yang akan dikumpulkan dari penyedia.

Jumlah maksimum ID peristiwa yang diizinkan dalam struktur EVENT_FILTER_EVENT_ID dibatasi oleh MAX_EVENT_FILTER_EVENT_ID_COUNT ditentukan dalam file header evntprov.h menjadi 64.

Catatan: Tersedia di Windows 10, versi 1709 dan yang lebih baru.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

Nama peristiwa TraceLogging.

Fitur ini memungkinkan pemfilteran koleksi tumpukan untuk peristiwa TraceLogging berdasarkan nama peristiwa. Filter yang disediakan mencakup struktur EVENT_FILTER_EVENT_NAME yang berisi array nama peristiwa, bitmask kata kunci, dan tingkat untuk difilter, dan nilai Boolean yang menunjukkan apakah akan mengumpulkan tumpukan atau tidak untuk peristiwa yang dijelaskan.

Saat diterapkan ke penyedia non-TraceLogging, filter ini diabaikan karena peristiwa tersebut tidak memiliki nama yang ditentukan dalam payload mereka.

Jika Anda memilih untuk menggunakan filter ini, Anda masih harus menentukan EVENT_ENABLE_PROPERTY_STACK_TRACE pada struktur ENABLE_TRACE_PARAMETERS saat mengaktifkan penyedia untuk tumpukan apa pun yang akan dikumpulkan dari penyedia sama sekali.

Catatan: Tersedia di Windows 10, versi 1709 dan yang lebih baru.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

Tingkat peristiwa dan kata kunci.

Fitur ini memungkinkan pemfilteran koleksi tumpukan untuk peristiwa berdasarkan tingkat dan kata kuncinya. Filter yang disediakan mencakup struktur EVENT_FILTER_LEVEL_KW yang berisi bitmask kata kunci dan tingkat untuk difilter, serta nilai Boolean yang menunjukkan apakah akan mengumpulkan tumpukan atau tidak untuk peristiwa yang dijelaskan.

Jika Anda memilih untuk menggunakan filter ini, Anda masih harus menentukan EVENT_ENABLE_PROPERTY_STACK_TRACE pada struktur ENABLE_TRACE_PARAMETERS saat mengaktifkan penyedia untuk tumpukan apa pun yang akan dikumpulkan dari penyedia sama sekali.

Catatan: Tersedia di Windows 10, versi 1709 dan yang lebih baru.

Keterangan

Penyedia menentukan tata letak data dan tujuannya.

Pada Windows 8.1,Windows Server 2012 R2, dan yang lebih baru, payload peristiwa, cakupan, dan filter stack walk dapat digunakan oleh fungsi EnableTraceEx2 dan struktur ENABLE_TRACE_PARAMETERS dan EVENT_FILTER_DESCRIPTOR untuk memfilter kondisi tertentu dalam sesi pencatat. Untuk informasi selengkapnya tentang filter payload peristiwa, lihat fungsi EnableTraceEx2, TdhCreatePayloadFilter, dan TdhAggregatePayloadFilters serta struktur ENABLE_TRACE_PARAMETERS dan PAYLOAD_FILTER_PREDICATE .

Persyaratan


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