struktur EVENT_DESCRIPTOR (evntprov.h)

Artikel
03/11/2023

Struktur EVENT_DESCRIPTOR berisi informasi (metadata) tentang peristiwa ETW.

Sintaks

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

Anggota

Id

Angka 16-bit yang digunakan untuk mengidentifikasi peristiwa berbasis manifes.

Untuk ETW berbasis manifes, kombinasi Provider.DecodeGuid + Event.Id + Event.Version harus secara unik mengidentifikasi peristiwa, yaitu semua peristiwa dengan DecodeGuid, Id, dan Versi yang sama harus memiliki kumpulan bidang yang sama tanpa perubahan nama bidang, jenis bidang, atau urutan bidang.

Untuk ETW bebas manifes (yaitu TraceLogging), bidang Id biasanya tidak bermakna dan biasanya akan diatur ke 0. Peristiwa TraceLogging umumnya diidentifikasi dengan nama peristiwanya, bukan ID peristiwa.

Version

Angka 8-bit yang digunakan untuk menentukan versi peristiwa berbasis manifes.

Versi menunjukkan revisi terhadap definisi peristiwa dengan Id tertentu. Semua peristiwa dengan Id tertentu harus memiliki semantik serupa, tetapi perubahan versi dapat digunakan untuk menunjukkan modifikasi kecil dari detail peristiwa, misalnya perubahan pada jenis bidang atau penambahan bidang baru.

Channel

Nomor 8-bit yang digunakan untuk mengaktifkan pemrosesan peristiwa khusus.

Peristiwa berbasis manifes biasanya menggunakan saluran 0.
Peristiwa berbasis TraceLogging biasanya menggunakan saluran 11.
Peristiwa berbasis manifes dengan sifat penyedia biasanya menggunakan saluran 12.
Nilai saluran lain dapat digunakan dengan peristiwa Log Peristiwa.

Nilai saluran di bawah 16 disediakan untuk digunakan oleh Microsoft untuk mengaktifkan perlakuan khusus oleh runtime ETW. Nilai saluran 16 ke atas akan diabaikan oleh runtime ETW (diperlakukan sama dengan saluran 0) dan dapat diberikan semantik yang ditentukan pengguna.

Level

Angka 8-bit yang digunakan untuk menjelaskan tingkat keparahan atau kepentingan peristiwa.

Penting

Tingkat peristiwa adalah sarana utama untuk memfilter peristiwa. Selalu tetapkan tingkat yang bermakna (bukan nol) untuk setiap peristiwa.

Nilai tingkat 0 hingga 5 ditentukan oleh Microsoft (lihat evntrace.h dan winmeta.h). Nilai tingkat 6 hingga 15 dicadangkan. Nilai tingkat 16 hingga 255 dapat ditentukan oleh penyedia peristiwa.

Nilai	Semantik
LOG_ALWAYS (0)	Peristiwa melewati pemfilteran peristiwa berbasis tingkat. Peristiwa tidak boleh menggunakan tingkat ini.
KRITIS (1)	Kesalahan kritis
KESALAHAN (2)	Kesalahan
PERINGATAN (3)	Peringatan
INFO (4)	Informasi
VERBOSE (5)	Verbose

Sesi pengumpulan peristiwa dapat mengatur filter tingkat, yang berarti bahwa sesi hanya akan menerima peristiwa di mana eventDescriptor.Level <= session.LevelFilter. Perhatikan bahwa peristiwa dengan tingkat 0 akan melewati pemfilteran berbasis tingkat.

Opcode

Angka 8-bit yang digunakan untuk menandai peristiwa dengan semantik khusus. Nilai ini dapat digunakan oleh dekoder pelacakan untuk mengatur dan menghubungkan peristiwa. Nilai opcode yang diakui secara global didefinisikan dalam winmeta.h. Sebagian besar peristiwa menggunakan INFO (0). Nilai Opcode 10 hingga 239 dapat diberikan semantik yang ditentukan pengguna.

Opcodes START (1) dan STOP (2) digunakan untuk menunjukkan awal dan akhir aktivitas ETW sebagai berikut:

