PEVENT_RECORD_CALLBACK função de retorno de chamada (evntrace.h)

Artigo
03/11/2023

Os consumidores implementam esse retorno de chamada para receber eventos de uma sessão de processamento de rastreamento.

O tipo PEVENT_RECORD_CALLBACK define um ponteiro para essa função de retorno de chamada. EventRecordCallback é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

Parâmetros

[in] EventRecord

Ponteiro para uma estrutura EVENT_RECORD que contém as informações do evento.

Valor retornado

Nenhum

Comentários

Para especificar a função que o ETW chama para entregar eventos, defina os membros EventRecordCallback, Context e ProcessTraceMode da estrutura EVENT_TRACE_LOGFILE que você passa para a função OpenTrace .

Defina EventRecordCallback como o endereço da função de retorno de chamada.
Defina Contexto como um valor que deve ser incluído no campo UserContext de cada EVENT_RECORD fornecido para o retorno de chamada.
Defina ProcessTraceMode como os sinalizadores a serem usados ao processar o rastreamento. Para usar EventRecordCallback, você deve incluir PROCESS_TRACE_MODE_EVENT_RECORD no valor ProcessTraceMode .

Observação

Se a função EventRecordCallback estiver recebendo dados embaralhados do ProcessTrace, marcar os sinalizadores especificados no ProcessTraceMode campo da EVENT_TRACE_LOGFILE estrutura que foi fornecida ao OpenTrace. EVENT_TRACE_LOGFILEOs campos EventCallback e EventRecordCallback são membros sobrepostos de uma união. Se o ProcessTraceMode campo incluir o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador, ProcessTrace invocará seu retorno de chamada usando a assinatura da função EventRecordCallback . Caso contrário, o ProcessTrace invocará o retorno de chamada usando a assinatura da função EventCallback .

Depois de usar o OpenTrace para criar a sessão de processamento de rastreamento, chame a função ProcessTrace para começar a receber os eventos.

Quando o ProcessTrace começa a processar eventos de um rastreamento, ele pode invocar o retorno de chamada com um ou mais eventos sintéticos que contêm dados sobre o rastreamento (metadados) em vez de dados de eventos registrados. Esses eventos sintéticos têm EventHeader.ProviderId definido como EventTraceGuid e EventHeader.EventDescriptor.Opcode definido com base no conteúdo do evento sintético. Por exemplo, o primeiro evento de cada arquivo de rastreamento será um evento sintético com Opcode 0 contendo TRACE_LOGFILE_HEADER informações.

Todos os outros eventos recebidos contêm dados de evento específicos do provedor. Você usa os membros EventHeader.ProviderId e EventHeader.EventDescriptor de EVENT_RECORD para determinar o tipo de evento recebido.

Se o evento for proveniente de um provedor conhecido e você souber o layout dos dados, poderá usar seu próprio sistema para decodificar os eventos.
Se o campo EventHeader.Flags incluir o EVENT_HEADER_FLAG_TRACE_MESSAGE sinalizador, o evento será uma mensagem WPP. Se as informações de decodificação apropriadas (arquivo TMF ou PDB) estiverem disponíveis, o evento poderá ser decodificado usando TdhGetProperty ou TdhGetWppProperty.
Caso contrário, o evento pode ser um evento baseado em MOF, baseado em manifesto ou TraceLogging. Se as informações de decodificação apropriadas estiverem disponíveis, o evento poderá ser decodificado usando TdhGetEventInformation.
- Se o evento usar a decodificação baseada em MOF, TdhGetEventInformation procurará informações de decodificação de eventos no armazenamento de dados WMI do sistema.
- Se o evento usar a decodificação baseada em manifesto, TdhGetEventInformation procurará informações de decodificação de eventos nos manifestos registrados do sistema ou em manifestos ou binários carregados no contexto de decodificação por processo por TdhLoadManifest ou TdhLoadManifestFromBinary.
- Se o evento usar a decodificação baseada em TraceLogging, TdhGetEventInformation usará informações de decodificação de dentro do evento.

