Menulis Manifes Instrumentasi

Aplikasi dan DLL menggunakan manifes instrumentasi untuk mengidentifikasi penyedia instrumentasi mereka dan peristiwa yang ditulis penyedia. Manifes adalah file XML yang berisi elemen yang mengidentifikasi penyedia Anda. Konvensinya adalah menggunakan .man sebagai ekstensi untuk manifes Anda. Manifes harus sesuai dengan XSD manifes peristiwa. Untuk detail tentang skema, lihat Skema EventManifest.

Penyedia instrumentasi adalah aplikasi atau DLL apa pun yang memanggil fungsi EventWriteEx, EventWriteString, atau EventWriteTransfer untuk menulis peristiwa ke sesi pelacakan Event Tracing (ETW) atau saluran Log Peristiwa. Aplikasi dapat menentukan satu penyedia instrumentasi yang mencakup semua peristiwa yang ditulisnya atau dapat menentukan penyedia untuk aplikasi dan penyedia untuk setiap DLL-nya. Jumlah penyedia yang ditentukan aplikasi dalam manifes hanya bergantung pada bagaimana aplikasi ingin mengatur peristiwa yang ditulisnya.

Keuntungan menentukan penyedia untuk setiap DLL adalah Anda kemudian dapat mengaktifkan dan menonaktifkan masing-masing penyedia dan dengan demikian peristiwa yang mereka hasilkan. Keuntungan ini hanya berlaku jika penyedia diaktifkan oleh sesi pelacakan ETW. Setiap peristiwa yang menentukan saluran log peristiwa selalu ditulis ke saluran tersebut.

Manifes harus mengidentifikasi penyedia dan peristiwa yang ditulisnya tetapi metadata lain seperti saluran, tingkat, dan kata kunci bersifat opsional; apakah Anda menentukan metadata opsional tergantung pada siapa yang akan mengonsumsi peristiwa. Misalnya, jika administrator atau personel dukungan menggunakan peristiwa menggunakan alat seperti Pemantau Peristiwa Windows yang membaca peristiwa dari saluran log peristiwa, maka Anda harus menentukan saluran tempat peristiwa ditulis. Namun, jika penyedia hanya akan diaktifkan oleh sesi pelacakan ETW, maka Anda tidak perlu menentukan saluran.

Meskipun tingkat, tugas, opcode, dan metadata kata kunci bersifat opsional, Anda harus menggunakannya untuk mengelompokkan atau mengarsim peristiwa secara logis. Mengelompokkan peristiwa membantu konsumen hanya mengonsumsi peristiwa yang menarik. Misalnya, konsumen dapat meminta semua peristiwa di mana tingkat "penting" dan kata kunci adalah "tulis", atau kueri untuk semua peristiwa yang ditulis oleh tugas tertentu.

Selain konsumen yang menggunakan tingkat dan kata kunci untuk menggunakan jenis peristiwa tertentu, sesi pelacakan ETW dapat menggunakan metadata tingkat dan kata kunci untuk memberi tahu ETW untuk membatasi peristiwa yang ditulis ke log pelacakan peristiwa. Misalnya, sesi dapat membatasi peristiwa hanya ke peristiwa di mana tingkat adalah "kesalahan" atau "kritis" dan kata kunci adalah "baca".

Penyedia dapat menentukan filter yang digunakan sesi untuk memfilter peristiwa berdasarkan data peristiwa. Dengan tingkat dan kata kunci, ETW menentukan apakah peristiwa ditulis ke log tetapi dengan filter, penyedia menggunakan kriteria data filter untuk menentukan apakah kejadian tersebut ditulis ke sesi tersebut. Filter hanya berlaku ketika sesi pelacakan ETW memungkinkan penyedia Anda.

Bagian berikut menunjukkan cara menentukan komponen manifes:

• Mengidentifikasi penyedia
• Menentukan saluran tempat peristiwa ditulis
• Menentukan tingkat keparahan peristiwa yang ditulis penyedia
• Menentukan tugas dan operasi yang dilakukan penyedia Anda
• Menentukan kata kunci yang mengklasifikasikan peristiwa yang ditulis penyedia
• Menentukan filter yang digunakan penyedia untuk memfilter peristiwa yang ditulisnya
• Menentukan peta nama/nilai yang direferensikan data templat Anda
• Menentukan templat yang menentukan data khusus peristiwa
• Menentukan peristiwa yang ditulis penyedia

Meskipun Anda dapat menulis manifes instrumentasi secara manual, Anda harus mempertimbangkan untuk menggunakan alat ECManGen.exe yang disertakan dalam folder \Bin dari Windows SDK. Alat ECManGen.exe menggunakan GUI yang memandu Anda membuat manifes dari awal tanpa harus menggunakan tag XML. Memiliki pengetahuan tentang informasi di bagian ini dan di bagian EventManifest Schema akan membantu saat menggunakan alat ini.

Jika Anda menggunakan Visual Studio sebagai editor XML, Anda dapat menambahkan skema EventManifest ke proyek (lihat menu XML) untuk memanfaatkan Intellisense, validasi skema sebaris, dan fitur lain untuk membuat penulisan manifes menjadi mudah dan akurat.

Setelah menulis manifes Anda, gunakan pengkompilasi pesan untuk memvalidasi manifes dan menghasilkan file sumber daya dan header yang Anda sertakan dalam penyedia Anda. Untuk informasi selengkapnya, lihat Mengkompilasi Manifes Instrumentasi.

Contoh berikut menunjukkan kerangka manifes peristiwa yang sepenuhnya ditentukan.

<instrumentationManifest
    xmlns="http://schemas.microsoft.com/win/2004/08/events" 
    xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    >

    <instrumentation>
        <events>
            <provider ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>