estrutura WNODE_HEADER

A estrutura WNODE_HEADER é membro da estrutura EVENT_TRACE_PROPERTIES .

Sintaxe

typedef struct _WNODE_HEADER {
  ULONG BufferSize;
  ULONG ProviderId;
  union {
    ULONG64 HistoricalContext;
    struct {
      ULONG Version;
      ULONG Linkage;
    };
  };
  union {
    HANDLE        KernelHandle;
    LARGE_INTEGER TimeStamp;
  };
  GUID  Guid;
  ULONG ClientContext;
  ULONG Flags;
} WNODE_HEADER, *PWNODE_HEADER;

Membros

BufferSize

Tamanho total da memória alocada, em bytes, para as propriedades da sessão de rastreamento de eventos. O tamanho da memória deve incluir a sala para a estrutura EVENT_TRACE_PROPERTIES mais a cadeia de caracteres de nome de sessão e a cadeia de caracteres de nome do arquivo de log que seguem a estrutura na memória.

ProviderId

Reservado para uso interno.

HistoricContext

Na saída, o identificador para a sessão de rastreamento de eventos.

Versão

Reservado para uso interno.

Vinculação

Reservado para uso interno.

KernelHandle

Reservado para uso interno.

Timestamp

Hora em que as informações nessa estrutura foram atualizadas, em intervalos de 100 nanossegundos desde a meia-noite de 1º de janeiro de 1601.

Guid

O GUID que você define para a sessão.

Para uma sessão do Agente do Kernel NT, defina esse membro como SystemTraceControlGuid.

Se esse membro estiver definido como SystemTraceControlGuid ou GlobalLoggerGuid, o agente será um agente do sistema.

Para uma sessão de agente privado, defina esse membro como o GUID do provedor que você habilitará para a sessão.

Se você iniciar uma sessão que não seja um agente do kernel ou uma sessão de agente privado, você não precisará especificar um GUID de sessão. Se você não especificar um GUID, o ETW criará um para você. Você precisa especificar um GUID de sessão somente se quiser alterar as permissões padrão associadas a uma sessão específica. Para obter detalhes, consulte a função EventAccessControl.

Não é possível iniciar mais de uma sessão com o mesmo GUID de sessão.

Antes do Windows Vista: Você pode iniciar mais de uma sessão com o mesmo GUID de sessão.

ClientContext

Resolução de relógio a ser usada ao registrar o carimbo de data/hora para cada evento. O padrão é QPC (contador de desempenho de consulta).

Antes do Windows Vista: O padrão é a hora do sistema.

Antes de Windows 10, versão 1703: não mais do que dois tipos de relógio distintos podem ser usados simultaneamente por qualquer agente do sistema.

Começando com Windows 10, versão 1703: a restrição de tipo de relógio foi removida. Todos os três tipos de relógio agora podem ser usados simultaneamente por agentes do sistema.

Você pode especificar um dos valores a seguir.

Valor	Significado
1	QPC (contador de desempenho de consulta). O contador QPC fornece um carimbo de data/hora de alta resolução que não é afetado por ajustes no relógio do sistema. O carimbo de data/hora armazenado no evento é equivalente ao valor retornado da API QueryPerformanceCounter. Para obter mais informações sobre as características desse carimbo de data/hora, consulte Adquirir carimbos de data/hora de alta resolução. Você deverá usar essa resolução se tiver altas taxas de eventos ou se o consumidor mesclar eventos de buffers diferentes. Nesses casos, a precisão e a estabilidade do carimbo de data/hora do QPC permitem maior precisão na ordenação dos eventos de buffers diferentes. No entanto, o carimbo de data/hora do QPC não refletirá as atualizações do relógio do sistema, por exemplo, se o relógio do sistema for ajustado para frente devido à sincronização com um servidor NTP enquanto o rastreamento estiver em andamento, os carimbos de data/hora do QPC no rastreamento continuarão a refletir o tempo como se nenhuma atualização tivesse ocorrido. Para determinar a resolução, use o membro PerfFreq de TRACE_LOGFILE_HEADER ao consumir o evento. Para converter o carimbo de data/hora de um evento em unidades de 100 ns, use a seguinte fórmula de conversão: scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart * 10000000.0 / logfileHeader.PerfFreq.QuadPart Observe que, em computadores mais antigos, o carimbo de data/hora pode não ser preciso porque o contador às vezes ignora devido a erros de hardware.
2	Hora do sistema. A hora do sistema fornece um carimbo de data/hora que acompanha as alterações no relógio do sistema, por exemplo, se o relógio do sistema for ajustado para frente devido à sincronização com um servidor NTP enquanto o rastreamento estiver em andamento, os carimbos de data/hora do sistema no rastreamento também avançarão para corresponder à nova configuração do relógio do sistema. Em sistemas anteriores a Windows 10, o carimbo de data/hora armazenado no evento é equivalente ao valor retornado da API GetSystemTimeAsFileTime. Em Windows 10 ou posterior, o carimbo de data/hora armazenado no evento é equivalente ao valor retornado da API GetSystemTimePreciseAsFileTime. Antes de Windows 10, a resolução desse carimbo de data/hora era a resolução de um tique de relógio do sistema, conforme indicado pelo membro timerResolution do TRACE_LOGFILE_HEADER. Começando com Windows 10, a resolução desse carimbo de data/hora é a resolução do contador de desempenho, conforme indicado pelo membro perfFreq do TRACE_LOGFILE_HEADER. Para converter o carimbo de data/hora de um evento em unidades de 100 ns, use a seguinte fórmula de conversão: scaledTimestamp = eventRecord.EventHeader.TimeStamp.QuadPart Observe que quando os eventos são capturados em um sistema que executa um sistema operacional antes de Windows 10, se o volume de eventos for alto, a resolução para o tempo do sistema pode não ser boa o suficiente para determinar a sequência de eventos. Nesse caso, um conjunto de eventos terá o mesmo carimbo de data/hora, mas a ordem na qual o ETW entrega os eventos pode não estar correta. Começando com Windows 10, o carimbo de data/hora é capturado com precisão adicional, embora alguma instabilidade ainda possa ocorrer nos casos em que o relógio do sistema foi ajustado enquanto o rastreamento estava sendo capturado.
3	Contador de ciclo de CPU. O contador de CPU fornece o carimbo de data/hora de maior resolução e é o menos intensivo em recursos para recuperar. No entanto, o contador de CPU não é confiável e não deve ser usado na produção. Por exemplo, em alguns computadores, os temporizadores alterarão a frequência devido a alterações térmicas e de energia, além de parar em alguns estados. Para determinar a resolução, use o membro CpuSpeedInMHz de TRACE_LOGFILE_HEADER ao consumir o evento. Se o hardware não der suporte a esse tipo de relógio, o ETW usará a hora do sistema. Windows Server 2003, Windows XP com SP1 e Windows XP: Esse valor não tem suporte, ele foi introduzido no Windows Server 2003 com SP1 e Windows XP com SP2.

 

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

