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.

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.

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.

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_BUFFERING flag , ETW riserva almeno 2 buffer.
• Se la modalità di registrazione non include il EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING flag , 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.

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.

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:

  • CSwitch

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

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100 )

  Abilita i tipi di evento DiskIo seguenti:

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400 )

  Abilita il tipo di evento DiskIo seguente:

  • DiskIo_TypeGroup2

  Questo valore è supportato in Windows Vista e versioni successive.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800 )

  Abilita il tipo di evento Thread seguente:

  • ReadyThread

  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:

  • DPC

  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:

  • FileIo_OpEnd

  Questo valore è supportato in Windows Vista e versioni successive.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000 )

  Abilita il tipo di evento FileIo seguente:

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Questo valore è supportato in Windows Vista e versioni successive.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004 )

  Abilita il tipo di evento Image seguente:

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040 )

  Abilita il tipo di evento PerfInfo seguente:

  • ISR

  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:

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000 )

  Abilita il tipo di evento PageFault_V2 seguente:

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000 )

  Abilita i tipi di evento TcpIp e UdpIp .

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

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008 )

  Abilita il tipo di evento Process_V2 seguente:

  • Process_V2_TypeGroup2

  Questo valore è supportato in Windows Vista e versioni successive.

• EVENT_TRACE_FLAG_PROFILE (0x01000000 )

  Abilita il tipo di evento PerfInfo seguente:

  • SampledProfile

  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:

  • SysCallEnter
  • SysCallExit

  Questo valore è supportato in Windows Vista e versioni successive.

• EVENT_TRACE_FLAG_THREAD (0x00000002 )

  Abilita il tipo di evento Thread seguente:

  • Thread_TypeGroup1

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

  • PageFault_VirtualAlloc

  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.

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

Vedi anche

StartTrace

ControlTrace

QueryAllTraces

Costanti della modalità di registrazione

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER