struttura EVENT_DESCRIPTOR (evntprov.h)

Articolo
03/05/2025

La struttura EVENT_DESCRIPTOR contiene informazioni (metadati) su un evento ETW.

Sintassi

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

Membri

Id

Numero a 16 bit usato per identificare gli eventi basati su manifesto.

Per ETW basato su manifesto, la combinazione Provider.DecodeGuid + Event.Id + Event.Version deve identificare in modo univoco un evento, ovvero tutti gli eventi con lo stesso DecodeGuid, ID e Version devono avere lo stesso set di campi senza modifiche nei nomi dei campi, nei tipi di campo o nell'ordinamento dei campi.

Per ETW senza manifesto (ad esempio TraceLogging), il campo ID in genere non è significativo e in genere sarà impostato su 0. Gli eventi TraceLogging sono in genere identificati dal nome dell'evento, non dall'ID evento.

Version

Numero a 8 bit usato per specificare la versione di un evento basato su manifesto.

La versione indica una revisione della definizione di un evento con un ID specifico. Tutti gli eventi con un id specificato devono avere una semantica simile, ma è possibile usare una modifica della versione per indicare una modifica secondaria dei dettagli dell'evento, ad esempio una modifica al tipo di un campo o l'aggiunta di un nuovo campo.

Channel

Numero a 8 bit usato per abilitare l'elaborazione speciale di eventi.

Gli eventi basati su manifesto usano normalmente il canale 0.
Gli eventi basati su TraceLogging usano normalmente channel 11.
Gli eventi basati su manifesto con tratti del provider usano normalmente il canale 12.
È possibile usare altri valori del canale con gli eventi del registro eventi.

I valori dei canali inferiori a 16 sono riservati per l'uso da parte di Microsoft per abilitare un trattamento speciale dal runtime ETW. I valori del canale 16 e versioni successive verranno ignorati dal runtime ETW (considerato lo stesso canale 0) e possono essere forniti semantiche definite dall'utente.

Level

Numero a 8 bit usato per descrivere la gravità o l'importanza di un evento.

Importante

Il livello di evento è un mezzo principale per filtrare gli eventi. Assegnare sempre un livello significativo (diverso da zero) a ogni evento.

I valori di livello da 0 a 5 sono definiti da Microsoft (vedere evntrace.h e winmeta.h). I valori di livello da 6 a 15 sono riservati. I valori di livello da 16 a 255 possono essere definiti dal provider di eventi.

Valore	Semantica
LOG_ALWAYS (0)	L'evento ignora il filtro degli eventi basato sul livello. Gli eventi non devono usare questo livello.
CRITICAL (1)	Errore critico
ERRORE (2)	Errore
AVVISO (3)	Avvertimento
INFO (4)	Informativo
VERBOSE (5)	Prolisso

Le sessioni di raccolta eventi possono impostare un filtro a livello, ovvero la sessione accetterà solo gli eventi in cui eventDescriptor.Level <= session.LevelFilter. Si noti che gli eventi con un livello pari a 0 ignorano il filtro basato sul livello.

Opcode

Numero a 8 bit usato per contrassegnare gli eventi con semantica speciale. Questo valore può essere usato dai decodificatori di traccia per organizzare e correlare gli eventi. I valori opcode riconosciuti a livello globale sono definiti in winmeta.h. La maggior parte degli eventi usa INFO (0). I valori opcode da 10 a 239 possono essere forniti dalla semantica definita dall'utente.

Opcodes START (1) e STOP (2) vengono usati per indicare l'inizio e la fine delle attività ETW come indicato di seguito:

Generare un ID attività univoco all'interno della traccia, in genere usando EventActivityIdControl.
Scrivere un evento iniziale con opcode = START, ID attività = l'ID attività generato e l'ID attività correlato = l'ID attività padre (se presente).
Scrivere un numero qualsiasi di eventi di informazioni sull'attività con opcode = INFO, ID attività = ID attività generato.
Scrivere un evento di arresto con opcode = STOP, ID attività = ID attività generato.

Gli strumenti di decodifica della traccia possono quindi organizzare questi eventi in gruppi in base ai relativi ID attività.

Task

Numero a 16 bit utilizzato per annotare un evento o un gruppo correlato di eventi.

Il codice dell'attività evento può essere usato per qualsiasi scopo definito dal provider. Il codice attività 0 è l'impostazione predefinita, usata per indicare che all'evento non è stato assegnato codice attività speciale. Il manifesto ETW supporta l'assegnazione di stringhe localizzate a ogni codice dell'attività. Il codice dell'attività può essere usato per raggruppare gli eventi in categorie o per associare semplicemente una stringa "task" localizzata a ogni evento.

Keyword

Maschera a 64 bit usata per indicare l'appartenenza di un evento in un set di categorie di eventi.

Importante

La parola chiave event è un mezzo principale per filtrare gli eventi. Assegnare sempre una parola chiave significativa (non zero) a ogni evento.

I primi 16 bit della parola chiave (maschera di bit 0xFFFF000000000000) sono definiti da Microsoft. I 48 bit bassi della parola chiave (maschera di bit 0x0000FFFFFFFFFFFF) sono definiti dal provider di eventi. Ad esempio, il provider di eventi potrebbe definire bit 0 (maschera di bit 0x1) come categoria "I/O", bit 1 (maschera di bit 0x2) come categoria "interfaccia utente" e bit 2 (maschera di bit 0x4) come categoria "misurazione delle prestazioni". In questo scenario, un evento potrebbe avere la parola chiave impostata su 0x5, a indicare che l'evento si trova nelle categorie "I/O" e "misurazione delle prestazioni".

Le sessioni di raccolta eventi possono impostare filtri MatchAnyKeyword e MatchAllKeyword, ovvero la sessione accetterà solo gli eventi in cui l'espressione seguente è true:

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

Si noti che gli eventi con una parola chiave 0 in genere ignorano il filtro basato su parole chiave.

Mancia

A partire da Windows 10 versione 1507 e successive, una sessione di raccolta eventi può escludere gli eventi con la parola chiave impostata su 0. A tale scopo, includere il flag EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 nel campo EnableProperty della struttura ENABLE_TRACE_PARAMETERS passata a EnableTraceEx2 durante la configurazione del provider.

Osservazioni

Questa struttura viene utilizzata quando si chiama EventWrite per scrivere l'evento. È anche possibile usarlo quando si chiama EventEnabled per determinare se l'evento deve essere generato ,ad esempio per determinare se i listener di eventi sono interessati all'evento.

Nota

La maggior parte dei provider di eventi non userà direttamente EVENT_DESCRIPTOR. La maggior parte dei provider di eventi viene invece implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWriteExe EventUnregister. Ad esempio, è possibile scrivere un manifesto eventi e quindi usare il del compilatore di messaggi per generare codice C/C++ per gli eventi oppure è possibile usare TraceLogging per evitare la necessità di un manifesto. Per informazioni dettagliate sul modo in cui i membri di questa struttura sono correlati al manifesto di strumentazione, vedere gli attributi del EventDefinitionType tipo complesso.

Questa struttura è inclusa nella struttura EVENT_HEADER restituita con il record dell'evento quando si utilizzano eventi usando ProcessTrace con il callback EventRecordCallback.

Nota

Quando si elaborano eventi basati su MOF, l'identità dell'evento è contenuta nel campo opcode, non nel campo id .

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 [solo app desktop]
intestazione	evntprov.h (include Evntprov.h)