estrutura EVENT_TRACE_HEADER (evntrace.h)

A estrutura EVENT_TRACE_HEADER contém informações de rastreamento de eventos padrão comuns a todos os eventos gravados por TraceEvent.

Sintaxe

typedef struct _EVENT_TRACE_HEADER {
  USHORT        Size;
  union {
    USHORT FieldTypeFlags;
    struct {
      UCHAR HeaderType;
      UCHAR MarkerFlags;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
  union {
    ULONG Version;
    struct {
      UCHAR  Type;
      UCHAR  Level;
      USHORT Version;
    } Class;
  } DUMMYUNIONNAME2;
  ULONG         ThreadId;
  ULONG         ProcessId;
  LARGE_INTEGER TimeStamp;
  union {
    GUID      Guid;
    ULONGLONG GuidPtr;
  } DUMMYUNIONNAME3;
  union {
    struct {
      ULONG KernelTime;
      ULONG UserTime;
    } DUMMYSTRUCTNAME;
    ULONG64 ProcessorTime;
    struct {
      ULONG ClientContext;
      ULONG Flags;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME4;
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;

Membros

Size

Número total de bytes do evento. O tamanho inclui o tamanho da estrutura de cabeçalho, além do tamanho de qualquer dado específico do evento acrescentado ao cabeçalho.

Na entrada, o tamanho deve ser menor que o tamanho do buffer da sessão de rastreamento de eventos menos 72 (0x48).

Na saída, não use esse número em cálculos.

DUMMYUNIONNAME

DUMMYUNIONNAME.FieldTypeFlags

Reservado.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.HeaderType

Reservado.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.MarkerFlags

Reservado.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.Version

Este é um roll-up dos membros da Classe. O byte de baixa ordem contém o Tipo, o próximo byte contém o Nível e os dois últimos bytes contêm a versão.

DUMMYUNIONNAME2.Class

DUMMYUNIONNAME2.Class.Type

Tipo de evento. Um provedor pode definir seus próprios tipos de evento ou usar os tipos de evento predefinidos listados na tabela a seguir.

• EVENT_TRACE_TYPE_CHECKPOINT: evento Checkpoint. Use para um evento que não esteja no início ou no final de uma atividade.

• EVENT_TRACE_TYPE_DC_END: evento final da coleta de dados.

• EVENT_TRACE_TYPE_DC_START: evento de início da coleta de dados.

• EVENT_TRACE_TYPE_DEQUEUE: Evento de remoção. Use quando uma atividade for enfileirada antes de começar. Use EVENT_TRACE_TYPE_START para marcar a hora em que um item de trabalho está na fila. Use o tipo de evento de dequeue para marcar a hora em que o trabalho no item realmente começa. Use EVENT_TRACE_TYPE_END para marcar a hora em que o trabalho no item é concluído.

• EVENT_TRACE_TYPE_END: evento final. Use para rastrear o estado final de um evento de várias etapas.

• EVENT_TRACE_TYPE_EXTENSION: evento de extensão. Use para um evento que é uma continuação de um evento anterior. Por exemplo, use o tipo de evento de extensão quando um rastreamento de evento registrar mais dados do que pode caber em um buffer de sessão.

• EVENT_TRACE_TYPE_INFO: evento informativo. Esse é o tipo de evento padrão.

• EVENT_TRACE_TYPE_REPLY: Evento de resposta. Use quando um aplicativo que solicita recursos puder receber várias respostas. Por exemplo, se um aplicativo cliente solicitar uma URL e o servidor Web responder enviando vários arquivos, cada arquivo recebido poderá ser marcado como um evento de resposta.

• EVENT_TRACE_TYPE_START: iniciar evento. Use para rastrear o estado inicial de um evento de várias etapas.

Se você definir seus próprios tipos de evento, deverá usar números a partir de 10. No entanto, não há nada que impeça você de usar os números que deseja usar. Se o GUID da classe de rastreamento de eventos der suporte a vários tipos de evento, os consumidores usarão o tipo de evento para determinar o evento e como interpretar seu conteúdo.

DUMMYUNIONNAME2.Class.Level

Valor definido pelo provedor que define o nível de severidade usado para gerar o evento. O valor varia de 0 a 255. O controlador especifica o nível de gravidade quando chama a função EnableTraceEx2 . O provedor recupera o nível de gravidade chamando a função GetTraceEnableLevel de sua implementação ControlCallback . O provedor usa o valor para definir esse membro.

O ETW define os seguintes níveis de gravidade. Selecionar um nível superior a 1 também incluirá eventos para níveis mais baixos. Por exemplo, se o controlador especificar TRACE_LEVEL_WARNING (3), o provedor também gerará eventos TRACE_LEVEL_FATAL (1) e TRACE_LEVEL_ERROR (2).

DUMMYUNIONNAME2.Class.Version

Indica a versão da classe de rastreamento de evento que você está usando para registrar o evento em log. Especifique zero se houver apenas uma versão da classe de rastreamento de eventos. A versão informa ao consumidor qual classe MOF usar para decifrar os dados do evento.

ThreadId

Na saída, identifica o thread que gerou o evento.

Observe que, no Windows 2000, ThreadId era um valor ULONGLONG .

ProcessId

Na saída, identifica o processo que gerou o evento.

Windows 2000: Não há suporte para esse membro.

TimeStamp

Na saída, contém a hora em que o evento ocorreu. A resolução é a hora do sistema, a menos que o membro ProcessTraceMode de EVENT_TRACE_LOGFILE contenha o PROCESS_TRACE_MODE_RAW_TIMESTAMP sinalizador, nesse caso, a resolução depende do valor do membro Wnode.ClientContext de EVENT_TRACE_PROPERTIES no momento em que o controlador criou a sessão.

DUMMYUNIONNAME3

DUMMYUNIONNAME3.Guid

GUID da classe de rastreamento de eventos. Você pode usar o GUID de classe para identificar uma categoria de eventos e o membro Class.Type para identificar um evento dentro da categoria de eventos.

Como alternativa, você pode usar o membro GuidPtr para especificar o GUID de classe.

Windows XP e Windows 2000: O GUID de classe deve ter sido registrado anteriormente usando a função RegisterTraceGuids .

DUMMYUNIONNAME3.GuidPtr

Ponteiro para um GUID de classe de rastreamento de eventos. Como alternativa, você pode usar o membro Guid para especificar o GUID de classe.

Quando o evento é gravado, o ETW usa o ponteiro para copiar o GUID para o evento (o GUID está incluído no evento, não no ponteiro).

Se você usar esse membro, o membro Flags também deverá conter WNODE_FLAG_USE_GUID_PTR.

DUMMYUNIONNAME4

DUMMYUNIONNAME4.DUMMYSTRUCTNAME

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.KernelTime

Tempo de execução decorrido para instruções de modo kernel, em unidades de tempo de CPU. Se você estiver usando uma sessão privada, use o valor no membro ProcessorTime . Para obter mais informações, consulte Comentários.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME.UserTime

Tempo de execução decorrido para instruções de modo de usuário, em unidades de tempo de CPU. Se você estiver usando uma sessão privada, use o valor no membro ProcessorTime . Para obter mais informações, consulte Comentários.

DUMMYUNIONNAME4.ProcessorTime

Para sessões privadas, o tempo de execução decorrido para instruções de modo de usuário, em tiques de CPU.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.ClientContext

Reservado.

DUMMYUNIONNAME4.DUMMYSTRUCTNAME2.Flags

Você deve definir esse membro como WNODE_FLAG_TRACED_GUID e, opcionalmente, pode especificar qualquer combinação do seguinte.

• WNODE_FLAG_USE_GUID_PTR: especifique se o membro GuidPtr contém o GUID da classe.

• WNODE_FLAG_USE_MOF_PTR: especifique se uma matriz de estruturas de MOF_FIELD contém os dados de evento acrescentados a essa estrutura. O número de elementos na matriz é limitado a MAX_MOF_FIELDS.

Comentários

Certifique-se de inicializar a memória dessa estrutura como zero antes de definir qualquer membro.

Você pode usar os membros KernelTime e UserTime para determinar o custo da CPU em unidades para um conjunto de instruções (os valores indicam o uso da CPU cobrado para esse thread no momento do registro em log). Por exemplo, se o Evento A e o Evento B forem registrados consecutivamente pelo mesmo thread e tiverem os números de uso da CPU 150 e 175, a atividade que foi executada por esse thread entre os eventos A e B custará 25 unidades de tempo de CPU (175 – 150).

O TimerResolution da estrutura TRACE_LOGFILE_HEADER contém a resolução do temporizador de uso da CPU em unidades de 100 nanossegundos. Você pode usar a resolução do temporizador com os valores de tempo de kernel e tempo do usuário para determinar a quantidade de tempo de CPU que o conjunto de instruções usou. Por exemplo, se a resolução do temporizador for de 156.250, 25 unidades de tempo de CPU serão 0,39 segundos (156.250 * 25 * 100 / 1.000.000.000). Essa é a quantidade de tempo de CPU (não tempo decorrido do relógio de parede) usado pelo conjunto de instruções entre os eventos A e B.

Observe, no entanto, que a resolução do temporizador de uso da CPU normalmente é muito baixa (cerca de 10 ou mais milissegundos). Portanto, os números de uso da CPU não podem ser usados para considerar o uso de tempo de CPU entre threads com alta precisão. Em vez disso, eles são adequados para o tipo estatístico de análise de longo prazo.

Requisitos

Confira também

EVENT_TRACE

EventCallback

Traceevent