EVENT_TRACE_LOGFILEA struttura (evntrace.h)
La struttura EVENT_TRACE_LOGFILE archivia informazioni su un'origine dati di traccia.
La struttura EVENT_TRACE_LOGFILE viene usata quando si chiama OpenTrace. L'utente fornisce una struttura EVENT_TRACE_LOGFILE con informazioni sull'origine dati di traccia (il nome di un file ETL o il nome di una sessione di logger in tempo reale attivo), i flag di elaborazione delle tracce e le funzioni di callback che riceveranno i dati di traccia. In caso di esito positivo, OpenTrace compila i campi rimanenti della struttura per restituire i dettagli sull'origine dati di traccia.
Quando ProcessTrace elabora un buffer, richiama il buffer definito dall'utente BufferCallback con una struttura EVENT_TRACE_LOGFILE per fornire informazioni sulla sessione di elaborazione eventi e sul buffer.
Sintassi
typedef struct _EVENT_TRACE_LOGFILEA {
LPSTR LogFileName;
LPSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;
Members
LogFileName
Nome del file di log elaborato o NULL se si elaborano dati da una sessione di traccia in tempo reale. Specificare un valore per questo membro se si chiama OpenTrace per utilizzare i dati da un file di log.
Quando si chiama OpenTrace, se LoggerName non è NULL , LogFileName deve essere NULL.
Quando si chiama OpenTrace, l'utente che usa gli eventi deve disporre delle autorizzazioni per leggere il file.
Nota
Il nome del file fornito a OpenTrace tramite il campo LogFileName deve essere il nome completo del file, incluse le suffissi. Alcune API di creazione di file di traccia possono aggiungere in modo automatico un suffisso al nome file specificato dall'utente. Ad esempio, se il controller ha registrato eventi in una sessione privata (il controller imposta il membro LogFileMode di EVENT_TRACE_PROPERTIES su EVENT_TRACE_PRIVATE_LOGGER_MODE quando si chiama StartTrace), il file ETL generato includerà un suffisso ID processo, ad esempio mytrace.etl_123.
Ciò può verificarsi anche se il file è stato creato usando la modalità EVENT_TRACE_FILE_MODE_NEWFILE , nel qual caso il file ETL generato includerà un numero di sequenza.
LoggerName
Nome della sessione di traccia eventi in tempo reale o NULL se si elaborano dati da un file di log. Specificare un valore per questo membro se si chiama OpenTrace per utilizzare i dati da una sessione in tempo reale.
Quando si chiama OpenTrace, se LogFileName non è NULL , LoggerName deve essere NULL.
È possibile utilizzare gli eventi in tempo reale solo se il controller di traccia ha impostato il membro LogFileMode di EVENT_TRACE_PROPERTIES per includere il flag di EVENT_TRACE_REAL_TIME_MODE .
Solo gli utenti con privilegi amministrativi, gli utenti nel gruppo Utenti log prestazioni e le applicazioni in esecuzione come LocalSystem, LocalService, NetworkService possono utilizzare gli eventi in tempo reale. Per concedere a un utente limitato la possibilità di usare gli eventi in tempo reale, aggiungerli al gruppo Utenti log prestazioni o chiamare EventAccessControl.
Windows XP e Windows 2000: Chiunque può usare eventi in tempo reale.
CurrentTime
In output, l'ora corrente, in 100-nanosecondi intervalli da mezzanotte, 1 gennaio 1601.
BuffersRead
In output il numero di buffer elaborati.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Riservato. Non usare.
DUMMYUNIONNAME.ProcessTraceMode
Modalità di elaborazione degli eventi. Le modalità sono definite nel evntcons.h file di intestazione. È possibile specificare una o più delle modalità seguenti:
PROCESS_TRACE_MODE_EVENT_RECORD
Specificare questa modalità se si desidera ricevere eventi nel nuovo formato di EVENT_RECORD (fortemente consigliato). Per ricevere eventi nel nuovo formato, è necessario specificare un callback nel membro EventRecordCallback . Se non si specifica questa modalità, si riceveranno eventi nel formato precedente tramite il callback specificato nel membro EventCallback .
Prima di Windows Vista: Non supportato.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
Per impostazione predefinita, ProcessTrace converte il timestamp dell'evento dal formato non elaborato originale (ora di sistema, tempo QPC o contatore ciclo CPU) in tempo di sistema (intervalli di 100 nanosecondi dalla mezzanotte, 1 gennaio 1601).
Specificare il flag di PROCESS_TRACE_MODE_RAW_TIMESTAMP se non si vuole che il valore del timestamp nel membro TimeStamp di EVENT_HEADER e EVENT_TRACE_HEADER convertito in ora di sistema. Se questo flag viene specificato, ProcessTrace lascerà il valore del timestamp nel formato originale specificato nel membro Wnode.ClientContext di EVENT_TRACE_PROPERTIES.
Prima di Windows Vista: Non supportato.
PROCESS_TRACE_MODE_REAL_TIME
Specificare questa modalità per ricevere eventi in tempo reale. È necessario specificare questa modalità se LoggerName non è NULL.
CurrentEvent
In output, una struttura EVENT_TRACE contenente l'ultimo evento elaborato.
LogfileHeader
In output, una struttura TRACE_LOGFILE_HEADER che contiene informazioni generali sulla sessione e sul computer in cui è stata eseguita la sessione.
BufferCallback
Puntatore alla funzione BufferCallback che riceve statistiche correlate al buffer per ogni scaricamento ETW del buffer. ETW chiama questo callback dopo aver recapitato tutti gli eventi nel buffer. Questo callback è facoltativo.
BufferSize
Nell'output contiene le dimensioni di ogni buffer, in byte.
Filled
Nell'output contiene il numero di byte nel buffer che contengono informazioni valide.
EventsLost
Non usato.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Puntatore alla funzione EventCallback che ETW chiama per ogni evento nel buffer. Questo campo viene usato solo se il campo ProcessTraceMode non include il PROCESS_TRACE_MODE_EVENT_RECORD flag.
Nota
Il campo EventCallback verrà considerato come EventRecordCallback se il campo ProcessTraceMode include il PROCESS_TRACE_MODE_EVENT_RECORD flag. Se l'evento EventCallback riceve dati in modo garbato da ProcessTrace, verificare che il campo ProcessTraceMode non includa il PROCESS_TRACE_MODE_EVENT_RECORD flag.
Suggerimento
Il nuovo codice deve usare EventRecordCallback anziché EventCallback. EventRecordCallback riceve un EVENT_RECORD che contiene informazioni di evento più complete, può essere usato con API di decodifica come TdhGetEventInformation e ha un puntatore al contesto che può essere usato dal callback.
DUMMYUNIONNAME2.EventRecordCallback
Puntatore alla funzione EventRecordCallback che ETW chiama per ogni evento nel buffer. Questo campo viene usato solo se il campo ProcessTraceMode include il PROCESS_TRACE_MODE_EVENT_RECORD flag.
Nota
Il campo EventRecordCallback verrà considerato come EventCallback se il campo ProcessTraceMode non include il PROCESS_TRACE_MODE_EVENT_RECORD flag. Se l'evento EventRecordCallback riceve i dati garbati da ProcessTrace, verificare che il campo ProcessTraceMode includa il PROCESS_TRACE_MODE_EVENT_RECORD flag.
Prima di Windows Vista: Non supportato.
IsKernelTrace
In output, se questo membro è TRUE, la sessione di traccia degli eventi è nt kernel Logger. In caso contrario, si tratta di un'altra sessione di traccia eventi.
Context
Dati di contesto che un consumer può specificare quando si chiama OpenTrace. Se il consumer usa EventRecordCallback per utilizzare gli eventi, ETW imposta il membro UserContext della struttura EVENT_RECORD su questo valore.
Prima di Windows Vista: Non supportato.
Commenti
I consumer di eventi devono:
- Inizializzare la memoria per questa struttura su zero.
- Se si legge da un file ETL, impostare LogFileName sul percorso del file.
In caso contrario, se si legge da una sessione in tempo reale, impostare LoggerName sul nome della sessione e impostare ProcessTraceMode su
PROCESS_TRACE_MODE_REAL_TIME. - Se si usa EventRecordCallback (consigliato), impostare EventRecordCallback sull'indirizzo della funzione di callback dei record eventi, impostare Contesto su un valore da fornire al callback e aggiungere
PROCESS_TRACE_MODE_EVENT_RECORDa ProcessTraceMode. In caso contrario, se si usa EventCallback, impostare EventCallback sull'indirizzo della funzione di callback dell'evento. - Se è necessario un callback dopo l'elaborazione di ogni buffer, impostare BufferCallback sull'indirizzo della funzione di callback del buffer.
- Se si desidera che i dati di timestamp non elaborati originali anziché il timestamp elaborato, aggiungere
PROCESS_TRACE_MODE_RAW_TIMESTAMPa ProcessTraceMode. - Chiamare OpenTrace. Si noti che, se ha esito positivo, la funzione OpenTrace compila i membri di questa struttura con informazioni dall'origine dati di traccia.
- Chiamare ProcessTrace con l'handle restituito da OpenTrace.
- ProcessTrace richiama la funzione di callback dell'evento per ogni evento.
- ProcessTrace richiama la funzione di callback del buffer (se specificato) dopo aver completato ogni buffer e includerà un'istanza della struttura EVENT_TRACE_LOGFILE con informazioni sullo stato dell'elaborazione della traccia.
- Al termine dell'elaborazione della traccia, chiamare CloseTrace per chiudere l'handle restituito da OpenTrace.
Nota
L'intestazione evntrace.h definisce EVENT_TRACE_LOGFILE come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | evntrace.h |