Configurazione e avvio di una sessione di traccia eventi
Per configurare una sessione di traccia eventi, utilizzare la struttura EVENT_TRACE_PROPERTIES per specificare le proprietà della sessione. La memoria allocata per la struttura EVENT_TRACE_PROPERTIES deve essere sufficientemente grande da contenere anche i nomi di file di sessione e di log che seguono la struttura in memoria.
Dopo aver specificato le proprietà della sessione, chiamare la funzione StartTrace per avviare la sessione. Se la funzione ha esito positivo, il parametro SessionHandle conterrà l'handle di sessione e la proprietà LoggerNameOffset conterrà l'offset al nome della sessione.
Per abilitare i provider che si desidera registrare eventi nella sessione, chiamare la funzione EnableTrace per abilitare i provider classici e la funzione EnableTraceEx per abilitare i provider basati su manifesto. Per abilitare i provider che vuoi registrare gli eventi nel filtro della sessione in base a condizioni specifiche in Windows 8.1,Windows Server 2012 R2 e versioni successive, chiama la funzione EnableTraceEx2.
Inoltre, puoi anche tracciare informazioni aggiuntive su un evento con una chiamata alla funzione TraceSetInformation. TraceSetInformation inserisce informazioni di traccia aggiuntive nella sezione dei dati estesi di un evento e può includere informazioni quali le informazioni sulla versione di traccia o quali provider sono attualmente registrati nel sistema. Per altre informazioni, vedere Recupero di dati di traccia eventi aggiuntivi.
Fino a otto sessioni di traccia possono abilitare e ricevere eventi dallo stesso provider basato su manifesto. Tuttavia, solo una sessione di traccia può abilitare un provider classico . Se più sessioni di traccia tentano di abilitare un provider classico, la prima sessione smette di ricevere eventi quando la seconda sessione abilita il provider. Ad esempio, se il provider 1 abilitato per la sessione A e quindi il provider 1 abilitato per la sessione B, solo la sessione B riceverà gli eventi dal provider 1.
È possibile usare una delle tre funzioni per abilitare un provider, ma è possibile perdere funzionalità se si usa EnableTrace per abilitare un provider basato su manifesto perché non sarà possibile fornire un valore MatchAllKeyword, specificare elementi di dati estesi da includere nell'evento o fornire dati di filtro definiti dal provider. Per altre informazioni, vedere la sezione Osservazioni di ogni funzione.
In Windows 8.1,Windows Server 2012 R2 e versioni successive, il payload dell'evento, l'ambito e i filtri di procedura dettagliata dello stack possono essere usati dalla funzione EnableTraceEx2 e dalle strutture ENABLE_TRACE_PARAMETERS e EVENT_FILTER_DESCRIPTOR per filtrare in base a condizioni specifiche in una sessione del logger. Per altre informazioni sui filtri del payload degli eventi, vedere le funzioni TdhCreatePayloadFilter e TdhAggregatePayloadFilters e le strutture ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR e PAYLOAD_FILTER_PREDICATE.
Per determinare il livello e le parole chiave usate per abilitare un provider basato su manifesto, usare uno dei comandi seguenti:
- Nome provider di query logman
- Wevtutil gp provider-name
I comandi elencano solo il livello e le parole chiave, il provider deve documentare i requisiti dei dati di filtro per i potenziali controller.
Per enumerare i provider basati su manifesto, usare Wevtutil ep.
Per i provider classici, spetta al provider documentare e rendere disponibili ai potenziali controller i livelli di gravità o abilitare i flag supportati. Se il provider vuole essere abilitato da qualsiasi controller, il provider deve accettare 0 per il livello di gravità e abilitare i flag e interpretare 0 come richiesta di eseguire la registrazione predefinita (qualunque sia).
È possibile abilitare il provider prima o dopo la registrazione del provider stesso. Dopo aver abilitato il provider, ETW chiamerà quindi la funzione di callback del provider. Se il provider non è registrato, ETW chiamerà la funzione di callback del provider dopo la registrazione.
È anche possibile usare la funzione EnableTrace per disabilitare il provider (arrestarlo dalla registrazione degli eventi alla sessione) o per aggiornare il livello di registrazione o abilitare i flag del provider. Con la funzione EnableTraceEx , è possibile disabilitare il provider o aggiornare il livello, le parole chiave, i dati estesi e filtrare i dati. Ogni volta che si chiama la funzione EnableTrace o EnableTraceEx , ETW chiama la funzione di callback del provider. Il provider rimane abilitato per la sessione fino a quando la sessione non disabilita il provider.
Per arrestare la sessione di traccia dopo la raccolta di eventi, chiamare la funzione ControlTrace e passare EVENT_TRACE_CONTROL_STOP come codice di controllo. Per specificare la sessione da arrestare, è possibile passare l'handle di sessione di traccia eventi ottenuto da una chiamata precedente alla funzione StartTrace o il nome di una sessione avviata in precedenza. Assicurarsi di disabilitare tutti i provider prima di arrestare la sessione. Se si arresta la sessione prima di disabilitare il provider, ETW disabiliterà il provider e tenterà di chiamare la funzione di callback del controllo del provider. Se l'applicazione che ha avviato la sessione termina senza disabilitare il provider o chiamare la funzione ControlTrace , il provider rimane abilitato.
Se ControlTrace ha esito positivo , le proprietà della sessione vengono aggiornate in modo da riflettere i valori finali delle proprietà ed eseguire statistiche per la sessione di traccia eventi.
Per un esempio che avvia una sessione di traccia eventi, vedere quanto segue:
- Esempio che crea una sessione e abilita un provider basato su manifesto: avvia una sessione di traccia, abilita un provider basato su manifesto, disabilita il provider e quindi arresta la sessione.
Per informazioni dettagliate sull'avvio di una sessione di traccia, vedere una delle opzioni seguenti:
- Configurazione e avvio di una sessione SystemTraceProvider
- Configurazione e avvio della sessione del logger del kernel NT
- Configurazione e avvio di una sessione autoLogger
- Configurazione e avvio della sessione globale del logger
- Configurazione e avvio di una sessione logger privata
Argomenti correlati