Funzione TraceEventInstance (evntrace.h)

Articolo
08/23/2023

Un provider di eventi basato su RegisterTraceGuids ("classico") usa la funzione TraceEventInstance per inviare un evento strutturato a una sessione di traccia eventi con un identificatore di istanza.

L'evento usa un identificatore di istanza per associare l'evento a una transazione. Questa funzione può essere usata anche per tracciare relazioni gerarchici tra eventi correlati.

Sintassi

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Parametri

[in] TraceHandle

Gestire la sessione di traccia eventi che registra l'istanza dell'evento. Il provider ottiene l'handle quando chiama la funzione GetTraceLoggerHandle nell'implementazione di ControlCallback .

[in] EventTrace

Puntatore a una struttura EVENT_INSTANCE_HEADER . I dati specifici dell'evento vengono facoltativamente aggiunti alla struttura. L'evento più grande che è possibile registrare è 64K. È necessario specificare i valori per i membri seguenti della struttura EVENT_INSTANCE_HEADER .

Dimensione
Flag
RegHandle

A seconda della complessità delle informazioni fornite dal provider, è anche consigliabile specificare i valori per i membri seguenti.

Class.Type
Class.Level

Per tracciare relazioni gerarchico tra eventi correlati, impostare anche il membro ParentRegHandle .

[in] InstInfo

Puntatore a una struttura EVENT_INSTANCE_INFO , che contiene l'handle di registrazione per questa classe di traccia evento e l'identificatore dell'istanza. Usare la funzione CreateTraceInstanceId per inizializzare la struttura.

[in] ParentInstInfo

Puntatore a una struttura EVENT_INSTANCE_INFO , che contiene l'handle di registrazione per la classe di traccia dell'evento padre e il relativo identificatore di istanza. Usare la funzione CreateTraceInstanceId per inizializzare la struttura. Impostare su NULL se non si traccia una relazione gerarchica.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. Di seguito sono riportati alcuni errori comuni e le relative cause.

ERROR_INVALID_FLAGS

Il membro Flag del EVENT_INSTANCE_HEADER non contiene WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

Memoria insufficiente per completare la chiamata alla funzione. Le cause per questo codice di errore sono descritte nella sezione Osservazioni seguenti.
ERROR_INVALID_PARAMETER

Una delle seguenti condizioni è vera:
- EventTrace è NULL.
- pInstInfo è NULL.
- I membri di pInstInfo sono NULL.
- TraceHandle è NULL.
- Il membro Size del EVENT_INSTANCE_HEADER non è corretto.
ERROR_INVALID_HANDLE

TraceHandle non è valido o specifica l'handle di sessione NT Kernel Logger.
ERROR_NOT_ENOUGH_MEMORY

Sono stati esauriti i buffer liberi in cui scrivere per la sessione. Questa situazione può verificarsi in caso di frequenze di evento elevate perché il sottosistema del disco è sovraccarico o il numero di buffer è insufficiente. Anziché bloccare fino a quando non diventano disponibili più buffer, TraceEvent elimina l'evento.

Windows 2000 e Windows XP: Non supportato.
ERROR_OUTOFMEMORY

L'evento viene rimosso perché, anche se il pool di buffer non ha raggiunto le dimensioni massime, la memoria disponibile non è sufficiente per allocare un buffer aggiuntivo e non è disponibile alcun buffer per ricevere l'evento.
ERROR_MORE_DATA

I dati di un singolo evento non possono estendersi su più buffer. Un evento di traccia è limitato alle dimensioni del buffer della sessione di traccia eventi meno le dimensioni della struttura EVENT_INSTANCE_HEADER .

Commenti

I provider ETW basati su MOF chiamano questa funzione.

Nota

La maggior parte degli sviluppatori non chiamerà questa funzione. Questa API supporta ETW basato su MOF, ma L'ETW basato su MOF è deprecato a favore di ETW basato su manifesto. Inoltre, la maggior parte dei provider basati su MOF usa funzioni wrapper generate da MC.exe anziché chiamare direttamente le API ETW.

Prima che il provider possa chiamare questa funzione, il provider

Deve chiamare la funzione RegisterTraceGuids per registrare se stessa e la classe di traccia eventi.
Deve chiamare la funzione CreateTraceInstanceId per creare un identificatore di istanza per la classe di traccia eventi registrata.
Deve essere abilitato. Un controller chiama la funzione EnableTrace per abilitare un provider.

L'evento viene scritto in un file di log, inviato ai consumer di traccia eventi in tempo reale o entrambi. Il membro LogFileMode della struttura EVENT_TRACE_PROPERTIES passato a StartTrace definisce la posizione in cui viene inviato l'evento.

Gli eventi di traccia vengono scritti nell'ordine in cui si verificano.

Per tracciare eventi non correlati, usare la funzione TraceEvent .

Windows XP: Non funziona correttamente.

Esempio

Per un esempio di generazione di set correlati di eventi tramite CreateTraceInstanceId e TraceEventInstance, vedere Traccia delle istanze degli eventi.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	evntrace.h
Libreria	Advapi32.lib
DLL	Advapi32.dll