Bagikan melalui

Makro TraceLoggingChannel (traceloggingprovider.h)

  • Artikel

Makro pembungkus TraceLogging yang mengatur saluran untuk peristiwa tersebut.

Sebagian besar peristiwa TraceLogging tidak perlu mengubah saluran default peristiwa dan tidak boleh menggunakan TraceLoggingChannel.

Sintaks

void TraceLoggingChannel(
  [in]  eventChannel
);

Parameter

[in] eventChannel

Saluran tempat peristiwa harus dicatat. Ini adalah nilai bilangan bulat dari 0 hingga 255.

Lihat EVENT_DESCRIPTOR untuk detail tentang saluran acara.

Mengembalikan nilai

Tidak ada

Keterangan

TraceLoggingChannel(eventChannel) dapat digunakan sebagai parameter untuk pemanggilan makro TraceLoggingWrite . Sebagian besar peristiwa TraceLogging tidak perlu mengubah saluran default peristiwa dan tidak boleh menggunakan TraceLoggingChannel.

Parameter eventChannel harus berupa konstanta waktu kompilasi 0 hingga 255. Jika tidak ada TraceLoggingChannel(n) arg yang disediakan, saluran default adalah 11 (WINEVENT_CHANNEL_TRACELOGGING), menunjukkan bahwa ini adalah peristiwa TraceLogging normal. Jika beberapa TraceLoggingChannel(n) arg disediakan, nilai dari parameter terakhir TraceLoggingChannel(n) akan digunakan.

Saluran digunakan dalam skenario Pelacakan Peristiwa tingkat lanjut untuk Windows (ETW). Ini termasuk menulis ke konsumen peristiwa yang ditentukan sistem seperti Log Peristiwa Windows.

Peringatan

Jika penyedia Anda akan berjalan pada Windows yang lebih lama dari Windows 10, jangan gunakan TraceLoggingChannel. Agar peristiwa dikenali sebagai kompatibel dengan TraceLogging oleh dekode peristiwa, saluran harus diatur ke nilai default (11) atau harus ditandai sebagai peristiwa TraceLogging oleh runtime ETW selama EventWrite. Penandaan peristiwa ini diaktifkan dengan memanggil EventSetInformation untuk mengonfigurasi penyedia sebagai penyedia TraceLogging. EventSetInformation di Windows 10 atau yang lebih baru memungkinkan dukungan untuk peristiwa TraceLogging terlepas dari saluran, tetapi versi Windows yang lebih lama memerlukan pembaruan Windows sebelum mendukung penandaan peristiwa TraceLogging. Untuk peristiwa yang diambil pada sistem tanpa EventSetInformation yang diperbarui, saluran 11 adalah satu-satunya cara untuk mengenali peristiwa TraceLogging, sehingga peristiwa dengan saluran lain mungkin tidak didekode dengan benar.

TraceLogging dan Log Peristiwa

Dalam kebanyakan kasus, pengembang menggunakan ETW berbasis manifes untuk peristiwa yang perlu direkam oleh Log Peristiwa. Log Peristiwa terutama dimaksudkan untuk mengumpulkan peristiwa volume rendah yang kemungkinan berguna bagi administrator sistem. ETW berbasis manifes berfungsi dengan baik untuk ini karena mendukung peristiwa yang dikumpulkan dengan cermat (semua peristiwa untuk komponen dijelaskan dalam satu file manifes) dan karena mendukung string pesan yang dapat dilokalkan yang dapat membantu administrator mengetahui cara bereaksi terhadap peristiwa tersebut.

Meskipun peristiwa TraceLogging tidak memiliki string pesan dan umumnya tidak dikumpulkan secara terpusat, TraceLogging masih dapat sesuai untuk beberapa skenario Log Peristiwa. Misalnya, sementara peristiwa yang masuk ke Log Windows (Aplikasi, Keamanan, Penyiapan, dan Sistem) harus selalu memiliki string pesan yang dilokalkan dan harus selalu berguna bagi administrator sistem, peristiwa yang dicatat dalam Log Aplikasi dan Layanan dapat lebih teknis dan dapat merekam informasi diagnostik. Saat menulis ke Log Aplikasi dan Layanan, Anda mungkin ingin menggunakan TraceLogging untuk menyederhanakan manajemen peristiwa yang dicatat.

