Menentukan Kata Kunci yang Digunakan untuk Mengklasifikasikan Jenis Peristiwa

Kata kunci ETW adalah bitmask 64-bit yang digunakan untuk menunjukkan keanggotaan peristiwa dalam serangkaian kategori peristiwa. Setiap bit dalam kata kunci sesuai dengan kategori. Jika kata kunci peristiwa memiliki sedikit yang ditetapkan, maka peristiwa tersebut termasuk dalam kategori peristiwa yang sesuai dengan bit tersebut.

48 bit rendah kata kunci (bitmask 0x0000FFFFFFFFFFFF) didefinisikan oleh penyedia peristiwa (penulis manifes). 16 bit teratas kata kunci (bitmask 0xFFFF000000000000) ditentukan oleh Microsoft. Lihat winmeta.h atau winmeta.xml di folder Windows Kits sertakan untuk definisi kata kunci yang ditentukan Microsoft.

Penyedia menggunakan kata kunci untuk mengklasifikasikan berbagai jenis peristiwa. Misalnya, Anda dapat menentukan kata kunci bit 0 (nilai 0x1kata kunci ) sebagai kategori baca lalu menerapkan kata kunci baca ke peristiwa apa pun yang melakukan operasi baca seperti membaca dari file atau registri. Konsumen kemudian dapat menggunakan nilai bit kata kunci untuk memfilter klasifikasi peristiwa yang berbeda. Misalnya, konsumen dapat mengatur properti MatchAnyKeyword sesi koleksi peristiwa untuk 0x1 membuat sesi hanya mengumpulkan peristiwa dalam kategori baca .

Sesi pengumpulan peristiwa ETW dapat menggunakan kata kunci (dengan cara yang sama seperti menggunakan tingkat) untuk membatasi peristiwa yang ditulis layanan ETW ke file log pelacakan peristiwanya. Sesi pelacakan dapat mengaktifkan penyedia menggunakan dua set bitmasks kata kunci: bitmask "MatchAnyKeyword" tempat peristiwa ditulis jika salah satu bit kata kunci peristiwa cocok dengan salah satu bit yang diatur dalam masker ini, dan bitmask "MatchAllKeyword" di mana untuk peristiwa yang cocok dengan kasus "MatchAnyKeyword", peristiwa ditulis hanya jika semua bit dalam masker "MatchAllKeyword" ada di kata kunci bitmask peristiwa.

Misalnya, jika penyedia menentukan peristiwa yang menentukan kata kunci baca (bit 0 = 0x1) dan kata kunci akses lokal (bit 1 = 0x2), dan peristiwa kedua yang menentukan kata kunci baca (bit 0 = 0x1) dan kata kunci akses jarak jauh (bit 2 = 0x4), Anda dapat mengatur bitmask "MatchAnyKeyword" sesi koleksi peristiwa ke 0x1 (baca) dan bitmask "MatchAllKeyword" ke 0x0 (tidak ada) untuk menerima semua peristiwa baca, atau Anda dapat mengatur bitmask "MatchAnyKeyword" ke 0x1 dan bitmask "MatchAllKeyword" ke 0x3 (baca + lokal) untuk hanya menerima bacaan lokal.

Untuk menentukan kata kunci untuk penyedia Anda, gunakan elemen kata kunci . Setelah kata kunci ditentukan untuk penyedia, Anda dapat menetapkan kata kunci ke salah satu peristiwa penyedia menggunakan atribut kata kunci elemen peristiwa .

Anda harus menentukan atribut nama dan mask kata kunci. Masker harus berupa bilangan bulat dengan satu set bit, antara bit 0 dan bit 47, seperti mask="256" atau mask="0x100" untuk mengatur kata kunci bit 8. Bit 48 hingga 63 ditentukan oleh Microsoft (lihat winmeta.h atau winmeta.xml) dan tidak dapat digunakan dalam elemen kata kunci .

Atribut simbol dan pesan bersifat opsional.

Contoh berikut menunjukkan cara menentukan kata kunci.

<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 name="Microsoft-Windows-SampleProvider"
                guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
                symbol="PROVIDER_GUID"
                resourceFileName="<path to the exe or dll that contains the metadata resources>"
                messageFileName="<path to the exe or dll that contains the string resources>"
                message="$(string.Provider.Name)">

                . . .

                <keywords>
                    <keyword name="Read" mask="0x1" symbol="READ_KEYWORD"/>
                    <keyword name="Write" mask="0x2" symbol="WRITE_KEYWORD"/>
                    <keyword name="Local" mask="0x4" symbol="LOCAL_KEYWORD"/>
                    <keyword name="Remote" mask="0x8" symbol="REMOTE_KEYWORD"/>
                </keywords>

                . . .

            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Sample Provider"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>