Scrittura di un manifesto di strumentazione

Le applicazioni e le DLL usano un manifesto di strumentazione per identificare i provider di strumentazione e gli eventi scritti dai provider. Un manifesto è un file XML che contiene gli elementi che identificano il provider. La convenzione consiste nell'usare .man come estensione per il manifesto. Il manifesto deve essere conforme al manifesto dell'evento XSD. Per informazioni dettagliate sullo schema, vedere Schema EventManifest.

Un provider di strumentazione è qualsiasi applicazione o DLL che chiama le funzioni EventWriteEx, EventWriteString o EventWriteTransfer per scrivere eventi in una sessione di traccia eventi (ETW) o in un canale del registro eventi. Un'applicazione può definire un singolo provider di strumentazione che copre tutti gli eventi che scrive o può definire un provider per l'applicazione e un provider per ognuna delle dll. Il numero di provider definiti dall'applicazione nel manifesto dipende esclusivamente dal modo in cui l'applicazione vuole organizzare gli eventi scritti dall'applicazione.

Il vantaggio di specificare un provider per ogni DLL è quindi possibile abilitare e disabilitare i singoli provider e quindi gli eventi generati. Questo vantaggio si applica solo se il provider è abilitato da una sessione di traccia ETW. Tutti gli eventi che specificano un canale del log eventi vengono sempre scritti in tale canale.

Il manifesto deve identificare il provider e gli eventi scritti, ma gli altri metadati, ad esempio canali, livelli e parole chiave sono facoltativi; se si definiscono i metadati facoltativi dipende da chi verrà utilizzato gli eventi. Ad esempio, se gli amministratori o il personale di supporto utilizzano gli eventi usando uno strumento come windows Visualizzatore eventi che legge gli eventi dai canali del log eventi, è necessario definire i canali a cui vengono scritti gli eventi. Tuttavia, se il provider sarà abilitato solo da una sessione di traccia ETW, non è necessario definire i canali.

Anche se i livelli, le attività, i codici opcode e i metadati delle parole chiave sono facoltativi, è consigliabile usarli per raggrupparli logicamente o raggruppare gli eventi. Raggruppare gli eventi consente agli utenti di utilizzare solo gli eventi che sono di interesse. Ad esempio, il consumer potrebbe eseguire una query per tutti gli eventi in cui il livello è "critico" e la parola chiave è "scrittura" o query per tutti gli eventi scritti da un'attività specifica.

Oltre ai consumer che usano parole chiave e livello per utilizzare tipi specifici di eventi, una sessione di traccia ETW può usare i metadati di livello e parola chiave per indicare a ETW di limitare gli eventi scritti nel log di traccia eventi. Ad esempio, la sessione potrebbe limitare gli eventi solo agli eventi in cui il livello è "error" o "critical" e la parola chiave è "read".

Un provider può definire filtri usati da una sessione per filtrare gli eventi in base ai dati degli eventi. Con parole chiave e livello, ETW determina se l'evento viene scritto nel log, ma con filtri, il provider usa i criteri di dati del filtro per determinare se scrive l'evento in tale sessione. I filtri sono applicabili solo quando una sessione di traccia ETW abilita il provider.

Le sezioni seguenti illustrano come definire i componenti del manifesto:

• Identificazione del provider
• Definizione dei canali in cui vengono scritti gli eventi
• Definizione dei livelli di gravità degli eventi scritti dal provider
• Definizione delle attività e delle operazioni eseguite dal provider
• Definizione delle parole chiave che classificano gli eventi scritti dal provider
• Definizione dei filtri usati dal provider per filtrare gli eventi che scrive
• Definizione del nome/valore mappata ai riferimenti ai dati del modello
• Definizione dei modelli che definiscono i dati specifici dell'evento
• Definizione degli eventi scritti dal provider

Anche se è possibile creare manualmente un manifesto di strumentazione, è consigliabile usare lo strumento ECManGen.exe incluso nella cartella \Bin di Windows SDK. Lo strumento ECManGen.exe usa un'interfaccia utente grafica che illustra la creazione di un manifesto da zero senza dover usare tag XML. La conoscenza delle informazioni contenute in questa sezione e nella sezione Schema EventManifest consente di usare lo strumento.

Se si usa Visual Studio come editor XML, è possibile aggiungere lo schema EventManifest al progetto (vedere il menu XML) per sfruttare Intellisense, la convalida dello schema inline e altre funzionalità per semplificare e precisione del manifesto.

Dopo aver scritto il manifesto, usare il compilatore di messaggi per convalidare il manifesto e generare i file di risorsa e intestazione inclusi nel provider. Per altre informazioni, vedere Compilazione di un manifesto di strumentazione.

Nell'esempio seguente viene illustrato lo scheletro di un manifesto evento completamente definito.

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