estrutura EVENT_TRACE_LOGFILEW (evntrace.h)
A estrutura EVENT_TRACE_LOGFILE armazena informações sobre uma fonte de dados de rastreamento.
A estrutura EVENT_TRACE_LOGFILE é usada ao chamar OpenTrace. O usuário fornece uma estrutura EVENT_TRACE_LOGFILE com informações sobre a fonte de dados de rastreamento (o nome de um arquivo ETL ou o nome de uma sessão ativa de agente em tempo real), sinalizadores de processamento de rastreamento e as funções de retorno de chamada que receberão dados de rastreamento. Com êxito, o OpenTrace preenche os campos restantes da estrutura para retornar detalhes sobre a fonte de dados de rastreamento.
Quando o ProcessTrace processa um buffer, ele invoca o BufferCallback definido pelo usuário com uma estrutura EVENT_TRACE_LOGFILE para fornecer informações sobre a sessão de processamento de eventos e o buffer.
Sintaxe
typedef struct _EVENT_TRACE_LOGFILEW {
LPWSTR LogFileName;
LPWSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;
Membros
LogFileName
Nome do arquivo de log que está sendo processado ou NULL se estiver processando dados de uma sessão de rastreamento em tempo real. Especifique um valor para esse membro se você estiver chamando OpenTrace para consumir dados de um arquivo de log.
Ao chamar OpenTrace, se LoggerName não for NULL , LogFileName deverá ser NULL.
Ao chamar OpenTrace, o usuário que consome os eventos deve ter permissões para ler o arquivo.
Observação
O nome do arquivo fornecido ao OpenTrace por meio do campo LogFileName deve ser o nome de arquivo completo, incluindo todos os sufixos. Algumas APIs de criação de arquivo de rastreamento podem adicionar silenciosamente um sufixo ao nome de arquivo especificado pelo usuário. Por exemplo, se o controlador registrou eventos registrados em uma sessão privada (o controlador definiu o membro LogFileMode de EVENT_TRACE_PROPERTIES como EVENT_TRACE_PRIVATE_LOGGER_MODE ao chamar StartTrace), o arquivo ETL gerado incluirá um sufixo de ID do processo, por exemplo. mytrace.etl_123.
Isso também poderá ocorrer se o arquivo tiver sido criado usando o modo EVENT_TRACE_FILE_MODE_NEWFILE , nesse caso, o arquivo ETL gerado incluirá um número de sequência.
LoggerName
Nome da sessão de rastreamento de eventos em tempo real ou NULL se estiver processando dados de um arquivo de log. Especifique um valor para esse membro se você estiver chamando OpenTrace para consumir dados de uma sessão em tempo real.
Ao chamar OpenTrace, se LogFileName não for NULL , LoggerName deverá ser NULL.
Você só poderá consumir eventos em tempo real se o controlador de rastreamento tiver definido o membro LogFileMode de EVENT_TRACE_PROPERTIES para incluir o sinalizador EVENT_TRACE_REAL_TIME_MODE .
Somente usuários com privilégios administrativos, usuários no grupo Usuários do Log de Desempenho e aplicativos em execução como LocalSystem, LocalService, NetworkService podem consumir eventos em tempo real. Para conceder a um usuário restrito a capacidade de consumir eventos em tempo real, adicione-os ao grupo Usuários do Log de Desempenho ou chame EventAccessControl.
Windows XP e Windows 2000: Qualquer pessoa pode consumir eventos em tempo real.
CurrentTime
Na saída, a hora atual, em intervalos de 100 nanossegundos desde a meia-noite de 1º de janeiro de 1601.
BuffersRead
Na saída, o número de buffers processados.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Reservado. Não use.
DUMMYUNIONNAME.ProcessTraceMode
Modos para processar eventos. Os modos são definidos no arquivo de evntcons.h cabeçalho. Você pode especificar um ou mais dos seguintes modos:
PROCESS_TRACE_MODE_EVENT_RECORD
Especifique esse modo se quiser receber eventos no novo formato de EVENT_RECORD (altamente recomendado). Para receber eventos no novo formato, você deve especificar um retorno de chamada no membro EventRecordCallback . Se você não especificar esse modo, receberá eventos no formato antigo por meio do retorno de chamada especificado no membro EventCallback .
Antes do Windows Vista: Sem suporte.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
Por padrão, o ProcessTrace converte o TimeStamp do evento do formato bruto original (hora do sistema, hora do QPC ou contador de ciclo de CPU) em tempo do sistema (intervalos de 100 nanossegundos desde a meia-noite de 1º de janeiro de 1601).
Especifique o sinalizador PROCESS_TRACE_MODE_RAW_TIMESTAMP se você não quiser o valor do carimbo de data/hora no membro TimeStamp de EVENT_HEADER e EVENT_TRACE_HEADER convertido em hora do sistema. Se esse sinalizador for especificado, ProcessTrace deixará o valor do carimbo de data/hora no formato original especificado pelo controlador no membro Wnode.ClientContext de EVENT_TRACE_PROPERTIES.
Antes do Windows Vista: Sem suporte.
PROCESS_TRACE_MODE_REAL_TIME
Especifique esse modo para receber eventos em tempo real. Você deve especificar esse modo se LoggerName não for NULL.
CurrentEvent
Na saída, uma estrutura EVENT_TRACE que contém o último evento processado.
LogfileHeader
Na saída, um TRACE_LOGFILE_HEADER estrutura que contém informações gerais sobre a sessão e o computador no qual a sessão foi executada.
BufferCallback
Ponteiro para a função BufferCallback que recebe estatísticas relacionadas ao buffer para cada ETW de buffer liberado. O ETW chama esse retorno de chamada depois que ele entrega todos os eventos no buffer. Esse retorno de chamada é opcional.
BufferSize
Na saída, contém o tamanho de cada buffer, em bytes.
Filled
Na saída, contém o número de bytes no buffer que contêm informações válidas.
EventsLost
Não usado.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Ponteiro para a função EventCallback que o ETW chama para cada evento no buffer. Esse campo será usado somente se o campo ProcessTraceMode não incluir o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador.
Observação
O campo EventCallback será tratado como um EventRecordCallback se o campo ProcessTraceMode incluir o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador. Se o EventCallback estiver recebendo dados embaralhados do ProcessTrace, verifique se o campo ProcessTraceMode não inclui o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador.
Dica
O novo código deve usar EventRecordCallback em vez de EventCallback. O EventRecordCallback recebe um EVENT_RECORD que contém informações de evento mais completas, pode ser usado com APIs de decodificação, como TdhGetEventInformation, e tem um ponteiro de contexto que pode ser usado pelo retorno de chamada.
DUMMYUNIONNAME2.EventRecordCallback
Ponteiro para a função EventRecordCallback que o ETW chama para cada evento no buffer. Esse campo será usado somente se o campo ProcessTraceMode incluir o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador.
Observação
O campo EventRecordCallback será tratado como um EventCallback se o campo ProcessTraceMode não incluir o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador. Se o EventRecordCallback estiver recebendo dados embaralhados do ProcessTrace, verifique se o campo ProcessTraceMode inclui o PROCESS_TRACE_MODE_EVENT_RECORD sinalizador.
Antes do Windows Vista: Sem suporte.
IsKernelTrace
Na saída, se esse membro for TRUE, a sessão de rastreamento de eventos será o Agente do Kernel NT. Caso contrário, será outra sessão de rastreamento de eventos.
Context
Dados de contexto que um consumidor pode especificar ao chamar OpenTrace. Se o consumidor usar EventRecordCallback para consumir eventos, o ETW definirá o membro UserContext da estrutura EVENT_RECORD como esse valor.
Antes do Windows Vista: Sem suporte.
Comentários
Os consumidores de eventos devem:
- Inicialize a memória dessa estrutura como zero.
- Se estiver lendo de um arquivo ETL, defina LogFileName como o caminho para o arquivo.
Caso contrário (ou seja, se estiver lendo de uma sessão em tempo real), defina LoggerName como o nome da sessão e defina ProcessTraceMode como
PROCESS_TRACE_MODE_REAL_TIME. - Se estiver usando EventRecordCallback (recomendado), defina EventRecordCallback como o endereço da função de retorno de chamada do registro de evento, defina Contexto como um valor a ser fornecido ao seu retorno de chamada e adicione
PROCESS_TRACE_MODE_EVENT_RECORDa ProcessTraceMode. Caso contrário (ou seja, se estiver usando EventCallback), defina EventCallback como o endereço da função de retorno de chamada de evento. - Se você precisar de um retorno de chamada depois que cada buffer for processado, defina BufferCallback como o endereço da função de retorno de chamada do buffer.
- Se você quiser os dados de carimbo de data/hora brutos originais em vez do carimbo de data/hora processado, adicione
PROCESS_TRACE_MODE_RAW_TIMESTAMPa ProcessTraceMode. - Chame OpenTrace. Observe que, se bem-sucedida, a função OpenTrace preencherá os membros dessa estrutura com informações da fonte de dados de rastreamento.
- Chame ProcessTrace com o identificador retornado pelo OpenTrace.
- O ProcessTrace invocará sua função de retorno de chamada de evento para cada evento.
- O ProcessTrace invocará sua função de retorno de chamada de buffer (se fornecido) depois de concluir cada buffer e incluirá uma instância da estrutura EVENT_TRACE_LOGFILE com o processamento de rastreamento status informações.
- Após a conclusão do processamento de rastreamento, chame CloseTrace para fechar o identificador retornado pelo OpenTrace.
Observação
O cabeçalho evntrace.h define EVENT_TRACE_LOGFILE como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Cabeçalho | evntrace.h |