Sinalizadores

Deve conter WNODE_FLAG_TRACED_GUID para indicar que a estrutura contém informações de rastreamento de eventos.

Comentários

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

Para converter um carimbo de data/hora etw em um FILETIME, use o seguinte procedimento:

1. Para cada sessão ou arquivo de log que está sendo processado (ou seja, para cada event\_TRACE\_LOGFILE), marcar o campo logFile.ProcessTraceMode para determinar se o sinalizador PROCESS\_TRACE\_MODE\_RAW\_TIMESTAMP está definido. Por padrão, esse sinalizador não está definido. Se esse sinalizador não estiver definido, o runtime do ETW converterá automaticamente o carimbo de data/hora de cada EVENT\_RECORD em UM FILETIME antes de enviar o EVENT\_RECORD para sua função EventRecordCallback, portanto, nenhum processamento adicional será necessário. As etapas a seguir só deverão ser usadas se o rastreamento estiver sendo processado com o conjunto de sinalizadores PROCESS\_TRACE\_MODE\_RAW\_TIMESTAMP. 2. Para cada sessão ou arquivo de log que está sendo processado (ou seja, para cada EVENT\_TRACE\_LOGFILE), marcar o campo logFile.LogfileHeader.ReservedFlags para determinar a escala de carimbo de data/hora do arquivo de log. Com base no valor de ReservedFlags, siga uma destas etapas para determinar o valor a ser usado para timeStampScale nas etapas restantes:

a. Se ReservedFlags == 1 (QPC): DOUBLE timeStampScale = 10000000.0 / logFile.LogfileHeader.PerfFreq.QuadPart; B. Se ReservedFlags == 2 (Hora do sistema): DOUBLE timeStampScale = 1,0; Observe que as etapas restantes são desnecessárias para eventos que usam a hora do sistema, já que os eventos já fornecem seus carimbos de data/hora em unidades FILETIME. As etapas restantes funcionarão, mas são desnecessárias e introduzirão um pequeno erro de arredondamento. c. Se ReservedFlags == 3 (contador de ciclo de CPU): DOUBLE timeStampScale = 10.0 / logFile.LogfileHeader.CpuSpeedInMHz;

3. Na primeira chamada para sua função EventRecordCallback para um arquivo de log específico, use dados do logFile (EVENT\_TRACE\_LOGFILE) e do eventRecord (EVENT\_RECORD) para calcular o timeStampBase que será usado para os eventos restantes no arquivo de log: INT64 timeStampBase = logFile.LogfileHeader.StartTime.QuadPart - (INT64)(timeStampScale \* eventRecord.EventHeader.TimeStamp.QuadPart); 4. Para cada eventRecord (EVENT\_RECORD), converta o carimbo de data/hora do evento em FILETIME da seguinte maneira, usando os valores timeStampScale e timeStampBase calculados nas etapas 2 e 3: INT64 timeStampInFileTime = timeStampBase + (INT64)(timeStampScale \* eventRecord.EventHeader.TimeStamp.QuadPart);

Requisitos

Confira também

ControlCallback

EVENT_TRACE_PROPERTIES

GetTraceLoggerHandle

LARGE_INTEGER