PEVENT_RECORD_CALLBACK funzione di callback (evntrace.h)

Articolo
08/23/2023

I consumer implementano questo callback per ricevere eventi da una sessione di elaborazione di traccia.

Il tipo PEVENT_RECORD_CALLBACK definisce un puntatore a questa funzione di callback. EventRecordCallback è un segnaposto per il nome della funzione definita dall'applicazione.

Sintassi

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

Parametri

[in] EventRecord

Puntatore a una struttura EVENT_RECORD contenente le informazioni sull'evento.

Valore restituito

nessuno

Osservazioni

Per specificare la funzione che ETW chiama per recapitare gli eventi, impostare i membri EventRecordCallback, Context e ProcessTraceMode della struttura EVENT_TRACE_LOGFILE passati alla funzione OpenTrace .

Impostare EventRecordCallback sull'indirizzo della funzione di callback.
Impostare Context su un valore che deve essere incluso nel campo UserContext di ogni EVENT_RECORD fornito al callback.
Impostare ProcessTraceMode sui flag da utilizzare durante l'elaborazione della traccia. Per usare EventRecordCallback, è necessario includere PROCESS_TRACE_MODE_EVENT_RECORD nel valore ProcessTraceMode .

Nota

Se la funzione EventRecordCallback riceve dati in modo non chiaro da ProcessTrace, controllare due volte i flag specificati nel ProcessTraceMode campo della EVENT_TRACE_LOGFILE struttura fornita a OpenTrace. EVENT_TRACE_LOGFILEI campi EventCallback e EventRecordCallback sono membri sovrapposti di un'unione. Se il ProcessTraceMode campo include il flag, ProcessTrace richiamerà il PROCESS_TRACE_MODE_EVENT_RECORD callback usando la firma della funzione EventRecordCallback. In caso contrario, ProcessTrace richiamerà il callback usando la firma della funzione EventCallback .

Dopo aver usato OpenTrace per creare la sessione di elaborazione della traccia, chiamare la funzione ProcessTrace per iniziare a ricevere gli eventi.

Quando ProcessTrace inizia a elaborare gli eventi da una traccia, può richiamare il callback con uno o più eventi sintetici che contengono dati sulla traccia (metadati) anziché i dati degli eventi registrati. Questi eventi sintetici hanno EventHeader.ProviderId impostato su EventTraceGuid e EventHeader.EventDescriptor.Opcode in base al contenuto dell'evento sintetico. Ad esempio, il primo evento di ogni file di traccia sarà un evento sintetico con Opcode 0 contenente TRACE_LOGFILE_HEADER informazioni.

Tutti gli altri eventi ricevuti contengono dati di evento specifici del provider. Utilizzare i membri EventHeader.ProviderId e EventHeader.EventDescriptor di EVENT_RECORD per determinare il tipo di evento ricevuto.

Se l'evento proviene da un provider noto e si conosce il layout dei dati, è possibile usare il proprio sistema per decodificare gli eventi.
Se il campo EventHeader.Flags include il EVENT_HEADER_FLAG_TRACE_MESSAGE flag , l'evento è un messaggio WPP. Se sono disponibili le informazioni di decodifica appropriate (file TMF o PDB), l'evento può essere decodificato usando TdhGetProperty o TdhGetWppProperty.
In caso contrario, l'evento può essere un evento basato su MOF, basato su manifesto o TraceLogging. Se le informazioni di decodifica appropriate sono disponibili, l'evento può essere decodificato usando TdhGetEventInformation.
- Se l'evento usa la decodifica basata su MOF, TdhGetEventInformation cercherà le informazioni di decodifica degli eventi nell'archivio dati WMI del sistema.
- Se l'evento usa la decodifica basata su manifesto, TdhGetEventInformation cercherà informazioni sulla decodifica degli eventi nei manifesti registrati del sistema o nei manifesti o nei file binari caricati nel contesto di decodifica per processo da TdhLoadManifest o TdhLoadManifestFromBinary.
- Se l'evento usa la decodifica basata su TraceLogging, TdhGetEventInformation userà le informazioni di decodifica dall'interno dell'evento.