Na maioria dos casos, os eventos serão entregues ao retorno de chamada na ordem em que ocorreram (ordem de carimbo de data/hora). No entanto, em determinadas circunstâncias, os eventos podem não ser entregues em sua ordem original.

Se o rastreamento estiver usando o tempo do sistema para o carimbo de data/hora da sessão (ou seja, a sessão de rastreamento foi iniciada com definido como properties.Wnode.ClientContext 2) e o relógio do sistema for ajustado para trás enquanto a sessão estiver coletando eventos, alguns dos eventos poderão ser entregues fora de ordem. Para evitar isso, defina ClientContext como 0 para obter o carimbo de data/hora padrão (hora do QPC).
Se o rastreamento for coletado usando carimbos de data/hora de um relógio impreciso, eventos com o mesmo carimbo de data/hora de diferentes CPUs poderão ser entregues fora de ordem. Isso ocorre com mais frequência quando o rastreamento usa o tempo do sistema para o carimbo de data/hora da sessão porque o tempo do sistema marca. Esse problema pode ser evitado iniciando a sessão com EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING nos sinalizadores LogFileMode , embora isso possa ter um impacto negativo substancial no desempenho de rastreamento. A partir do Windows 10: O tipo de relógio de hora do sistema usa GetSystemTimePreciseAsFileTime para reduzir a probabilidade desse problema.
Se o rastreamento estiver corrompido, foi gerado usando APIs de baixo nível que não mantêm as regras de carimbo de data/hora esperadas dentro do arquivo ou usa opções de substituição de carimbo de data/hora ao gravar eventos, alguns dos eventos podem ser entregues fora de ordem.

Detalhes técnicos: Os eventos são armazenados em buffers. Cada buffer é atribuído a um fluxo de buffer, normalmente um fluxo para cada CPU. A implementação do ProcessTrace pressupõe que todos os eventos em um buffer sejam classificados por carimbo de data/hora e que cada buffer contenha eventos por um único período de tempo que não se sobreponha ao intervalo de nenhum outro buffer no fluxo desse buffer. Quando essas suposições não são atendidas, o ProcessTracepode fornecer eventos fora de ordem.

Quando uma sessão de coleta de rastreamento em tempo real não tiver sessões de processamento de rastreamento associadas, os eventos coletados serão armazenados em buffer pelo sistema até que o buffer esteja cheio. Quando uma sessão de processamento de rastreamento se conecta a uma sessão de coleta de rastreamento em tempo real, a sessão de processamento de rastreamento receberá os eventos sintéticos da sessão, depois os eventos armazenados em buffer e, em seguida, começará a receber os eventos recém-gerados em tempo real. Se uma segunda sessão de processamento em tempo real se conectar à mesma sessão de coleta de rastreamento, ela receberá os eventos sintéticos e os eventos em tempo real recém-gerados (a segunda sessão de processamento de rastreamento não receberá eventos mais antigos).

Importante

Ao processar eventos de uma sessão em tempo real, se o retorno de chamada de processamento levar muito tempo para processar cada evento e os eventos chegarem muito rapidamente, ele ficará para trás. O sistema armazenará eventos em buffer para evitar perda de dados, mas isso aumenta o uso de recursos do sistema (por exemplo, uso de memória e disco). Evite esse problema usando filtros de sessão (por exemplo, filtros de nível e palavra-chave para cada provedor) para reduzir a taxa de eventos de entrada, fazendo a filtragem antecipada em seu retorno de chamada para ignorar eventos que não precisam de processamento completo e otimizando seu retorno de chamada para retornar o mais rápido possível para evitar bloquear o thread de processamento.

Para obter detalhes adicionais sobre como interpretar os dados do evento, consulte Consumindo eventos e recuperando dados de evento usando TDH.

Requisitos


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]
Plataforma de Destino	Windows
Cabeçalho	evntrace.h