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.

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.

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.

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:

1. Inizializzare la memoria per questa struttura su zero.
2. 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.
3. 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_RECORD a ProcessTraceMode. In caso contrario, se si usa EventCallback, impostare EventCallback sull'indirizzo della funzione di callback dell'evento.
4. Se è necessario un callback dopo l'elaborazione di ogni buffer, impostare BufferCallback sull'indirizzo della funzione di callback del buffer.
5. Se si desidera che i dati di timestamp non elaborati originali anziché il timestamp elaborato, aggiungere PROCESS_TRACE_MODE_RAW_TIMESTAMP a ProcessTraceMode.
6. 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.
7. 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.
8. Al termine dell'elaborazione della traccia, chiamare CloseTrace per chiudere l'handle restituito da OpenTrace.

Requisiti

Vedi anche

BufferCallback

EventRecordCallback

OpenTrace