Nella maggior parte dei casi, gli eventi verranno recapitati al callback nell'ordine in cui si sono verificati (ordine di timestamp). Tuttavia, in determinate circostanze, gli eventi potrebbero non essere recapitati nell'ordine originale.

Se la traccia usa l'ora di sistema per il timestamp della sessione (ad esempio, la sessione di traccia è stata avviata con properties.Wnode.ClientContext impostato su 2) e l'orologio di sistema viene regolato all'indietro mentre la sessione raccoglie gli eventi, è possibile che alcuni eventi vengano recapitati in ordine non ordinato. Per evitare questo problema, impostare ClientContext su 0 per ottenere il timestamp predefinito (ora QPC).
Se la traccia viene raccolta usando timestamp da un orologio impreciso, gli eventi con lo stesso timestamp da CPU diverse potrebbero essere recapitati in ordine non corretto. Questa situazione si verifica più frequentemente quando la traccia usa l'ora di sistema per il timestamp della sessione perché il tempo di sistema si verifica. Questo problema può essere evitato avviando la sessione con EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING nei flag LogFileMode , anche se questo può avere un impatto negativo significativo sulle prestazioni di traccia. A partire da Windows 10: il tipo di orologio dell'ora di sistema usa GetSystemTimePreciseAsFileTime per ridurre la probabilità di questo problema.
Se la traccia è danneggiata, è stata generata usando API di basso livello che non gestiscono le regole di timestamp previste all'interno del file o usa le opzioni di override del timestamp durante la scrittura di eventi, alcuni eventi potrebbero essere recapitati in ordine non ordinato.

Dettagli tecnici: Gli eventi vengono archiviati nei buffer. Ogni buffer viene assegnato a un flusso di buffer, in genere un flusso per ogni CPU. L'implementazione di ProcessTrace presuppone che tutti gli eventi in un buffer siano ordinati in base al timestamp e che ogni buffer contenga eventi per un singolo intervallo di tempo che non sovrappone l'intervallo di qualsiasi altro buffer nel flusso del buffer. Quando queste ipotesi non vengono soddisfatte, ProcessTracepuò recapitare eventi non ordinati.

Quando una sessione di raccolta di tracce in tempo reale non ha sessioni di elaborazione di traccia associate, gli eventi raccolti verranno memorizzati nel buffer dal sistema fino a quando il buffer non è pieno. Quando una sessione di elaborazione di traccia si connette a una sessione di raccolta di tracce in tempo reale, la sessione di elaborazione di traccia riceverà gli eventi sintetici per la sessione, quindi gli eventi memorizzati nel buffer e inizierà a ricevere gli eventi in tempo reale appena generati. Se una seconda sessione di elaborazione in tempo reale si connette alla stessa sessione di raccolta di tracce, riceverà gli eventi sintetici e gli eventi in tempo reale appena generati (la seconda sessione di elaborazione della traccia non riceverà eventi meno recenti).

Importante

Quando si elaborano gli eventi da una sessione in tempo reale, se il callback di elaborazione richiede troppo tempo per elaborare ogni evento e gli eventi arrivano troppo rapidamente, il callback di elaborazione richiede troppo tempo. Il sistema memorizza nel buffer gli eventi per evitare la perdita di dati, ma questo aumenta l'utilizzo delle risorse di sistema ,ad esempio l'utilizzo della memoria e del disco. Evitare questo problema usando filtri di sessione (ad esempio filtri di livello e parole chiave per ogni provider) per ridurre la frequenza degli eventi in ingresso, eseguendo il filtro anticipato nel callback per ignorare gli eventi che non richiedono l'elaborazione completa e ottimizzando il callback per restituire il più rapidamente possibile per evitare di bloccare il thread di elaborazione.

Per altri dettagli sull'interpretazione dei dati dell'evento, vedere Utilizzo di eventi e recupero dei dati degli eventi tramite TDH.

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	evntrace.h