定义用于对事件类型进行分类的关键字

  • 项目

ETW 关键字 (keyword) 是一个 64 位掩码，用于指示事件在一组事件类别中的成员身份。 关键字 (keyword) 中的每个位对应于一个类别。 如果事件的关键字 (keyword) 设置了位，则该事件属于对应于该位的事件类别。

关键字 (keyword) (位掩码0x0000FFFFFFFFFFFF) 的低 48 位由清单) 的作者 (事件提供程序定义。 关键字 (keyword) (位掩码0xFFFF000000000000) 的前 16 位由 Microsoft 定义。 有关 Microsoft 定义的关键字的定义，请参阅 winmeta.h 或 winmeta.xml 中的 Windows 工具包 include 文件夹中。

提供程序使用关键字对不同类型的事件进行分类。 例如，可以将关键字 (keyword) 位 0 (关键字 (keyword) 值0x1) 定义为读取类别，然后将读取关键字 (keyword) 应用于执行读取操作（例如从文件或注册表读取）的任何事件。 然后，使用者可以使用关键字 (keyword) 位值来筛选事件的不同分类。 例如，使用者可以将事件集合会话的 MatchAnyKeyword 属性设置为 ， 0x1 使会话仅收集 读取 类别中的事件。

ETW 事件收集会话可以使用关键字 (，就像它使用级别) 来限制 ETW 服务写入其事件跟踪日志文件的事件一样。 跟踪会话可以使用两组关键字 (keyword) 位掩码来启用提供程序：一个“MatchAnyKeyword”位掩码，如果事件的任何关键字 (keyword) 位与此掩码中设置的任何位匹配，则写入事件。 和“MatchAllKeyword”位掩码，其中，对于与“MatchAnyKeyword”情况匹配的事件，仅当“MatchAllKeyword”掩码中的所有位都存在于 中时，才会写入事件 事件的关键字 (keyword) 位掩码。

例如，如果提供程序定义了一个事件，该事件指定读取关键字 (keyword) (位 0 = 0x1) 和本地访问关键字 (keyword) (位 1 = 0x2) ，另一个事件指定读取关键字 (keyword) (位 0 = 0x1) 和远程访问关键字 (keyword) (位 2 = 0x4) ，可以将事件集合会话的“MatchAnyKeyword”位掩码设置为0x1 (读取) ，将“MatchAllKeyword”位掩码设置为0x0 (无) 接收所有读取事件，也可以将“MatchAnyKeyword”位掩码设置为0x1，将“MatchAllKeyword”位掩码设置为0x3 (read + 本地) ，以仅接收本地读取。

若要为提供程序定义关键字 (keyword) ，请使用 关键字 (keyword) 元素。 为提供程序定义关键字 (keyword) 后，可以使用事件元素的 keywords 属性将关键字 (keyword) 分配给提供程序的任何事件。

必须指定关键字 (keyword) 的名称和掩码属性。 掩码必须是一个整数，设置了一个位，介于位 0 和位 47 之间，例如 mask="256" 或 mask="0x100" 要设置关键字 (keyword) 位 8。 位 48 到 63 由 Microsoft (查看winmeta.h或winmeta.xml) 定义，不能在 关键字 (keyword) 元素中使用。

符号和消息属性是可选的。

以下示例演示如何定义关键字 (keyword) 。

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