Hasilkan ID aktivitas yang unik dalam jejak, biasanya menggunakan EventActivityIdControl.
Tulis peristiwa awal dengan opcode = START, ID aktivitas = ID aktivitas yang dihasilkan, dan ID aktivitas terkait = ID aktivitas induk (jika ada).
Tulis sejumlah peristiwa informasi aktivitas dengan opcode = INFO, ID aktivitas = ID aktivitas yang dihasilkan.
Tulis peristiwa berhenti dengan opcode = STOP, ID aktivitas = ID aktivitas yang dihasilkan.

Alat pendekodean jejak kemudian dapat mengatur peristiwa ini ke dalam grup berdasarkan ID aktivitas mereka.

Task

Angka 16-bit yang digunakan untuk membuat anotasi peristiwa atau grup peristiwa terkait.

Kode tugas peristiwa dapat digunakan untuk tujuan apa pun yang ditentukan oleh penyedia. Kode tugas 0 adalah default, digunakan untuk menunjukkan bahwa tidak ada kode tugas khusus yang ditetapkan ke peristiwa tersebut. Manifes ETW mendukung penetapan string yang dilokalkan ke setiap kode tugas. Kode tugas dapat digunakan untuk mengelompokkan peristiwa ke dalam kategori atau hanya untuk mengaitkan string "tugas" yang dilokalkan dengan setiap peristiwa.

Keyword

Bitmask 64-bit yang digunakan untuk menunjukkan keanggotaan peristiwa dalam serangkaian kategori peristiwa.

Penting

Kata kunci peristiwa adalah sarana utama untuk memfilter peristiwa. Selalu tetapkan kata kunci yang bermakna (bukan nol) untuk setiap peristiwa.

16 bit teratas kata kunci (bitmask 0xFFFF000000000000) ditentukan oleh Microsoft. Kata kunci 48 bit rendah (bitmask 0x0000FFFFFFFFFFFF) ditentukan oleh penyedia peristiwa. Misalnya, penyedia peristiwa mungkin mendefinisikan bit 0 (bitmask 0x1) menjadi kategori "I/O", bit 1 (bitmask 0x2) menjadi kategori "UI", dan bit 2 (bitmask 0x4) menjadi kategori "pengukuran performa". Dalam skenario ini, peristiwa mungkin memiliki kata kuncinya yang diatur ke 0x5, menunjukkan bahwa peristiwa tersebut berada dalam kategori "I/O" dan "pengukuran performa".

Sesi pengumpulan peristiwa dapat mengatur filter MatchAnyKeyword dan MatchAllKeyword, yang berarti bahwa sesi hanya akan menerima peristiwa di mana ekspresi berikut ini benar:

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

Perhatikan bahwa peristiwa dengan kata kunci 0 biasanya akan melewati pemfilteran berbasis kata kunci.

Tip

Dimulai dengan Windows 10 versi 1507 dan yang lebih baru, sesi pengumpulan peristiwa dapat mengecualikan peristiwa yang kata kuncinya diatur ke 0. Untuk melakukan ini, sertakan EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 bendera di EnableProperty bidang struktur ENABLE_TRACE_PARAMETERS yang diteruskan ke EnableTraceEx2 saat mengonfigurasi penyedia.

Keterangan

Struktur ini digunakan saat memanggil EventWrite untuk menulis peristiwa. Anda juga dapat menggunakannya saat memanggil EventEnabled untuk menentukan apakah peristiwa harus dihasilkan (yaitu untuk menentukan apakah ada pendengar peristiwa yang tertarik dengan acara tersebut).

Catatan

Sebagian besar penyedia peristiwa tidak akan menggunakan EVENT_DESCRIPTOR secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWriteEx, dan EventUnregister. Misalnya, Anda dapat menulis manifes peristiwa lalu menggunakan Pengkompilasi Pesan untuk menghasilkan kode C/C++ untuk peristiwa tersebut, atau Anda mungkin menggunakan TraceLogging untuk menghindari kebutuhan manifes. Untuk detail tentang bagaimana anggota struktur ini berhubungan dengan manifes instrumentasi, lihat atribut jenis kompleks EventDefinitionType .

Struktur ini disertakan dalam struktur EVENT_HEADER yang dikembalikan dengan rekaman peristiwa saat Anda menggunakan peristiwa menggunakan ProcessTrace dengan panggilan balik EventRecordCallback .

Catatan

Saat memproses peristiwa berbasis MOF, identitas peristiwa terkandung dalam bidang Opcode , bukan bidang Id .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Header	evntprov.h (termasuk Evntprov.h)