イベント データ テンプレートの定義

プロバイダーは、データ テンプレートを使用して、イベントに含めるイベント固有のデータを定義し、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>