estrutura EVENT_DESCRIPTOR (evntprov.h)

Artigo
02/26/2024

A estrutura EVENT_DESCRIPTOR contém informações (metadados) sobre um evento ETW.

Sintaxe

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

Membros

Id

Um número de 16 bits usado para identificar eventos baseados em manifesto.

Para ETW baseado em manifesto, a combinação Provider.DecodeGuid + Event.Id + Event.Version deve identificar exclusivamente um evento, ou seja, todos os eventos com o mesmo DecodeGuid, Id e Version devem ter o mesmo conjunto de campos sem alterações em nomes de campo, tipos de campo ou ordenação de campo.

Para ETW sem manifesto (ou seja, TraceLogging), o campo Id geralmente não é significativo e normalmente será definido como 0. Os eventos traceLogging geralmente são identificados pelo nome do evento, não pela ID do evento.

Version

Um número de 8 bits usado para especificar a versão de um evento baseado em manifesto.

A versão indica uma revisão para a definição de um evento com uma ID específica. Todos os eventos com uma determinada ID devem ter semântica semelhante, mas uma alteração na versão pode ser usada para indicar uma pequena modificação dos detalhes do evento, por exemplo, uma alteração no tipo de um campo ou a adição de um novo campo.

Channel

Um número de 8 bits usado para habilitar o processamento de eventos especiais.

Eventos baseados em manifesto normalmente usam o canal 0.
Os eventos baseados em TraceLogging normalmente usam o canal 11.
Eventos baseados em manifesto com características de provedor normalmente usam o canal 12.
Outros valores de canal podem ser usados com eventos do Log de Eventos.

Os valores de canal abaixo de 16 são reservados para uso pela Microsoft para habilitar o tratamento especial pelo runtime do ETW. Os valores de canal 16 e superiores serão ignorados pelo runtime do ETW (tratado da mesma forma que o canal 0) e poderão receber semântica definida pelo usuário.

Level

Um número de 8 bits usado para descrever a gravidade ou a importância de um evento.

Importante

O nível de evento é um meio principal para filtrar eventos. Sempre atribua um nível significativo (diferente de zero) a cada evento.

Os valores de nível de 0 a 5 são definidos pela Microsoft (consulte evntrace.h e winmeta.h). Os valores de nível de 6 a 15 são reservados. Os valores de nível de 16 a 255 podem ser definidos pelo provedor de eventos.

Valor	Semântica
LOG_ALWAYS (0)	O evento ignora a filtragem de eventos baseada em nível. Os eventos não devem usar esse nível.
CRÍTICO (1)	Erro crítico
ERRO (2)	Erro
AVISO (3)	Aviso
INFORMAÇÕES (4)	Informativo
VERBOSE (5)	Detalhado

As sessões de coleção de eventos podem definir um filtro de nível, o que significa que a sessão só aceitará eventos em eventDescriptor.Level <= session.LevelFilterque . Observe que eventos com um nível de 0 ignorarão a filtragem baseada em nível.

Opcode

Um número de 8 bits usado para marcar eventos com semântica especial. Esse valor pode ser usado por decodificadores de rastreamento para organizar e correlacionar eventos. Os valores de opcode reconhecidos globalmente são definidos em winmeta.h. A maioria dos eventos usa INFO (0). Os valores opcode de 10 a 239 podem receber semântica definida pelo usuário.

Os opcodes START (1) e STOP (2) são usados para indicar o início e o fim das atividades do ETW da seguinte maneira:

Gere uma ID de atividade exclusiva dentro do rastreamento, normalmente usando EventActivityIdControl.
Escreva um evento de início com opcode = START, ID da atividade = a ID da atividade gerada e a ID da atividade relacionada = a ID da atividade pai (se houver).
Escreva qualquer número de eventos de informações de atividade com opcode = INFO, ID da atividade = a ID da atividade gerada.
Escreva um evento stop com opcode = STOP, ID da atividade = a ID da atividade gerada.

As ferramentas de decodificação de rastreamento podem organizar esses eventos em grupos com base em suas IDs de atividade.

Task

Um número de 16 bits usado para anotar um evento ou um grupo relacionado de eventos.

O código da tarefa de evento pode ser usado para qualquer finalidade definida pelo provedor. O código da tarefa 0 é o padrão, usado para indicar que nenhum código de tarefa especial foi atribuído ao evento. O manifesto ETW dá suporte à atribuição de cadeias de caracteres localizadas a cada código de tarefa. O código da tarefa pode ser usado para agrupar eventos em categorias ou simplesmente associar uma cadeia de caracteres "tarefa" localizada a cada evento.

Keyword

Uma máscara de bits de 64 bits usada para indicar a associação de um evento em um conjunto de categorias de eventos.

Importante

A palavra-chave de eventos é um meio principal para filtrar eventos. Sempre atribua um palavra-chave significativo (diferente de zero) a cada evento.

Os 16 principais bits do palavra-chave (bitmask 0xFFFF000000000000) são definidos pela Microsoft. Os 48 bits baixos do palavra-chave (bitmask 0x0000FFFFFFFFFFFF) são definidos pelo provedor de eventos. Por exemplo, o provedor de eventos pode definir o bit 0 (bitmask 0x1) como a categoria "E/S", o bit 1 (bitmask 0x2) como a categoria "interface do usuário" e o bit 2 (bitmask 0x4) para ser a categoria "medida de desempenho". Nesse cenário, um evento pode ter seu palavra-chave definido como 0x5, indicando que o evento está nas categorias "E/S" e "medida de desempenho".

As sessões de coleção de eventos podem definir os filtros MatchAnyKeyword e MatchAllKeyword, o que significa que a sessão só aceitará eventos em que a expressão a seguir for verdadeira:

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

Observe que eventos com um palavra-chave de 0 normalmente ignorarão a filtragem baseada em palavra-chave.

Dica

Começando com Windows 10 versão 1507 e posterior, uma sessão de coleção de eventos pode excluir eventos que têm seus palavra-chave definidos como 0. Para fazer isso, inclua o EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 sinalizador no EnableProperty campo da estrutura ENABLE_TRACE_PARAMETERS que é passada para EnableTraceEx2 ao configurar o provedor.

Comentários

Essa estrutura é usada ao chamar EventWrite para gravar o evento. Você também pode usá-lo ao chamar EventEnabled para determinar se o evento deve ser gerado (ou seja, para determinar se algum ouvinte de evento está interessado no evento).

Observação

A maioria dos provedores de eventos não usará EVENT_DESCRIPTOR diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWriteEx e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto. Para obter detalhes sobre como os membros dessa estrutura se relacionam com o manifesto de instrumentação, consulte os atributos do tipo complexo EventDefinitionType .

Essa estrutura é incluída na estrutura EVENT_HEADER retornada com o registro de evento quando você consome eventos usando ProcessTrace com o retorno de chamada EventRecordCallback .

Observação

Ao processar eventos baseados em MOF, a identidade do evento está contida no campo Opcode , não no campo Id .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Cabeçalho	evntprov.h (inclua Evntprov.h)