struttura EVENT_TRACE_LOGFILEW (evntrace.h)

La struttura EVENT_TRACE_LOGFILE archivia informazioni su un'origine dati di traccia.

La struttura EVENT_TRACE_LOGFILE viene utilizzata 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 logger attiva in tempo reale), 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 BufferCallback definito dall'utente con una struttura EVENT_TRACE_LOGFILE per fornire informazioni sulla sessione di elaborazione eventi e sul buffer.

Sintassi

typedef struct _EVENT_TRACE_LOGFILEW {
  LPWSTR                        LogFileName;
  LPWSTR                        LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;

Members

LogFileName

Nome del file di log da elaborare 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 è diverso da NULL , LogFileName deve essere NULL.

Quando si chiama OpenTrace, l'utente che utilizza 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 è diverso da 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 EVENT_TRACE_REAL_TIME_MODE .

Solo gli utenti con privilegi amministrativi, gli utenti nel gruppo Performance Log Users e le applicazioni in esecuzione come LocalSystem, LocalService, NetworkService possono utilizzare gli eventi in tempo reale. Per concedere a un utente con restrizioni la possibilità di utilizzare gli eventi in tempo reale, aggiungerli al gruppo Performance Log Users o chiamare EventAccessControl.

Windows XP e Windows 2000: Chiunque può utilizzare eventi in tempo reale.

CurrentTime

In output, l'ora corrente, in intervalli di 100 nanosecondi dalla mezzanotte del 1° gennaio 1601.

BuffersRead

Nell'output il numero di buffer elaborati.

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

Riservato. Non usare.

DUMMYUNIONNAME.ProcessTraceMode

Modalità per l'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 del ciclo della CPU) in tempo di sistema (intervalli di 100 nanosecondi dalla mezzanotte del 1° gennaio 1601).

  Specificare il flag PROCESS_TRACE_MODE_RAW_TIMESTAMP se non si desidera 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 dal controller 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

Nell'output, una struttura EVENT_TRACE che contiene l'ultimo evento elaborato.

LogfileHeader

Nell'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 il recapito di 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 utilizzato 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 utilizzato solo se il campo ProcessTraceMode include il PROCESS_TRACE_MODE_EVENT_RECORD flag .

Prima di Windows Vista: Non supportato.

IsKernelTrace

Nell'output, se questo membro è TRUE, la sessione di traccia eventi è il Logger del kernel NT. 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 utilizza 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 (scelta consigliata), impostare EventRecordCallback sull'indirizzo della funzione di callback del record eventi, impostare Context 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 timestamp non elaborati originali anziché il timestamp elaborato, aggiungere PROCESS_TRACE_MODE_RAW_TIMESTAMP a ProcessTraceMode.
6. Chiama OpenTrace. Si noti che, se ha esito positivo, la funzione OpenTrace compilerà i membri di questa struttura con informazioni provenienti dall'origine dati di traccia.
7. Chiamare ProcessTrace con l'handle restituito da OpenTrace.
   • ProcessTrace richiamerà la funzione di callback dell'evento per ogni evento.
   • ProcessTrace richiamerà 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 di 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