Definir palabras clave usadas para clasificar tipos de eventos

Una palabra clave ETW es una máscara de bits de 64 bits que se usa para indicar la pertenencia de un evento en un conjunto de categorías de eventos. Cada bit de la palabra clave corresponde a una categoría. Si la palabra clave de un evento tiene un bit establecido, el evento pertenece a la categoría de eventos correspondiente a ese bit.

El proveedor de eventos define los 48 bits bajos de la palabra clave (máscara de bits 0x0000FFFFFFFFFFFF). Microsoft define los 16 bits principales de la palabra clave (máscara de bits 0xFFFF000000000000). Consulte winmeta.h o winmeta.xml en la carpeta include de Windows Kits para obtener las definiciones de las palabras clave definidas por Microsoft.

Los proveedores usan palabras clave para clasificar diferentes tipos de eventos. Por ejemplo, podría definir el bit de palabra clave 0 (valor 0x1de palabra clave ) como categoría de lectura y, a continuación, aplicar la palabra clave read a cualquier evento que realice una operación de lectura, como leer desde un archivo o registro. A continuación, los consumidores podrían usar los valores de bits de palabra clave para filtrar por diferentes clasificaciones de eventos. Por ejemplo, el consumidor podría establecer la propiedad MatchAnyKeyword de la sesión de recopilación de eventos para 0x1 que la sesión recopile solo los eventos de la categoría de lectura .

Una sesión de recopilación de eventos ETW puede usar las palabras clave (de la misma manera que usa el nivel) para limitar los eventos que el servicio ETW escribe en su archivo de registro de seguimiento de eventos. Una sesión de seguimiento puede habilitar el proveedor mediante dos conjuntos de máscaras de bits de palabra clave: una máscara de bits "MatchAnyKeyword" donde se escribe el evento si alguno de los bits de palabra clave del evento coincide con cualquiera de los bits establecidos en esta máscara, y una máscara de bits "MatchAllKeyword" donde para los eventos que coinciden con el caso "MatchAnyKeyword", el evento solo se escribe si todos los bits de la máscara "MatchAllKeyword" existen en la máscara de bits de palabra clave del evento.

Por ejemplo, si el proveedor define un evento que especifica una palabra clave read (bit 0 = 0x1) y una palabra clave de acceso local (bit 1 = 0x2), y un segundo evento que especifica una palabra clave read (bit 0 = 0x1) y una palabra clave de acceso remoto (bit 2 = 0x4), podría establecer la máscara 0x1 de bits "MatchAnyKeyword" de la sesión de recopilación de eventos en (read) y la máscara 0x0 de bits "MatchAllKeyword" en (ninguno) para recibir todos los eventos de lectura, o bien, puede establecer la máscara de bits "MatchAnyKeyword" en 0x1 y la máscara 0x3 de bits "MatchAllKeyword" en (lectura + local) para recibir solo lecturas locales.

Para definir una palabra clave para el proveedor, use el elemento keyword . Una vez definida una palabra clave para el proveedor, puede asignar la palabra clave a cualquiera de los eventos del proveedor mediante el atributo keywords del elemento event .

Debe especificar los atributos name y mask de la palabra clave. La máscara debe ser un entero con un bit establecido, entre el bit 0 y el bit 47, como mask="256" o mask="0x100" para establecer el bit de palabra clave 8. Microsoft define los bits de 48 a 63 (vea winmeta.h o winmeta.xml) y no se puede usar en el elemento de palabra clave .

Los atributos de símbolo y mensaje son opcionales.

En el ejemplo siguiente se muestra cómo definir una palabra clave.

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