Escritura de un manifiesto de instrumentación

Las aplicaciones y los archivos DLL usan un manifiesto de instrumentación para identificar sus proveedores de instrumentación y los eventos que escriben los proveedores. Un manifiesto es un archivo XML que contiene los elementos que identifican al proveedor. La convención consiste en usar .man como extensión para el manifiesto. El manifiesto debe ajustarse al manifiesto de evento XSD. Para obtener más información sobre el esquema, vea Esquema EventManifest.

Un proveedor de instrumentación es cualquier aplicación o DLL que llama a las funciones EventWriteEx, EventWriteString o EventWriteTransfer para escribir eventos en una sesión de seguimiento de Seguimiento de eventos (ETW) o en un canal de registro de eventos. Una aplicación puede definir un único proveedor de instrumentación que abarque todos los eventos que escribe o puede definir un proveedor para la aplicación y un proveedor para cada uno de sus archivos DLL. El número de proveedores que define la aplicación en el manifiesto depende únicamente de cómo la aplicación desea organizar los eventos que escribe.

La ventaja de especificar un proveedor para cada DLL es que, a continuación, puede habilitar y deshabilitar los proveedores individuales y, por tanto, los eventos que generan. Esta ventaja solo se aplica si el proveedor está habilitado por una sesión de seguimiento de ETW. Los eventos que especifican un canal de registro de eventos siempre se escriben en ese canal.

El manifiesto debe identificar el proveedor y los eventos que escribe, pero los demás metadatos, como canales, niveles y palabras clave, son opcionales; si define los metadatos opcionales depende de quién va a consumir los eventos. Por ejemplo, si los administradores o el personal de soporte técnico consumen los eventos mediante una herramienta como windows Visor de eventos que lee eventos de canales de registro de eventos, debe definir los canales en los que se escriben los eventos. Sin embargo, si el proveedor solo estará habilitado por una sesión de seguimiento de ETW, no es necesario definir canales.

Aunque los niveles, las tareas, los códigos de operación y los metadatos de palabras clave son opcionales, debe usarlos para agrupar o agrupar lógicamente los eventos. La agrupación de los eventos ayuda a los consumidores a consumir solo los eventos que son de interés. Por ejemplo, el consumidor podría consultar todos los eventos en los que el nivel es "crítico" y la palabra clave es "write" o consultar todos los eventos escritos por una tarea específica.

Además de los consumidores que usan el nivel y las palabras clave para consumir tipos específicos de eventos, una sesión de seguimiento ETW puede usar los metadatos de nivel y palabra clave para indicar a ETW que limite los eventos escritos en el registro de seguimiento de eventos. Por ejemplo, la sesión podría limitar los eventos a solo los eventos en los que el nivel es "error" o "crítico" y la palabra clave es "read".

Un proveedor puede definir filtros que una sesión usa para filtrar los eventos en función de los datos del evento. Con el nivel y las palabras clave, ETW determina si el evento se escribe en el registro pero con filtros, el proveedor usa los criterios de datos de filtro para determinar si escribe el evento en esa sesión. Los filtros solo son aplicables cuando una sesión de seguimiento ETW habilita el proveedor.

En las secciones siguientes se muestra cómo definir los componentes del manifiesto:

• Identificación del proveedor
• Definición de los canales en los que se escriben los eventos
• Definición de los niveles de gravedad de los eventos que escribe el proveedor
• Definición de las tareas y operaciones que realiza el proveedor
• Definición de las palabras clave que clasifican los eventos que escribe el proveedor
• Definición de los filtros que usa el proveedor para filtrar los eventos que escribe
• Definición de las asignaciones de nombre y valor a las que hacen referencia los datos de la plantilla
• Definición de las plantillas que definen los datos específicos del evento
• Definición de los eventos que escribe el proveedor

Aunque puede crear manualmente un manifiesto de instrumentación, debe considerar el uso de la herramienta ECManGen.exe que se incluye en la carpeta \Bin del SDK de Windows. La herramienta ECManGen.exe usa una GUI que le guía a través de la creación de un manifiesto desde cero sin tener que usar etiquetas XML. Tener conocimiento de la información de esta sección y en la sección Esquema de EventManifest le ayudará al usar la herramienta.

Si usa Visual Studio como editor XML, puede agregar el esquema EventManifest al proyecto (consulte el menú XML) para aprovechar IntelliSense, la validación de esquemas insertados y otras características para facilitar y precisa la escritura del manifiesto.

Después de escribir el manifiesto, use el compilador de mensajes para validar el manifiesto y generar los archivos de recursos y encabezados que incluya en el proveedor. Para obtener más información, vea Compilar un manifiesto de instrumentación.

En el ejemplo siguiente se muestra el esqueleto de un manifiesto de evento completamente definido.

<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 ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>