Escrevendo um manifesto de instrumentação

  • Artigo

Aplicativos e DLLs usam um manifesto de instrumentação para identificar seus provedores de instrumentação e os eventos que os provedores gravam. Um manifesto é um arquivo XML que contém os elementos que identificam seu provedor. A convenção é usar .man como a extensão do manifesto. O manifesto deve estar em conformidade com o XSD do manifesto do evento. Para obter detalhes sobre o esquema, consulte Esquema EventManifest.

Um provedor de instrumentação é qualquer aplicativo ou DLL que chama as funções EventWriteEx, EventWriteString ou EventWriteTransfer para gravar eventos em uma sessão de rastreamento etw (Rastreamento de Eventos ) ou um canal de Log de Eventos. Um aplicativo pode definir um único provedor de instrumentação que abrange todos os eventos que grava ou pode definir um provedor para o aplicativo e um provedor para cada uma de suas DLLs. O número de provedores que o aplicativo define no manifesto depende apenas de como o aplicativo deseja organizar os eventos que ele grava.

A vantagem de especificar um provedor para cada DLL é que você pode habilitar e desabilitar os provedores individuais e, portanto, os eventos que eles geram. Essa vantagem só se aplicará se o provedor estiver habilitado por uma sessão de rastreamento ETW. Todos os eventos que especificam um canal de log de eventos são sempre gravados nesse canal.

O manifesto deve identificar o provedor e os eventos que ele grava, mas os outros metadados, como canais, níveis e palavras-chave, são opcionais; se você definir os metadados opcionais depende de quem consumirá os eventos. Por exemplo, se os administradores ou a equipe de suporte consumirem os eventos usando uma ferramenta como o Windows Visualizador de Eventos que lê eventos de canais de log de eventos, você deverá definir os canais nos quais os eventos são gravados. No entanto, se o provedor só for habilitado por uma sessão de rastreamento ETW, você não precisará definir canais.

Embora os níveis, tarefas, opcodes e metadados de palavras-chave sejam opcionais, você deve usá-los para agrupar ou agrupar logicamente os eventos. O agrupamento dos eventos ajuda os consumidores a consumir apenas os eventos de interesse. Por exemplo, o consumidor pode consultar todos os eventos em que level é "crítico" e palavra-chave é "write" ou consultar todos os eventos gravados por uma tarefa específica.

Além dos consumidores usarem palavras-chave e nível para consumir tipos específicos de eventos, uma sessão de rastreamento etw pode usar o nível e palavra-chave metadados para instruir o ETW a limitar os eventos gravados no log de rastreamento de eventos. Por exemplo, a sessão pode limitar os eventos somente a eventos em que o nível é "erro" ou "crítico" e palavra-chave é "leitura".

Um provedor pode definir filtros que uma sessão usa para filtrar os eventos com base nos dados do evento. Com palavras-chave e nível, o ETW determina se o evento é gravado no log, mas com filtros, o provedor usa os critérios de dados de filtro para determinar se ele grava o evento nessa sessão. Os filtros são aplicáveis somente quando uma sessão de rastreamento ETW habilita seu provedor.

As seções a seguir mostram como definir os componentes do manifesto:

Embora você possa criar um manifesto de instrumentação manualmente, considere usar a ferramenta ECManGen.exe incluída na pasta \Bin do SDK do Windows. A ferramenta ECManGen.exe usa uma GUI que orienta você na criação de um manifesto do zero sem precisar usar marcas XML. Ter conhecimento das informações nesta seção e na seção Esquema EventManifest ajudará ao usar a ferramenta.

Se você usar o Visual Studio como seu editor XML, poderá adicionar o esquema EventManifest ao projeto (consulte o menu XML) para aproveitar o IntelliSense, a validação de esquema embutido e outros recursos para tornar a gravação do manifesto fácil e precisa.

Depois de escrever o manifesto, use o compilador de mensagem para validar o manifesto e gerar os arquivos de recurso e cabeçalho que você inclui em seu provedor. Para obter mais informações, consulte Compilando um manifesto de instrumentação.

O exemplo a seguir mostra o esqueleto de um manifesto de evento totalmente 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>