イベントの種類の分類に使用されるキーワードの定義

ETW キーワードは、一連のイベント カテゴリ内のイベントのメンバーシップを示すために使用される 64 ビット ビットマスクです。 キーワード内の各ビットはカテゴリに対応します。 イベントのキーワードにビットが設定されている場合、イベントはそのビットに対応するイベント カテゴリに属します。

キーワードの下位 48 ビット (ビットマスク 0x0000FFFFFFFFFFFF) は、イベント プロバイダー (マニフェストの作成者) によって定義されます。 キーワードの上位 16 ビット (ビットマスク 0xFFFF000000000000) は、Microsoft によって定義されます。 Microsoft で定義されたキーワードの定義については、Windows Kits include フォルダーの winmeta.h または winmeta.xml を参照してください。

プロバイダーは、キーワードを使用してさまざまな種類のイベントを分類します。 たとえば、キーワード ビット 0 (キーワード値 0x1) を 読み取り カテゴリとして定義し、ファイルやレジストリからの読み取りなどの読み取り操作を実行するイベントに 読み取り キーワードを適用できます。 コンシューマーは、キーワード ビット値を使用して、さまざまな分類のイベントをフィルター処理できます。 たとえば、コンシューマーは、イベント コレクション セッションの MatchAnyKeyword プロパティを 0x1 に設定して、セッションが 読み取り カテゴリ内のイベントのみを収集するようにすることができます。

ETW イベント 収集セッションでは、(レベルを使用するのと同じ方法で) キーワードを使用して、ETW サービスがイベント トレース ログ ファイルに書き込むイベントを制限できます。 トレース セッションでは、2 セットのキーワード ビットマスクを使用してプロバイダーを有効にすることができます。"MatchAnyKeyword" ビットマスク。イベントのキーワード ビットがこのマスクに設定されているビットのいずれかに一致する場合はイベントが書き込まれ、"MatchAllKeyword" ビットマスクが "MatchAnyKeyword" ケースに一致したイベントの場合、イベントはイベントのキーワード ビットマスクに "MatchAllKeyword" マスク内のすべてのビットが存在する場合にのみ書き込まれます。

たとえば、プロバイダーが読み取りキーワード (ビット 0 = 0x1) とローカル アクセス キーワード (ビット 1 = 0x2) を指定するイベントと、読み取りキーワード (ビット 0 = 0x1) とリモート アクセス キーワード (ビット 2 = 0x4) を指定する2つ目のイベントを定義する場合、イベント コレクション セッションの "MatchAnyKeyword" ビットマスクを 0x1 (読み取り) に設定し、"MatchAllKeyword" ビットマスクを 0x0 (なし) に設定して、すべての読み取りイベントを受信できます。もしくは、"MatchAnyKeyword" ビットマスクを 0x1 に設定し、"MatchAllKeyword" ビットマスクを 0x3 (読み取り + ローカル) に設定して、ローカル読み取りのみを受信できます。

プロバイダーのキーワードを定義するには、キーワード 要素を使用します。 プロバイダーに対してキーワードが定義されたら、イベント 要素の属性 キーワードを使用して、プロバイダーのイベントにキーワードを割り当てることができます。

キーワードの 名 を指定し、マスク 属性を指定する必要があります。 マスクは、キーワード ビット 8 を設定するための mask="256" や mask="0x100" など、ビット 0 からビット 47 までの 1 ビットセットの整数である必要があります。 ビット 48 から 63 は Microsoft によって定義され (winmeta.h または winmeta.xmlを参照)、キーワード 要素では使用できません。

シンボル および メッセージ 属性は省略可能です。

次の例は、キーワードを定義する方法を示しています。

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

                . . .

                <keywords>
                    <keyword name="Read" mask="0x1" symbol="READ_KEYWORD"/>
                    <keyword name="Write" mask="0x2" symbol="WRITE_KEYWORD"/>
                    <keyword name="Local" mask="0x4" symbol="LOCAL_KEYWORD"/>
                    <keyword name="Remote" mask="0x8" symbol="REMOTE_KEYWORD"/>
                </keywords>

                . . .

            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources culture="en-US">
            <stringTable>
                <string id="Provider.Name" value="Sample Provider"/>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>