Определение шаблонов данных событий
Поставщики используют шаблоны данных для определения данных, специфичных для событий, и для определения данных фильтра, которые сеанс трассировки ETW может передать поставщику при активации последнего. Если событие не содержит конкретные данные события, вы не будете определять шаблон. Чтобы определить шаблон, используйте элемент шаблона . Шаблон содержит элемент данных для каждого фрагмента данных, который поставщик включает в событие. Вы можете указать целые типы, строки, массивы и структуры. Необходимо записать данные события в том порядке, в который были определены элементы данных в шаблоне.
Вы также можете включить в шаблон фрагмент XML, который потребители должны использовать для определения способа отрисовки данных события. Если фрагмент не включен, потребители должны обрабатывать данные события в том порядке, в котором были определены элементы данных в шаблоне.
При определении шаблона необходимо предоставить ему идентификатор шаблона, используемый для ссылки на шаблон в определении события. Каждый элемент данных в шаблоне должен указывать имя и тип входных данных (список доступных типов входных данных см. в разделе "Примечания" сложного типа InputType). Если входной тип данных может быть представлен в нескольких форматах, следует указать выходной тип данных, который информирует потребителей о способе визуализации элемента данных. Например, входной тип данных UInt32 можно отобразить как целое число без знака, идентификатор потока, адрес IPv4 и код ошибки Win32. Если тип выходных данных не указан, потребители должны использовать тип выходных данных по умолчанию входного типа для отрисовки элемента данных.
Чтобы указать массив, включите атрибут количество для элемента данных и установите в него число элементов в массиве. Массив может быть массивом размера переменной или массивом фиксированного размера. Если массив является массивом фиксированного размера, задайте размер массива. Например, если массив целых чисел имеет фиксированный размер 10, установите счетчик на 10. При записи массива необходимо написать 40 байт данных.
Если массив является массивом переменной длины, установите как имя элемента данных, который содержит размер массива. Если массив содержит указатели, адрес указателей записывается как данные события, а не данные, к которым указывает указатель.
Необходимо указать длину атрибут, если элемент данных является двоичным BLOB-объектом. Можно также указать атрибут длины для строк фиксированной длины.
Укажите атрибут сопоставления, если элемент данных представляет значение перечисления, и вы хотите, чтобы потребитель выводил строковое представление значения вместо его численного значения.
Если вы включаете структуры в шаблон, следует описывать элементы структуры по отдельности вместо описания всей структуры, если вы не можете гарантировать 8-байтное выравнивание границ.
Вам следует тщательно обдумать сведения, которые вы включаете в события, особенно если они вносятся в глобальные каналы. Как правило, в события не следует включать частную информацию. К ним относятся пароли с открытым текстом и персональные данные пользователя. Кроме того, программы, выполняемые пользователем, URL-адреса, которые посетил пользователь, и другие сведения, связанные с действиями пользователя на компьютере, должны считаться частными.
Если необходимо записать URL-адреса и имена пользователей в событиях, не записывайте их в каналы Windows (системные и приложения), так как эти каналы доступны для чтения всеми прошедшими проверку подлинности пользователями. Вместо этого напишите их в собственные операционные или аналитические каналы. Задайте разрешения на доступ в этих каналах, чтобы разрешить только администраторам читать события. Возможно, потребуется предоставить соответствующее раскрытие информации, чтобы уведомить пользователей о том, что частная информация предоставляется администраторам.
В следующем примере показано, как определить шаблон. Необходимо указать атрибут tid шаблона , на который ссылается определение события или определение фильтра.
<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)">
. . .
<maps>
<valueMap name="TransferType">
<map value="1" message="$(string.TransferType.Download)"/>
<map value="2" message="$(string.TransferType.Upload)"/>
<map value="3" message="$(string.TransferType.UploadReply)"/>
</valueMap>
<bitMap name="DaysOfTheWeek">
<map value="0x1" message="$(string.DaysOfTheWeek.Sunday)"/>
<map value="0x2" message="$(string.DaysOfTheWeek.Monday)"/>
<map value="0x4" message="$(string.DaysOfTheWeek.Tuesday)"/>
<map value="0x8" message="$(string.DaysOfTheWeek.Wednesday)"/>
<map value="0x10" message="$(string.DaysOfTheWeek.Thursday)"/>
<map value="0x20" message="$(string.DaysOfTheWeek.Friday)"/>
<map value="0x40" message="$(string.DaysOfTheWeek.Saturday)"/>
</bitMap>
</maps>
<templates>
<template tid="t2">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="Day" inType="win:UInt32" map="DaysOfTheWeek"/>
<data name="Transfer" inType="win:UInt32" map="TransferType"/>
</template>
<template tid="t3">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="ErrorCode" inType="win:Int32" outType="win:HResult"/>
<data name="FilesCount" inType="win:UInt16" />
<data name="Files" inType="win:UnicodeString" count="FilesCount"/>
<data name="BufferSize" inType="win:UInt32" />
<data name="Buffer" inType="win:Binary" length="BufferSize"/>
<data name="Certificate" inType="win:Binary" length="11" />
<data name="IsLocal" inType="win:Boolean" />
<data name="Path" inType="win:UnicodeString" />
<data name="ValuesCount" inType="win:UInt16" />
<struct name="Values" count="ValuesCount" >
<data name="Value" inType="win:UInt16" />
<data name="Name" inType="win:UnicodeString" />
</struct>
</template>
</templates>
. . .
</provider>
</events>
</instrumentation>
<localization>
<resources culture="en-US">
<stringTable>
<string id="Provider.Name" value="Sample Provider"/>
<string id="TransferType.Download" value="Download"/>
<string id="TransferType.Upload" value="Upload"/>
<string id="TransferType.UploadReply" value="Upload-reply"/>
<string id="DaysOfTheWeek.Sunday" value="Sunday"/>
<string id="DaysOfTheWeek.Monday" value="Monday"/>
<string id="DaysOfTheWeek.Tuesday" value="Tuesday"/>
<string id="DaysOfTheWeek.Wednesday" value="Wednesday"/>
<string id="DaysOfTheWeek.Thursday" value="Thursday"/>
<string id="DaysOfTheWeek.Friday" value="Friday"/>
<string id="DaysOfTheWeek.Saturday" value="Saturday"/>
</stringTable>
</resources>
</localization>
</instrumentationManifest>