Определение ключевых слов, используемых для классификации типов событий

Ключевое слово ETW — это 64-разрядная маска, используемая для указания членства события в наборе категорий событий. Каждый бит в ключевом слове соответствует категории. Если ключевое слово события имеет битовое значение, событие относится к категории событий, соответствующей этому биту.

Низкие 48 бит ключевого слова (битовая маска 0x0000FFFFFFFFFFFF) определяются поставщиком событий (автор манифеста). Основные 16 бит ключевого слова (битовая маска 0xFFFF000000000000) определяются корпорацией Майкрософт. Дополнительные сведения об определениях ключевых слов, определенных корпорацией Майкрософт, см. в winmeta.h или winmeta.xml в папке include комплектов Windows.

Поставщики используют ключевые слова для классификации различных типов событий. Например, можно определить бит 0 ключевого слова (значение ключевого слова 0x1) в качестве категории чтения, а затем применить ключевое слово чтения к любому событию, которое выполняет операцию чтения, например чтение из файла или реестра. Затем потребители могут использовать битовые значения ключевых слов для фильтрации для различных классификаций событий. Например, потребитель может задать свойству MatchAnyKeyword сеанса сбора событий значение 0x1, чтобы сеанс собирал только события в категории чтения.

Сеанс сбора событий ETW может использовать ключевые слова (таким же образом, как и уровень), чтобы ограничить события, которые служба ETW записывает в файл журнала трассировки событий. Сеанс трассировки может задействовать поставщика с помощью двух наборов битмасок ключевых слов: битмаска MatchAnyKeyword, в которой событие записывается, если любой из битов ключевых слов события соответствует любому из битов, заданных в этой маске, и битмаска MatchAllKeyword, где для тех событий, которые соответствовали случаю MatchAnyKeyword, событие записывается только в том случае, если все биты в маске MatchAllKeyword присутствуют в битовой маске ключевых слов события.

Например, если поставщик определяет событие, указывающее ключевое слово чтения (бит 0 = 0x1) и ключевое слово локального доступа (бит 1 = 0x2), и второе событие, указывающее ключевое слово чтения (бит 0 = 0x1) и ключевое слово удаленного доступа (бит 2 = 0x4), можно задать битовую маску MatchAnyKeyword сеанса коллекции событий на 0x1 (для чтения) и битовую маску MatchAllKeyword на 0x0 (ничего), чтобы получать все события чтения, или можно задать битовую маску MatchAnyKeyword на 0x1 и MatchAllKeyword на 0x3 (чтение + локальное), чтобы получать только локальные операции чтения.

Чтобы определить ключевое слово для поставщика, используйте элемент ключевого слова. После определения ключевого слова для поставщика, вы можете назначить это ключевое слово любому из событий поставщика, используя атрибут ключевых слов элемента события .

Необходимо указать имя ключевого слова и атрибуты маски. Маска должна быть целым числом с одним битом, от 0 до 47 бита, например mask="256" или mask="0x100", чтобы задать ключевое слово бит 8. Биты 48–63 определяются корпорацией Майкрософт (см. winmeta.h или winmeta.xml) и не могут использоваться в элементе ключевого слова.

Атрибуты символа и сообщения являются необязательными.

В следующем примере показано, как определить ключевое слово.

<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>