Condividi tramite

StartKernelTrace

  • Articolo

Questa funzione registra e avvia una sessione di traccia eventi kernel. È anche possibile abilitare stacktour per determinati eventi del kernel usando questa funzione.

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

Parametri

TraceHandle [out]
Archivia un handle in una sessione di traccia eventi. Questo parametro è impostato su zero se l'handle non è valido. Questo parametro non deve essere confrontato con INVALID_HANDLE_VALUE. Non usare questo handle se la funzione ha esito negativo.

Proprietà [in, out]
Archivia un puntatore a una struttura di EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES configura determinati aspetti del comportamento della sessione.

Il primo membro della struttura EVENT_TRACE_PROPERTIES è una struttura WNODE_HEADER, definita qui Wnode.

Il EVENT_TRACE_PROPERTIES seguente. I membri di Wnode devono essere impostati per configurare il controllo di traccia del kernel.

Buffersize
Questo membro contiene le dimensioni totali, in byte, della memoria allocata per le proprietà della sessione di traccia eventi. Le dimensioni della memoria devono includere spazio sufficiente per archiviare i dati seguenti:

  • Struttura EVENT_TRACE_PROPERTIES.

  • Stringa nome sessione.

  • Stringa nome file di log.

Guid
Ogni sessione di traccia deve avere un GUID definito per fare riferimento alla sessione.

Per una sessione del logger del kernel NT, questo membro deve essere impostato su SystemTraceControlGuid. Per altre informazioni sulle costanti della modalità di registrazione, vedere Costanti NT Kernel Logger.

Clientcontext
Questo membro imposta la risoluzione dell'orologio utilizzata quando viene calcolato il timestamp di registrazione per ogni evento. Il valore predefinito per questo membro è un contatore delle prestazioni di query.

È possibile specificare uno dei valori seguenti:

  • 1: Contatore delle prestazioni delle query (QPC). Il QPC fornisce un timestamp a risoluzione elevata (100 nanosecondi), ma è relativamente più costoso da recuperare. Usare questa risoluzione se si dispone di tariffe di eventi elevate o se l'utente unisce eventi da buffer diversi. Nei computer meno recenti, il timestamp potrebbe non essere accurato perché il contatore a volte salta avanti a causa di errori hardware.

  • 2: Ora di sistema. Il tempo di sistema fornisce un timestamp a bassa risoluzione (10 millisecondi), ma è relativamente meno costoso da recuperare. Se il volume degli eventi è elevato, la risoluzione per il tempo di sistema potrebbe non essere sufficiente per determinare la sequenza di eventi. In questo caso, un set di eventi avrà lo stesso timestamp, ma l'ordine in cui ETW recapita gli eventi potrebbe non essere corretto.

  • 3: Contatore del ciclo della CPU. Il contatore della CPU fornisce il timestamp di risoluzione più alto ed è il meno costoso da recuperare. Tuttavia, il contatore della CPU non è affidabile e non deve essere usato in produzione. Ad esempio, in alcuni computer, il timer cambia frequenza a causa di modifiche termiche e di alimentazione, oltre all'arresto in alcuni stati. Se l'hardware non supporta questo tipo di orologio, ETW usa il tempo di sistema. In Windows Server 2003, Windows XP con SP1 e Windows XP, questo valore non è supportato. È stato introdotto in Windows Server 2003 con SP1 e Windows XP con SP2.

Bandiere
Questo membro deve contenere WNODE_FLAG_TRACED_GUID per indicare che la struttura contiene informazioni sulla traccia degli eventi e le informazioni vengono inviate a un logger. WNODE_FLAG_TRACED_GUID è definito in Evntrace.h.

I membri di EVENT_TRACE_PROPERTIES seguenti devono essere impostati anche:

LogFileMode
Indica quali modalità di registrazione devono essere usate nella sessione di traccia degli eventi del kernel. È possibile usare questo membro per specificare che gli eventi devono essere scritti in un file di log, un consumer in tempo reale o entrambi.

Questo membro può essere usato anche per specificare che la sessione è una sessione di logger privata. È possibile specificare una o più modalità. Per un elenco delle modalità possibili, vedere Costanti della modalità di registrazione.

Nota Non specificare la registrazione in tempo reale a meno che non siano presenti consumer in tempo reale pronti a usare gli eventi. Se non sono presenti consumer in tempo reale, gli eventi vengono scritti in un file di riproduzione. Le dimensioni del file di riproduzione sono limitate. Se il limite viene raggiunto, non vengono registrati nuovi eventi nel file di log o nel file di riproduzione. Le funzioni di registrazione hanno esito negativo con STATUS_LOG_FILE_FULL.

EnableFlags
Questo membro viene usato solo per le sessioni del logger del kernel NT. Identifica il logger del kernel da tracciare. Usando OR logico, questo membro può contenere uno o più valori. Oltre agli eventi specificati, il logger del kernel registra anche gli eventi di configurazione hardware.

I flag di controllo di traccia seguenti sono disponibili oltre a quelli forniti da EVENT_TRACE_PROPERTIES:

