Funzione EventWriteEx (evntprov.h)

Articolo
02/26/2024

Scrive un evento ETW con un ID attività, un ID attività correlato facoltativo, filtri di sessione e opzioni speciali.

Sintassi

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parametri

[in] RegHandle

Handle di registrazione del provider. L'handle proviene da EventRegister. L'evento generato userà il ProviderId associato all'handle.

[in] EventDescriptor

EVENT_DESCRIPTOR con informazioni sugli eventi (metadati) inclusi ID, Versione, Livello, Parola chiave, Canale, Opcode e Attività.

Importante

ProviderId, Level e Keyword sono i mezzi principali per filtrare gli eventi. Altri tipi di filtro sono possibili, ma hanno un sovraccarico molto maggiore. Assegnare sempre un livello diverso da zero e una parola chiave a ogni evento.

[in] Filter

Valore maschera a 64 bit. Ogni bit del set indica che questo evento deve essere escluso da una determinata sessione di traccia.

Il parametro Filter viene usato con i provider di eventi che eseguono filtri di eventi personalizzati in base a FilterData da EnableCallback.

Impostare Filter su zero se non si supportano filtri di eventi personalizzati o se l'evento deve essere scritto in tutte le sessioni di traccia. In caso contrario, impostare Filtro sull'OR bit per bit degli identificatori di sessioni che non devono ricevere l'evento.

[in] Flags

Impostare Flag su zero per la gestione normale degli eventi.

Impostare Flag su una combinazione di valori EVENT_WRITE_FLAG per la gestione degli eventi speciali.

EVENT_WRITE_FLAG_INPRIVATE (0x2 )

Indica che questo evento deve essere escluso da qualsiasi logger che ha impostato l'opzione EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE .

[in, optional] ActivityId

Puntatore facoltativo a un ID attività a 128 bit per questo evento. Se non è NULL, EventWriteEx userà il valore specificato per l'ID attività dell'evento. Se è NULL, EventWriteEx userà l'ID attività del thread corrente.

Gli strumenti di elaborazione delle tracce possono usare l'ID attività dell'evento per organizzare gli eventi in gruppi denominati attività. Per altre informazioni sull'ID attività, vedere EventActivityIdControl.

[in, optional] RelatedActivityId

Puntatore facoltativo a un ID attività a 128 bit padre dell'attività di questo evento. Se non è NULL, EventWriteEx userà il valore specificato per l'ID attività correlato dell'evento. Se è NULL, l'evento non avrà un ID attività correlato. L'ID attività correlato viene in genere impostato sull'evento START dell'attività (il primo evento dell'attività, registrato con Opcode = START).

Gli strumenti di elaborazione delle tracce possono usare l'ID attività correlata dell'evento per determinare la relazione tra le attività, ad esempio l'attività correlata è l'elemento padre dell'attività appena avviata. Per altre informazioni sull'ID attività correlato, vedere EventActivityIdControl.

[in] UserDataCount

Numero di strutture EVENT_DATA_DESCRIPTOR in UserData. Il numero massimo è 128.

[in, optional] UserData

Matrice di strutture UserDataCountEVENT_DATA_DESCRIPTOR che descrivono i dati da includere nell'evento. UserData può essere NULL se UserDataCount è zero.

Ogni EVENT_DATA_DESCRIPTOR descrive un blocco di memoria da includere nell'evento. I blocchi specificati verranno concatenati in ordine senza spaziatura interna o allineamento per formare il contenuto dell'evento. Se si usa la decodifica basata su manifesto, il contenuto dell'evento deve corrispondere al layout specificato nel modello associato all'evento nel manifesto.

Valore restituito

Restituisce ERROR_SUCCESS in caso di esito positivo o di codice di errore. I codici di errore possibili includono quanto segue:

ERROR_INVALID_PARAMETER: uno o più parametri non sono validi.
ERROR_INVALID_HANDLE: l'handle di registrazione del provider non è valido.
ERROR_ARITHMETIC_OVERFLOW: la dimensione dell'evento è maggiore del massimo consentito (64 KB - intestazione).
ERROR_MORE_DATA: la dimensione del buffer della sessione è troppo piccola per l'evento.
ERROR_NOT_ENOUGH_MEMORY: si verifica quando i buffer riempiti tentano di scaricare su disco, ma le operazioni di I/O del disco non vengono eseguite abbastanza velocemente. Ciò si verifica quando il disco è lento e il traffico degli eventi è elevato. Alla fine, non sono presenti più buffer gratuiti (vuoti) e l'evento viene eliminato.
STATUS_LOG_FILE_FULL: il file di riproduzione in tempo reale è pieno. Gli eventi non vengono registrati nella sessione finché un consumer in tempo reale non utilizza gli eventi dal file di riproduzione.

Il codice di errore è destinato principalmente all'uso negli scenari di debug e diagnostica. La maggior parte del codice di produzione deve continuare a essere eseguita e continuare a segnalare gli eventi anche se non è stato possibile scrivere un evento ETW, pertanto le compilazioni di versione devono in genere ignorare il codice di errore.

Commenti

La maggior parte dei provider di eventi non chiamerà direttamente EventWriteEx . La maggior parte dei provider di eventi viene invece implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWriteEx e EventUnregister. Ad esempio, è possibile scrivere un manifesto dell'evento e quindi usare il compilatore di messaggi per generare codice C/C++ per gli eventi oppure è possibile usare TraceLogging per evitare la necessità di un manifesto.

EventWriteEx instrada l'evento alle sessioni di traccia appropriate in base al ProviderId (determinato da RegHandle), Level, Keyword e altre caratteristiche dell'evento. Se nessuna sessione di traccia registra questo evento, questa funzione non eseguirà alcuna operazione e restituirà ERROR_SUCCESS.

Per ridurre l'impatto sulle prestazioni degli eventi non registrati da alcuna sessione di traccia, è possibile chiamare EventEnabled per determinare se una sessione di traccia registra l'evento prima di preparare i dati e chiamare EventWriteEx.

Un provider può definire filtri usati da una sessione per filtrare gli eventi in base ai dati dell'evento. I filtri principali sono basati su parole chiave e di livello. I provider di eventi possono supportare filtri più complessi. Il provider di eventi può ricevere informazioni sul filtro dal parametro FilterData di EnableCallback. Il provider può valutare il filtro e usare il parametro Filter di EventWriteEx per indicare che determinate sessioni di traccia non hanno superato il filtro e pertanto non devono ricevere l'evento.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 R2 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	evntprov.h
Libreria	Advapi32.lib
DLL	Advapi32.dll