Поделиться через

Написание манифеста инструментирования

Приложения и библиотеки DLL используют манифест инструментирования для идентификации поставщиков инструментирования и событий, записываемых поставщиками. Манифест — это XML-файл, содержащий элементы, определяющие поставщика. Принято использовать расширение .man для манифестов. Манифест должен соответствовать XSD-схеме манифеста события. Для получения сведений о схеме см. схему EventManifest.

Поставщик инструментирования — это любое приложение или DLL-библиотека, вызывающее функции EventWriteEx, EventWriteStringили EventWriteTransfer для записи событий в сеанс трассировки событий (ETW) или канал журнала событий. Приложение может определить одного источника инструментовки, охватывающего все события, которые оно записывает, или может определить источник для приложения и источник для каждой из его DLL библиотек. Количество поставщиков, определяемых приложением в манифесте, зависит исключительно от того, как приложение хочет упорядочить события, которые он записывает.

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

Манифест должен определить поставщика и события, которые он записывает, но другие метаданные, такие как каналы, уровни и ключевые слова, являются необязательными; Определяете ли вы необязательные метаданные, зависит от того, кто будет использовать события. Например, если администраторы или сотрудники службы поддержки используют события с помощью средства, например средства просмотра событий Windows, который считывает события из каналов журнала событий, необходимо определить каналы, в которые записываются события. Однако если поставщик будет включен только через сеанс трассировки ETW, вам не нужно определять каналы.

Хотя уровни, задачи, опкоды и метаданные ключевых слов являются необязательными, их следует использовать для логического группирования или сегментирования событий. Группирование событий помогает потребителям использовать только те события, которые являются интересующими. Например, потребитель может запрашивать все события, где уровень "критический" и ключевое слово "запись", или запрашивать все события, созданные конкретной задачей.

Помимо того, что потребители используют уровни и ключевые слова для обработки определенных типов событий, сеанс трассировки ETW может использовать метаданные уровня и ключевых слов, чтобы указать ETW ограничить события, записываемые в журнал трассировки событий. Например, сеанс может ограничить события только событиями, в которых уровень "ошибка" или "критически важный" и ключевое слово "read".

Поставщик может определить фильтры, которые сеанс использует для фильтрации событий на основе данных события. С помощью уровней и ключевых слов ETW определяет, будет ли событие записано в журнал. В случае применения фильтров поставщик использует критерии фильтра для определения, записывать ли событие в данный сеанс. Фильтры применимы только в том случае, если сеанс трассировки ETW включает вашего поставщика.

В следующих разделах показано, как определить компоненты манифеста:

Хотя вы можете создать манифест инструментирования вручную, рекомендуется использовать средство ECManGen.exe, которое входит в папку \Bin пакета SDK для Windows. Средство ECManGen.exe использует графический интерфейс, который поможет вам создать манифест с нуля, не используя XML-теги. Знание информации в этом разделе и в разделе Схема EventManifest поможет при использовании инструмента.

Если вы используете Visual Studio в качестве редактора XML, вы можете добавить схему eventManifest в проект (см. меню XML), чтобы воспользоваться преимуществами Intellisense, встроенной проверки схемы и других функций, чтобы сделать манифест простым и точным.

После написания манифеста используйте компилятор сообщений для проверки манифеста и создания файлов ресурсов и заголовков, которые вы включаете в ваш проект. Дополнительные сведения см. в о компиляции манифеста инструментирования.

В следующем примере показан скелет полностью определенного манифеста события.

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