struttura EVENT_TRACE_PROPERTIES (evntrace.h)
La struttura EVENT_TRACE_PROPERTIES contiene informazioni su una sessione di traccia eventi. Questa struttura viene usata con API come StartTrace e ControlTrace durante la definizione, l'aggiornamento o l'esecuzione di query sulle proprietà di una sessione.
Nota
Si tratta di una struttura della versione 1. Le opzioni aggiuntive sono supportate da EVENT_TRACE_PROPERTIES_V2 (ad esempio FilterDesc e V2Options).
Sintassi
typedef struct _EVENT_TRACE_PROPERTIES {
WNODE_HEADER Wnode;
ULONG BufferSize;
ULONG MinimumBuffers;
ULONG MaximumBuffers;
ULONG MaximumFileSize;
ULONG LogFileMode;
ULONG FlushTimer;
ULONG EnableFlags;
union {
LONG AgeLimit;
LONG FlushThreshold;
} DUMMYUNIONNAME;
ULONG NumberOfBuffers;
ULONG FreeBuffers;
ULONG EventsLost;
ULONG BuffersWritten;
ULONG LogBuffersLost;
ULONG RealTimeBuffersLost;
HANDLE LoggerThreadId;
ULONG LogFileNameOffset;
ULONG LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;
Members
Wnode
Struttura WNODE_HEADER . È necessario specificare i membri BufferSize, Flag e Guid . Facoltativamente, è possibile specificare il membro ClientContext .
BufferSize
Kilobyte di memoria allocata per ogni buffer della sessione di traccia eventi. La dimensione minima del buffer è 4 (4 KB). La dimensione massima del buffer è 16384 (16 MB). La maggior parte delle sessioni di traccia deve usare una dimensione del buffer di 64 KB o inferiore per evitare di sprecare memoria e spazio su disco. Prima di Windows 8: la dimensione massima del buffer è 1024 (1 MB).
Le dimensioni del buffer più piccole riducono l'utilizzo della memoria della sessione e consentono di ridurre le dimensioni dei file di log. Le dimensioni del buffer più grandi supportano la raccolta di eventi di dimensioni maggiori perché ETW non frammenta gli eventi attraverso i limiti del buffer e pertanto non può raccogliere eventi superiori alle dimensioni del buffer. Negli scenari che coinvolgono una velocità effettiva dei dati estremamente elevata, le dimensioni del buffer maggiori possono anche ridurre il sovraccarico della CPU.
- Una sessione con eventi di piccole dimensioni e una frequenza di eventi bassa (pochi KB/sec) deve usare una dimensione del buffer ridotta (da 4 KB a 16 KB).
- Una sessione con eventi di piccole dimensioni e una frequenza di eventi moderata devono usare una dimensione media del buffer (da 16 KB a 32 KB).
- Una sessione con eventi di grandi dimensioni o una frequenza di eventi elevata (alcuni MB/s) deve usare una dimensione del buffer di grandi dimensioni (da 64 KB a 128 KB).
- In rari casi, quando una grande quantità di memoria deve essere riservata per una traccia di diagnostica con centinaia di megabyte di dati al secondo, una dimensione del buffer enorme (da 256 KB a 1024 KB) può ridurre il sovraccarico della CPU.
Nota
Indipendentemente dalle dimensioni del buffer, ETW non può raccogliere eventi superiori a 64 KB.
ETW può modificare l'oggetto BufferSize richiesto verso l'alto in determinati scenari. Ad esempio, quando si scrive un file di traccia in un disco, ETW può aumentare le dimensioni del buffer a più dimensioni del blocco fisico del disco.
Importante
BufferSize è uno dei parametri più importanti per una sessione di traccia. I buffer di grandi dimensioni in genere sprecano memoria e spazio su disco. Le sessioni di traccia con buffer di grandi dimensioni (256 KB o superiori) devono essere usate solo per le indagini diagnostiche o i test, non per la traccia di produzione.
Suggerimento
Non usare BufferSize per controllare l'utilizzo della memoria della sessione di traccia. Selezionare invece le dimensioni del buffer in base alle dimensioni e alla frequenza degli eventi della sessione, quindi usare i parametri MinimumBuffers e MaximumBuffers per modificare l'utilizzo della memoria della sessione.
MinimumBuffers
Numero minimo di buffer riservati per il pool di buffer della sessione di traccia.
ETW può modificare questo valore in determinati scenari.
- Se la modalità di registrazione include il
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGflag , ETW riserva almeno 2 buffer. - Se la modalità di registrazione non include il
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGflag , ETW riserva almeno 2 buffer per ogni processore logico. - Se questo valore è maggiore di un limite determinato da ETW, ETW può ridurlo al limite per evitare un utilizzo eccessivo della memoria.
Per le tracce in modalità file e in tempo reale con frequenze di eventi moderate, la maggior parte degli utenti deve ridurre al minimo l'utilizzo della memoria impostando MinimumBuffers su 0 o su un minimo minimo (ad esempio 4 o 8), consentendo a ETW di regolare il valore verso l'alto in base al numero di processori. ETW riserva il numero minimo (modificato) di buffer all'avvio della traccia. Se i buffer vengono riempiti più rapidamente di quanto possano essere elaborati, ETW tenterà di allocare buffer di addizione, fino al numero specificato da MaximumBuffers.
Per le tracce in modalità buffering (memoria circolare), gli utenti devono impostare il parametro MinimumBuffers in base alla quantità totale di memoria che si desidera riservare per la sessione. Questa operazione viene in genere calcolata in base alla frequenza degli eventi prevista e alla quantità di tempo da coprire per la traccia. Ad esempio, se si prevede una velocità di dati di 16 KB al secondo e si vuole che la traccia registri almeno 60 secondi di dati, è necessario 960 KB. Supponendo che una dimensione del buffer di 32 KB sia impostata su MinimumBuffers su 30 (totale di 960 KB / 32 KB per buffer = 30 buffer). ETW riserva il numero minimo (modificato) di buffer all'avvio della traccia. Quando tutti i buffer vengono riempiti, ETW riutilizza il buffer riempito meno recente per i nuovi eventi. Si noti che ETW non allocherà buffer aggiuntivi (ETW ignora MaximumBuffers per le tracce in modalità buffering).
MaximumBuffers
Numero massimo di buffer da allocare per il pool di buffer della sessione di traccia.
ETW può modificare questo valore in determinati scenari.
- Se questo valore è minore del valore modificato di MinimumBuffers, ETW può aumentarlo a un valore appropriato uguale o maggiore di MinimumBuffers.
- Se questo valore è maggiore di un limite determinato da ETW, ETW può ridurlo al limite.
La maggior parte degli utenti deve iniziare a ottimizzare la sessione impostando MinimumBuffers e MaximumBuffers sullo stesso valore. È quindi possibile aumentare il valore di MaximumBuffers se la traccia elimina gli eventi durante i picchi di frequenza degli eventi.
ETW non può allocare buffer su richiesta se l'evento viene generato da un driver in esecuzione a un numero elevato di runtime di integrazione. Se la sessione di traccia deve registrare eventi da provider in modalità kernel IRQL elevati, potrebbe essere necessario usare un valore più elevato di MinimumBuffers per forzare la preallocazione dei buffer.
Nota
ETW ignora MaximumBuffers per le sessioni in modalità buffering (sessioni che includono la modalità EVENT_TRACE_BUFFERING_MODEdi registrazione). Le sessioni in modalità buffer allocano sempre MinimumBuffers all'inizio della raccolta di traccia e non allocano mai buffer aggiuntivi.
MaximumFileSize
Dimensioni massime del file utilizzato per registrare eventi, in megabyte o zero per nessun limite di dimensioni. In genere, questo membro viene usato per limitare le dimensioni di un file di log circolare quando si imposta LogFileMode su EVENT_TRACE_FILE_MODE_CIRCULAR. Questo membro deve essere impostato su un valore diverso da zero se LogFileMode contiene EVENT_TRACE_FILE_MODE_PREALLOCATEo EVENT_TRACE_FILE_MODE_CIRCULAREVENT_TRACE_FILE_MODE_NEWFILE.
Se si usa l'unità di sistema (l'unità che contiene il sistema operativo) per la registrazione, ETW verifica la presenza di un ulteriore 200 MB di spazio su disco, indipendentemente dal fatto che si usi il parametro di dimensione massima del file. Pertanto, se si specifica 100 MB come dimensione massima del file di traccia nell'unità di sistema, è necessario avere 300 MB di spazio libero nell'unità.
LogFileMode
Flag di registrazione per la sessione di traccia eventi. Questo membro consente di specificare se si desidera che gli eventi siano scritti in un buffer circolare in memoria, in un file di log o in un consumer in tempo reale. È anche possibile usare questo membro per specificare altre caratteristiche di sessione, ad esempio che la sessione è una sessione di logger privato. Per un elenco dei flag possibili, vedere Costanti della modalità di registrazione.
ETW memorizza nel buffer gli eventi per le sessioni in tempo reale quando non sono presenti consumer in tempo reale per la sessione. Si noti che questo buffering è limitato. Se viene raggiunto il limite, i nuovi eventi verranno ignorati e le funzioni di registrazione avranno esito negativo con STATUS_LOG_FILE_FULL. Prima di Windows Vista: Se non è presente alcun consumer in tempo reale, gli eventi vengono eliminati e la registrazione continua.
Non avviare una sessione di registrazione in tempo reale, a meno che un consumer in tempo reale non utilizzerà gli eventi. Una sessione in tempo reale senza consumer sprecherà risorse di sistema (CPU, memoria e spazio su disco per memorizzare nel buffer gli eventi).
Se un consumer inizia a elaborare eventi in tempo reale, gli eventi memorizzati nel buffer vengono utilizzati per primi. Dopo l'utilizzo di tutti gli eventi memorizzati nel buffer, la sessione inizierà a segnalare nuovi eventi.
FlushTimer
Con quale frequenza, in secondi, vengono scaricati tutti i buffer di traccia non vuoti. Il tempo di scaricamento minimo è di 1 secondo.
- Per le sessioni in modalità file: l'impostazione di FlushTimer su 0 disabilita gli scaricamenti basati sul tempo (lo scaricamento si verifica quando il buffer viene riempito, quando la sessione viene arrestata o quando la sessione viene scaricata in modo esplicito). La maggior parte delle tracce in modalità file deve impostare FlushTimer su 0 per evitare lo spazio sprecato nel file di traccia,ad esempio in modo che lo spazio su disco non venga sprecato archiviando per lo più buffer vuoti. È possibile impostare il timer su un valore diverso da zero se è possibile che la traccia non venga chiusa, ad esempio se si vuole assicurarsi di ottenere eventi anche se il sistema si arresta in modo anomalo.
- Per le sessioni in tempo reale: l'impostazione di FlushTimer su 0 abilita un timeout predefinito di 1 secondo. Le sessioni in tempo reale devono impostare il timer di scaricamento in base alla velocità di ricezione dei dati. Si noti che un valore timer superiore ridurrà il sovraccarico della CPU per la traccia. La maggior parte delle tracce in tempo reale deve iniziare con un timer di 5 o 10 secondi e ottimizzare il timer in base alle esigenze.
- Per le sessioni memorizzate nel buffer (circolare in memoria), FlushTimer non viene usato. I dati di traccia verranno scaricati solo su richiesta ,ad esempio scaricati in un file tramite ControlTrace.
EnableFlags
Una sessione del logger di sistema può impostare EnableFlags per indicare quali eventi SystemTraceProvider devono essere inclusi nella traccia.
Nota
EnableFlags è valido solo per i logger di sistema, ad esempio le sessioni di traccia avviate usando il flag della EVENT_TRACE_SYSTEM_LOGGER_MODE modalità logger, il KERNEL_LOGGER_NAME nome della sessione, il SystemTraceControlGuid GUID di sessione o il GUID della GlobalLoggerGuid sessione.
Questo membro può contenere uno o più dei valori seguenti. Oltre agli eventi specificati, a meno che non si specifichi EVENT_TRACE_FLAG_NO_SYSCONFIG, il logger registra anche gli eventi di configurazione hardware in Windows XP e gli eventi di configurazione del sistema in Windows Server 2003 o versione successiva.
EVENT_TRACE_FLAG_ALPC (0x00100000 )
Abilita i tipi di evento ALPC .
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_CSWITCH (0x00000010)
Abilita il tipo di evento Thread seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_DBGPRINT (0x00040000 )
Abilita le chiamate DbgPrint e DbgPrintEx da convertire in eventi ETW.
EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200 )
Abilita il tipo di evento FileIo seguente (è necessario abilitare anche EVENT_TRACE_FLAG_DISK_IO):
EVENT_TRACE_FLAG_DISK_IO (0x00000100 )
Abilita i tipi di evento DiskIo seguenti:
EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400 )
Abilita il tipo di evento DiskIo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_DISPATCHER (0x00000800 )
Abilita il tipo di evento Thread seguente:
Questo valore è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
EVENT_TRACE_FLAG_DPC (0x00000020 )
Abilita il tipo di evento PerfInfo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_DRIVER (0x00800000 )
Abilita i tipi di evento DiskIo seguenti:
- DriverCompleteRequest
- DriverCompleteRequestReturn
- DriverCompletionRoutine
- DriverMajorFunctionCall
- DriverMajorFunctionReturn
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_FILE_IO (0x02000000 )
Abilita i tipi di evento FileIo seguenti:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000 )
Abilita il tipo di evento FileIo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004 )
Abilita il tipo di evento Image seguente:
EVENT_TRACE_FLAG_INTERRUPT (0x00000040 )
Abilita il tipo di evento PerfInfo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_JOB (0x00080000 )
Questo valore è supportato in Windows 10
EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000 )
Abilita il tipo di evento PageFault_V2 seguente:
EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000 )
Abilita il tipo di evento PageFault_V2 seguente:
EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000 )
EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000 )
Non eseguire un'esecuzione di configurazione del sistema.
Questo valore è supportato in Windows 8, Windows Server 2012 e versioni successive.
EVENT_TRACE_FLAG_PROCESS (0x00000001 )
Abilita il tipo di evento Process seguente:
EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008 )
Abilita il tipo di evento Process_V2 seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_PROFILE (0x01000000 )
Abilita il tipo di evento PerfInfo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_REGISTRY (0x00020000 )
Abilita i tipi di evento del Registro di sistema .
EVENT_TRACE_FLAG_SPLIT_IO (0x00200000 )
Abilita i tipi di evento SplitIo .
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080 )
Abilita il tipo di evento PerfInfo seguente:
Questo valore è supportato in Windows Vista e versioni successive.
EVENT_TRACE_FLAG_THREAD (0x00000002 )
Abilita il tipo di evento Thread seguente:
EVENT_TRACE_FLAG_VAMAP (0x00008000 )
Abilita il tipo di evento map e unmap (escluso i file di immagine).
Questo valore è supportato in Windows 8, Windows Server 2012 e versioni successive.
EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000 )
Abilita il tipo di evento PageFault_V2 seguente:
Questo valore è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
DUMMYUNIONNAME
DUMMYUNIONNAME.AgeLimit
Non usato.
Windows 2000: Ritardo di tempo prima che i buffer inutilizzati vengano liberati, in minuti. Il valore predefinito è 15 minuti.
DUMMYUNIONNAME.FlushThreshold
NumberOfBuffers
In output il numero di buffer allocati per il pool di buffer della sessione di traccia eventi.
FreeBuffers
In output il numero di buffer allocati ma inutilizzati nel pool di buffer della sessione di traccia eventi.
EventsLost
In output il numero di eventi che non sono stati registrati.
BuffersWritten
In output il numero di buffer scritti.
LogBuffersLost
Nell'output il numero di buffer che non è stato possibile scrivere nel file di log.
RealTimeBuffersLost
In output il numero di buffer che non è stato possibile recapitare in tempo reale al consumer.
LoggerThreadId
Nell'output l'identificatore del thread per la sessione di traccia eventi.
LogFileNameOffset
Offset (in byte) dall'inizio della memoria allocata della struttura all'inizio della stringa con terminazione nul contenente il nome del file di log.
Il nome del file in genere ha un'estensione .etl . Tutte le cartelle nel percorso devono già esistere (ETW non creerà cartelle per l'utente). Il percorso può essere relativo, assoluto, locale o remoto. Le variabili di ambiente nel percorso non verranno espanse. L'utente deve disporre dell'autorizzazione per scrivere nella cartella.
Il nome del file di log è limitato a 1.024 caratteri. Se si imposta LogFileMode su EVENT_TRACE_PRIVATE_LOGGER_MODE o EVENT_TRACE_FILE_MODE_NEWFILE, assicurarsi di riservare memoria sufficiente per includere l'identificatore di processo che verrà aggiunto al nome file per le sessioni dei loggger privati e il numero sequenziale aggiunto ai file di log creati usando la nuova modalità di log file.
Se non si desidera registrare gli eventi in un file di log, ad esempio se si specifica solo EVENT_TRACE_REAL_TIME_MODE , impostare LogFileNameOffset su 0. Se si specifica solo la registrazione in tempo reale e si specifica anche un offset con un nome di file di log valido, ETW userà il nome del file di log per creare un file di log sequenziale e registrare gli eventi nel file di log oltre a inviare gli eventi ai consumer in tempo reale. ETW crea anche il file di log sequenziale se LogFileMode è 0 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 riservare 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. Vedere le osservazioni per un esempio.
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 accedere ai file con restrizioni, creare una directory padre con gli elenchi di controllo di accesso appropriati.
LoggerNameOffset
Offset (in byte) dall'inizio della memoria allocata della struttura all'inizio della stringa con terminazione nul che contiene il nome della sessione.
Importante
Usare un nome descrittivo per la sessione in modo che la proprietà e l'utilizzo della sessione possano essere determinate dal nome della sessione. Non usare un GUID o un altro valore non descrittivo. Non aggiungere cifre casuali per rendere univoco il nome della sessione. Le sessioni ETW sono una risorsa limitata in modo che il componente non inizi più sessioni. Se la sessione del componente è già in esecuzione all'avvio del componente, il componente deve pulire la sessione orfana anziché creare una seconda sessione.
Il nome della sessione è limitato a 1.024 caratteri. Il nome della sessione è senza distinzione tra maiuscole e minuscole. Il sistema non avvierà una nuova sessione se un'altra sessione con lo stesso nome è già in esecuzione.
Windows 2000: I nomi di sessione sono distinzione tra maiuscole e minuscole. Di conseguenza, le sessioni con nomi diversi solo nel caso siano consentite. Tuttavia, per ridurre la confusione, è necessario assicurarsi che i nomi delle sessioni siano univoci.
Commenti
Quando si alloca la memoria per questa struttura, è necessario allocare 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. È necessario copiare il nome del file di log nell'offset, ma non copiare il nome della sessione nell'offset. La funzione StartTrace copia il nome.
Assicurarsi di inizializzare la memoria per questa struttura su zero prima di impostare i membri. Ad esempio:
typedef struct EventTracePropertyData {
EVENT_TRACE_PROPERTIES Props;
WCHAR LoggerName[128];
WCHAR LogFileName[1024];
} EventTracePropertyData;
EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);
Gli eventi dei provider vengono scritti nei buffer di una sessione. Quando un buffer in un file o una sessione in tempo reale è pieno (o al termine di FlushTimer), la sessione scarica il buffer scrivendo gli eventi in un file di log, recapitandoli a un consumer in tempo reale o entrambi. Se i buffer di una sessione vengono riempiti più velocemente di quanto possano essere scaricati, i nuovi buffer vengono allocati e aggiunti al pool di buffer della sessione, fino a MaximumBuffers. Oltre questo limite, la sessione elimina gli eventi in ingresso fino a quando non diventa disponibile un buffer. Ogni sessione mantiene un record del numero di eventi ignorati (vedere il membro EventsLost ).
Per visualizzare le statistiche della sessione, ad esempio EventsLost durante l'esecuzione della sessione, chiamare la funzione ControlTrace e impostare il parametro ControlCode su EVENT_TRACE_CONTROL_QUERY.
Requisiti
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Intestazione | evntrace.h |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per