Определение шаблонов данных событий
Поставщики используют шаблоны данных для определения данных, которые они включают в событие, и для определения данных фильтра, которые сеанс трассировки ETW может передать поставщику при включении поставщика. Если событие не содержит данные, относящиеся к конкретному событию, шаблон не определяется. Чтобы определить шаблон, используйте элемент template . Шаблон содержит элемент данных для каждого элемента данных, который поставщик включает в событие. Можно указать целочисленные типы, строки, массивы и структуры. Данные события необходимо записывать в том порядке, в который элементы данных были определены в шаблоне.
Вы также можете включить в шаблон XML-фрагмент, который потребители должны использовать для определения способа отрисовки данных события. Если фрагмент не включен, потребители должны отображать данные события в том порядке, в который элементы данных были определены в шаблоне.
При определении шаблона необходимо присвоить ему идентификатор шаблона, который используется для ссылки на шаблон в определении события. Каждый элемент данных в шаблоне должен указывать имя и тип входных данных (список входных типов см. в разделе Примечания сложного типа InputType ). Если входной тип данных может быть отрисован в нескольких форматах, следует указать тип выходных данных, который сообщает потребителям, как отрисовка элемента данных. Например, входной тип данных UInt32 можно отобразить в виде целого числа без знака, идентификатора потока, IPv4-адреса и кода ошибки Win32. Если тип выходных данных не указан, потребители должны использовать тип выходных данных по умолчанию для отрисовки элемента данных.
Чтобы указать массив, включите атрибут count в элемент данных и задайте для него количество элементов в массиве. Массив может быть массивом переменного размера или массивом фиксированного размера. Если массив является массивом фиксированного размера, задайте для параметра count значение размера массива. Например, если массив целых чисел имеет фиксированный размер 10, задайте для параметра count значение 10. При записи массива необходимо записать 40 байт данных.
Если массив является массивом переменной величины, задайте для параметра count имя элемента данных, содержащего размер массива. Если массив содержит указатели, адрес указателей записывается как данные события, а не данные, на которые указывают указатели.
Необходимо указать атрибут length , если элемент данных является двоичным BLOB-объектом. Можно также указать атрибут length для строк фиксированной длины.
Укажите атрибут карты , если элемент данных представляет значение перечисления и вы хотите, чтобы потребитель напечатыл строку для значения, а не самого значения.
При включении структур в шаблон следует записывать элементы структуры по отдельности, а не записывать структуру, если вы не можете гарантировать выравнивание границ в 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>