Menggunakan peristiwa TraceLogging dengan Log Peristiwa Windows mirip dengan menggunakan peristiwa berbasis manifes normal dengan Log Peristiwa. Anda masih perlu membuat dan mendaftarkan manifes untuk menentukan penyedia dan saluran tetapi Anda tidak perlu menentukan peristiwa individual dalam manifes:

  • Tulis manifes ETW yang menentukan penyedia Anda dan saluran Log Peristiwa. Penyedia dalam manifes harus menggunakan nama penyedia dan panduan penyedia (ID penyedia) yang sama seperti yang Anda gunakan di makro TRACELOGGING_DEFINE_PROVIDER Anda. Manifes tidak perlu menyertakan <event> definisi atau <template> karena peristiwa TraceLogging dijelaskan sendiri.
  • Dalam proses build untuk komponen Anda, gunakan Pengkompilasi Pesan (MC.exe) dari Windows SDK 10.0.22621 atau yang lebih baru untuk mengkompilasi manifes. Ini akan menghasilkan file berikut:
    • ManifestName.h: Header C/C++ yang berisi definisi konstanta. Ini akan menentukan ChannelSymbol dan konstanta ChannelSymbol_KEYWORD yang perlu Anda gunakan dalam peristiwa TraceLogging Anda. (Nama konstanta yang sebenarnya akan berbeda untuk setiap saluran.)
    • ManifestName.rc: Skrip Pengkompilasi Sumber Daya (RC.exe) yang menambahkan data BIN manifes ke file biner (EXE, DLL, atau SYS). Anda harus menyertakan skrip sumber daya ini ke dalam sumber daya salah satu file biner di komponen Anda.
    • ManifestNameTEMP.BIN, MSG00001.bin: data BIN manifes yang dirujuk oleh ManifestName.rc.
  • #include file yang dihasilkan ManifestName.h ke dalam kode yang perlu menghasilkan peristiwa TraceLogging. Ini akan menentukan konstanta ChannelSymbol dan ChannelSymbol_KEYWORD .
    • Jika Anda menentukan atribut simbol pada <channel> definisi atau <importChannel> dalam manifes, nama ChannelSymbol akan menjadi nilai atribut simbol Anda. Jika tidak, ChannelSymbol akan ProviderSymbol_CHANNEL_ChannelName (yaitu akan menggunakan simbol dari elemen Anda <provider> dan nama dari elemen atau <importChannel> Anda<channel>).
    • Nama ChannelSymbol_KEYWORD adalah nama ChannelSymbol diikuti oleh _KEYWORD.
    • Konstanta ChannelSymbol_KEYWORD hanya dihasilkan oleh MC.exe 10.0.22621 atau yang lebih baru.
  • Setiap peristiwa TraceLogging yang akan masuk ke Log Peristiwa harus digunakanTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD) untuk mengatur saluran dan kata kunci untuk peristiwa tersebut. Misalnya, jika simbol saluran saya adalah MY_CHANNEL, saya akan menambahkan TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) sebagai parameter ke TraceLoggingWrite makro untuk peristiwa tersebut.
  • Agar Log Peristiwa mengenali penyedia Anda, informasi dari manifes Anda harus disertakan dalam sumber daya modul (file DLL, EXE, atau SYS) yang akan diinstal pada sistem target.
  • Agar Log Peristiwa menerima peristiwa dari penyedia Anda, Anda harus mendaftarkan manifes Anda pada sistem target menggunakan wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll selama penginstalan komponen. Anda juga harus membatalkan pendaftaran manifes Anda menggunakan wevtutil um ManifestFile.man selama penghapusan instalasi komponen.

Penting

Jika penyedia Anda terdaftar di Log Peristiwa, semua peristiwa yang dihasilkan oleh penyedia Anda harus memiliki kata kunci non-nol yang ditentukan dengan TraceLoggingKeyword, bahkan jika peristiwa tersebut tidak ditujukan untuk Log Peristiwa. Peristiwa dengan kata kunci 0 tidak dapat difilter secara efisien dan akan dikirimkan ke Log Peristiwa hanya untuk dibuang. Jika Log Peristiwa mendengarkan peristiwa apa pun dari penyedia Anda, peristiwa apa pun dengan Kata Kunci 0 tidak perlu meningkatkan overhead Log Peristiwa.

Contoh peristiwa TraceLogging untuk Log Peristiwa:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

Kata kunci tambahan yang ditentukan pengguna dapat ditambahkan ke peristiwa jika sesuai, baik dengan menggunakan beberapa argumen TraceLoggingKeyword atau dengan menentukan beberapa kata kunci dalam satu argumen TraceLoggingKeyword , misalnya TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 10 [khusus aplikasi desktop]
Server minimum yang didukung Windows Server 2012 R2
Target Platform Windows
Header traceloggingprovider.h

Lihat juga

EVENT_DESCRIPTOR

TraceLoggingWrite

Makro pembungkus TraceLogging