LogFileNameOffset
Questo numero rappresenta l'offset dall'inizio della memoria allocata alla struttura all'inizio della stringa con terminazione null contenente il nome del file di log.

Si applicano le considerazioni seguenti:

  • L'estensione del nome file deve essere .etl.

  • Tutte le cartelle nel percorso devono esistere.

  • Il percorso può essere relativo, assoluto, locale o remoto.

  • Il percorso non deve contenere variabili di ambiente, perché tali variabili non vengono espanse.

  • L'utente che avvia la traccia deve disporre dell'autorizzazione di scrittura nella cartella.

  • Il nome del file di log è limitato a 1024 caratteri.

  • Se si imposta LogFileMode su EVENT_TRACE_PRIVATE_LOGGER_MODE o EVENT_TRACE_FILE_MODE_NEWFILE, assicurarsi di allocare memoria sufficiente per includere l'identificatore di processo aggiunto al nome del file per sessioni di logger private e il numero sequenziale aggiunto ai file di log creati usando la nuova modalità di log dei file.

  • Se non si desidera registrare gli eventi in un file di log,ad esempio si specifica EVENT_TRACE_REAL_TIME_MODE solo, impostare LogFileNameOffset su zero. Se si specifica solo la registrazione in tempo reale e si specifica anche un offset con un nome di file di log valido, il nome del file di log viene usato per creare un file di log sequenziale e registrare gli eventi nel file di log. Il file di log sequenziale viene creato anche se LogFileMode è zero e viene fornito un offset con un nome di file di log valido.

  • Se si desidera registrare gli eventi in un file di log, è necessario allocare memoria sufficiente per questa struttura per includere il nome del file di log e il nome della sessione seguendo la struttura. Il nome del file di log deve seguire il nome della sessione in memoria.

  • I file di traccia vengono creati usando il descrittore di sicurezza predefinito, ovvero che il file di log avrà lo stesso elenco di controllo di accesso della directory padre. Se si vuole limitare l'accesso ai file, creare una directory padre con gli elenchi di controllo di accesso appropriati.

LoggerNameOffset
Questo membro rappresenta l'offset dall'inizio della memoria allocata alla struttura all'inizio della stringa con terminazione null contenente il nome della sessione.

Si applicano le considerazioni seguenti:

  • Il nome della sessione è limitato a 1024 caratteri.

  • Il nome della sessione è senza distinzione tra maiuscole e minuscole e deve essere univoco.

  • Quando si alloca la memoria per questa struttura, è necessario riservare memoria sufficiente per includere il nome della sessione e il nome del file di log seguendo la struttura.

  • Il nome della sessione deve venire prima del nome del file di log in memoria. Il nome del file di log deve essere copiato nell'area di offset. Questa funzione scrive il nome della sessione definito da KERNEL_LOGGER_NAME.

In base al tipo di file di log scelto, potrebbe essere necessario impostare il membro MaximumFileSize .

Nota Non è necessario impostare il nome del logger in LoggerNameOffset perché questa funzione usa sempre il valore KERNEL_LOGGER_NAME per chiamare StartKernelTrace. Questa funzione verifica se Wnode.Guid corrisponde a SystemTraceControlGuid; in caso contrario, restituisce ERROR_INVALID_PARAMETER. Se Wnode.Guid corrisponde a KernelRundownGuid, è necessario specificare il nome del logger. KernelRundownGuid è il GUID di controllo usato per registrare eventi come le informazioni sul processo esistenti, le informazioni sui thread, le immagini caricate per processo e la configurazione hardware, ad esempio CPU, video, disco, schede di rete, servizi, alimentazione, Plug and Play e canali IDE su disco.

Valore restituito

ERROR_SUCCESS indica l'esito positivo.

I valori di errore possibili sono descritti nella tabella seguente.

Valore errore Descrizione

ERROR_ALREADY_EXISTS

Solo una singola istanza del logger kernel viene eseguita nel sistema. Se questa funzione tenta di iniziare dopo che un altro componente ha avviato la registrazione del kernel, questo errore potrebbe essere restituito.

ERROR_INVALID_FLAGS

Possibilmente indica che esistono flag di traccia non validi in Proprietà.EnableFlags.

ERROR_OUT_OF_MEMORY

Probabilmente indica l'errore di allocare memoria per EVENT_TRACE_PROPERTIES.

Se la funzione ha esito negativo per un motivo diverso da quelli elencati, viene restituito un codice di errore di sistema.

Commenti

Se StackTracingEventIds contiene eventi non abilitati nella EVENT_TRACE_PROPERTIES. Il campo EnableFlags o non è stato possibile decodificare da Kernel Trace Control, tali flag vengono ignorati e non viene restituito alcun codice di errore.

Requisiti:

Versioni: Disponibile a partire da Windows Vista. Questa struttura viene distribuita con Windows analizzatore prestazioni.

Intestazioni: Dichiarato in KernelTraceControl.h. Includere KernelTraceControl.h.

Libreria: Contenuto in KernelTraceControl.dll.

Funzioni

Inserimento personalizzato delle informazioni di sistema