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

项目
06/12/2023

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>

通过

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

反馈

其他资源