イベント データ テンプレートの定義
プロバイダーは、データ テンプレートを使用して、イベントに含めるイベント固有のデータを定義し、ETW トレース セッションがプロバイダーを有効にしたときにプロバイダーに渡すことができるフィルター データを定義します。 イベントにイベント固有のデータが含まれていない場合、テンプレートは定義されません。 テンプレートを定義するには、 template 要素を使用します。 テンプレートには、プロバイダーがイベントに含めるデータの各部分のデータ項目が含まれます。 整数型、文字列、配列、および構造体を指定できます。 イベント データは、データ項目がテンプレートで定義された順序で書き込む必要があります。
テンプレートには、コンシューマーがイベント データのレンダリング方法を決定するために使用する必要がある XML フラグメントを含めることもできます。 フラグメントを含まない場合、コンシューマーは、データ項目がテンプレートで定義された順序でイベント データをレンダリングする必要があります。
テンプレートを定義するときは、イベント定義でテンプレートを参照するために使用するテンプレート識別子を指定する必要があります。 テンプレート内の各データ項目には、名前と入力データ型を指定する必要があります (入力型の一覧については、 InputType 複合型の「解説」セクションを参照してください)。 入力データ型を複数の形式でレンダリングできる場合は、データ項目のレンダリング方法をコンシューマーに指示する出力データ型を指定する必要があります。 たとえば、UInt32 入力データ型は、符号なし整数、スレッド識別子、IPv4 アドレス、および Win32 エラー コードとしてレンダリングできます。 出力データ型を指定しない場合、コンシューマーは入力型の既定の出力型を使用してデータ項目をレンダリングする必要があります。
配列を指定するには、データ項目に count 属性を含め、配列内の要素の数に設定します。 配列には、可変サイズ配列または固定サイズ配列を指定できます。 配列が固定サイズの配列の場合は、 count を配列のサイズに設定します。 たとえば、整数の配列の固定サイズが 10 の場合は、 count を 10 に設定します。 配列を記述するときは、40 バイトのデータを書き込む必要があります。
配列が可変サイズ配列の場合は、 count に配列のサイズを含むデータ項目の名前を設定します。 配列にポインターが含まれている場合、ポインターのアドレスは、ポインターが指すデータではなく、イベント データとして書き込まれます。
データ項目がバイナリ BLOB の場合は、 length 属性を指定する必要があります。 固定長文字列の 長さ 属性を指定することもできます。
データ項目が列挙値を表し、コンシューマーが値自体ではなく値の文字列を出力する場合は、 map 属性を指定します。
テンプレートに構造体を含める場合は、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>