EVENT_DESCRIPTOR struttura (evntprov.h)

Articolo
02/26/2024

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;

Members

Id

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

Per ETW basato sul manifesto, la combinazione Provider.DecodeGuid + Event.Id + Event.Version deve identificare in modo univoco un evento, ad esempio 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 (ad esempio TraceLogging), il campo ID in genere non è significativo e normalmente verrà impostato su 0. Gli eventi TraceLogging vengono generalmente 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 alla definizione di un evento con un ID specifico. Tutti gli eventi con un determinato ID devono avere una semantica simile, ma una modifica nella versione può essere usata 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 di eventi speciali.

Gli eventi basati sul manifesto usano normalmente il canale 0.
Gli eventi basati su TraceLogging usano normalmente il canale 11.
Gli eventi basati sul manifesto con i tratti del provider usano normalmente il canale 12.
Altri valori del canale possono essere usati con gli eventi del registro eventi.

I valori del canale 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 (trattato come canale 0) e possono essere fornite 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 primario per filtrare gli eventi. Assegnare sempre un livello significativo (non 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 su livello. Gli eventi non devono usare questo livello.
CRITICO (1)	Errore critico
ERRORE (2)	Errore
AVVISO (3)	Avviso
INFO (4)	Informativo
VERBOSE (5)	Dettagliato

Le sessioni della raccolta eventi possono impostare un filtro a livello, ovvero che 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 su 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 assegnati alla semantica definita dall'utente.

Gli opcode 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 qualsiasi numero 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 agli ID attività.

Task

Numero a 16 bit usato 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, utilizzata per indicare che non è stato assegnato alcun codice attività speciale all'evento. Il manifesto ETW supporta l'assegnazione di stringhe localizzate a ogni codice attività. Il codice 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 a un set di categorie di eventi.

Importante

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

I primi 16 bit della parola chiave (0xFFFF000000000000 bitmask) 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 bit 0x1) come categoria "I/O", bit 1 (maschera bit 0x2) per essere la categoria "UI" e bit 2 (0x4 maschera bit) per essere la categoria "misurazione delle prestazioni". In questo scenario, un evento potrebbe avere la parola chiave impostata su 0x5, che indica che l'evento si trova sia nelle categorie "I/O" che "misurazione delle prestazioni".

Le sessioni della raccolta eventi possono impostare filtri MatchAnyKeyword e MatchAllKeyword, ovvero che 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 pari a 0 ignorano normalmente il filtro basato su parole chiave.

Suggerimento

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

Commenti

Questa struttura viene usata 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 eventuali 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 implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWriteEx e EventUnregister. Ad esempio, è possibile scrivere un manifesto evento e quindi usare il compilatore 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 si riferiscono al manifesto della strumentazione, vedere gli attributi del tipo complesso EventDefinitionType .

Questa struttura è inclusa nella struttura di EVENT_HEADER restituita con il record di eventi quando si usano eventi usando ProcessTrace con il callback EventRecordCallback .

Nota

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

Requisiti

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)