estrutura EVENT_TRACE_PROPERTIES (evntrace.h)

A estrutura EVENT_TRACE_PROPERTIES contém informações sobre uma sessão de rastreamento de eventos. Você usa essa estrutura com APIs como StartTrace e ControlTrace ao definir, atualizar ou consultar as propriedades de uma sessão.

Sintaxe

typedef struct _EVENT_TRACE_PROPERTIES {
  WNODE_HEADER Wnode;
  ULONG        BufferSize;
  ULONG        MinimumBuffers;
  ULONG        MaximumBuffers;
  ULONG        MaximumFileSize;
  ULONG        LogFileMode;
  ULONG        FlushTimer;
  ULONG        EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG        NumberOfBuffers;
  ULONG        FreeBuffers;
  ULONG        EventsLost;
  ULONG        BuffersWritten;
  ULONG        LogBuffersLost;
  ULONG        RealTimeBuffersLost;
  HANDLE       LoggerThreadId;
  ULONG        LogFileNameOffset;
  ULONG        LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Membros

Wnode

Uma estrutura WNODE_HEADER . Você deve especificar os membros BufferSize, Flags e Guid . Opcionalmente, você pode especificar o membro ClientContext .

BufferSize

Quilobytes de memória alocados para cada buffer de sessão de rastreamento de eventos. O tamanho mínimo do buffer é 4 (4 KB). O tamanho máximo do buffer é 16384 (16 MB). A maioria das sessões de rastreamento deve usar um tamanho de buffer de 64 KB ou menos para evitar perda de memória e espaço em disco. Antes de Windows 8: o tamanho máximo do buffer é 1024 (1 MB).

Tamanhos de buffer menores reduzem o uso de memória da sessão e podem ajudar a reduzir o tamanho do arquivo de log. Tamanhos de buffer maiores dão suporte à coleta de eventos maiores porque o ETW não fragmenta eventos entre limites de buffer e, portanto, não pode coletar eventos maiores que o tamanho do buffer. Em cenários que envolvem uma taxa de transferência de dados extremamente alta, tamanhos de buffer maiores também podem reduzir a sobrecarga da CPU.

• Uma sessão com eventos pequenos e uma baixa taxa de eventos (alguns KB/s) deve usar um tamanho de buffer pequeno (4 KB a 16 KB).
• Uma sessão com eventos pequenos e uma taxa de eventos moderada deve usar um tamanho médio de buffer (16 KB a 32 KB).
• Uma sessão com eventos grandes ou uma alta taxa de eventos (alguns MB/s) deve usar um tamanho de buffer grande (64 KB a 128 KB).
• Em casos raros em que uma grande quantidade de memória deve ser reservada para um rastreamento de diagnóstico com centenas de megabytes de dados por segundo, um tamanho de buffer enorme (256 KB a 1024 KB) pode reduzir a sobrecarga da CPU.

O ETW pode ajustar o BufferSize solicitado para cima em determinados cenários. Por exemplo, ao gravar um arquivo de rastreamento em um disco, o ETW pode aumentar o tamanho do buffer para um múltiplo do tamanho do bloco físico do disco.

MinimumBuffers

Número mínimo de buffers reservados para o pool de buffers da sessão de rastreamento.

O ETW pode ajustar esse valor em determinados cenários.

• Se o modo de registro em log incluir o sinalizador , o EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING ETW reservará pelo menos 2 buffers.
• Se o modo de registro em log não incluir o sinalizador , o EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING ETW reservará pelo menos 2 buffers para cada processador lógico.
• Se esse valor for maior que um limite determinado pelo ETW, o ETW poderá reduzi-lo ao limite para evitar o uso excessivo de memória.

Para rastreamentos de modo de arquivo e em tempo real com taxas de evento moderadas, a maioria dos usuários deve minimizar o uso de memória definindo MinimumBuffers como 0 ou para um mínimo pequeno (por exemplo, 4 ou 8), permitindo que o ETW ajuste o valor para cima com base no número de processadores. O ETW reservará o número mínimo (ajustado) de buffers quando o rastreamento for iniciado. Se os buffers forem preenchidos mais rapidamente do que podem ser processados, o ETW tentará alocar buffers de adição, até o número especificado por MaximumBuffers.

Para rastreamentos do modo de buffer (circular na memória), os usuários devem definir o parâmetro MinimumBuffers de acordo com a quantidade total de memória que você deseja que o ETW reserve para a sessão. Isso geralmente é calculado com base na taxa de eventos esperada e na quantidade de tempo que você deseja que o rastreamento cubra. Por exemplo, se você espera uma taxa de dados de 16 KB por segundo e deseja que o rastreamento registre pelo menos 60 segundos de dados, precisará de 960 KB. Supondo um tamanho de buffer de 32 KB, você definiria MinimumBuffers como 30 (total de 960 KB/32 KB por buffer = 30 buffers). O ETW reservará o número mínimo (ajustado) de buffers quando o rastreamento for iniciado. Quando todos os buffers forem preenchidos, o ETW reutilizará o buffer preenchido mais antigo para novos eventos. Observe que o ETW não alocará buffers adicionais (o ETW ignora MaximumBuffers para rastreamentos no modo de buffer).

MaximumBuffers

Número máximo de buffers a serem alocados para o pool de buffers da sessão de rastreamento.

O ETW pode ajustar esse valor em determinados cenários.

• Se esse valor for menor que o valor ajustado de MinimumBuffers, o ETW poderá aumentá-lo para um valor adequado igual ou maior que MinimumBuffers.
• Se esse valor for maior que um limite determinado pelo ETW, o ETW poderá reduzi-lo ao limite.

A maioria dos usuários deve começar a ajustar sua sessão definindo MinimumBuffers e MaximumBuffers com o mesmo valor. Em seguida, você poderá aumentar o valor de MaximumBuffers se o rastreamento descartar eventos durante picos de taxa de eventos.

O ETW não poderá alocar buffers sob demanda se o evento for gerado por um driver em execução no IRQL alto. Se a sessão de rastreamento precisar registrar eventos de provedores de modo kernel de ALTO IRQL, talvez seja necessário usar um valor mais alto de MinimumBuffers para forçar os buffers a serem pré-alocados.

MaximumFileSize

Tamanho máximo do arquivo usado para registrar eventos, em megabytes ou zero para nenhum limite de tamanho. Normalmente, você usa esse membro para limitar o tamanho de um arquivo de log circular ao definir LogFileMode como EVENT_TRACE_FILE_MODE_CIRCULAR. Esse membro deverá ser definido como um valor diferente de zero se LogFileMode contiver EVENT_TRACE_FILE_MODE_PREALLOCATEou EVENT_TRACE_FILE_MODE_CIRCULAREVENT_TRACE_FILE_MODE_NEWFILE.

Se você estiver usando a unidade do sistema (a unidade que contém o sistema operacional) para registro em log, o ETW verificará se há mais 200 MB de espaço em disco, independentemente de você estar usando o parâmetro de tamanho máximo do arquivo. Portanto, se você especificar 100 MB como o tamanho máximo do arquivo de rastreamento na unidade do sistema, precisará ter 300 MB de espaço livre na unidade.

LogFileMode

Sinalizadores de registro em log para a sessão de rastreamento de eventos. Use esse membro para especificar se deseja que os eventos sejam gravados em um buffer circular na memória, em um arquivo de log ou em um consumidor em tempo real. Você também pode usar esse membro para especificar outras características de sessão, por exemplo, que a sessão é uma sessão de agente privado. Para obter uma lista de sinalizadores possíveis, consulte Constantes de modo de registro em log.

O ETW armazena eventos em buffer para sessões em tempo real quando não há consumidores em tempo real para a sessão. Observe que esse buffer é limitado. Se o limite for atingido, novos eventos serão ignorados e as funções de log falharão com STATUS_LOG_FILE_FULL. Antes do Windows Vista: Se não houver um consumidor em tempo real, os eventos serão descartados e o registro em log continuará.

Não inicie uma sessão de log em tempo real, a menos que um consumidor em tempo real consuma os eventos. Uma sessão em tempo real sem consumidores desperdiçará recursos do sistema (CPU, memória e espaço em disco para armazenar os eventos em buffer).

Se um consumidor começar a processar eventos em tempo real, os eventos armazenados em buffer serão consumidos primeiro. Depois que todos os eventos em buffer forem consumidos, a sessão começará a relatar novos eventos.

FlushTimer

Com que frequência, em segundos, todos os buffers de rastreamento não vazios são liberados. O tempo mínimo de liberação é de 1 segundo.

• Para sessões de modo de arquivo: definir FlushTimer como 0 desabilitará as liberações baseadas em tempo (a liberação ocorrerá quando o buffer for preenchido, quando a sessão for interrompida ou quando a sessão for liberada explicitamente). A maioria dos rastreamentos no modo de arquivo deve definir FlushTimer como 0 para evitar o desperdício de espaço no arquivo de rastreamento (ou seja, para que o espaço em disco não seja desperdiçado armazenando buffers quase vazios). Talvez você queira definir o temporizador como um valor diferente de zero se houver uma chance de o rastreamento não ser fechado (por exemplo, se você quiser ter certeza de obter eventos mesmo que o sistema falhe).
• Para sessões em tempo real: definir FlushTimer como 0 habilitará um tempo limite padrão de 1 segundo. As sessões em tempo real devem definir o temporizador de liberação com base na rapidez com que os dados precisam ser recebidos. Observe que um valor de temporizador mais alto reduzirá a sobrecarga da CPU para o rastreamento. A maioria dos rastreamentos em tempo real deve começar com um temporizador de 5 ou 10 segundos e ajustar o temporizador com base na necessidade.
• Para sessões em buffer (circular na memória), FlushTimer não é usado. Os dados de rastreamento serão liberados somente sob demanda (ou seja, liberados para um arquivo por meio do ControlTrace).

EnableFlags

Uma sessão do agente do sistema pode definir EnableFlags para indicar quais eventos SystemTraceProvider devem ser incluídos no rastreamento.

Esse membro pode conter um ou mais dos valores a seguir. Além dos eventos especificados, a menos que você especifique EVENT_TRACE_FLAG_NO_SYSCONFIG, o agente também registra eventos de configuração de hardware no Windows XP e eventos de configuração do sistema no Windows Server 2003 ou posterior.

• EVENT_TRACE_FLAG_ALPC (0x00100000)

  Habilita os tipos de evento ALPC .

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_CSWITCH (0x00000010)

  Habilita o seguinte tipo de evento Thread :

  • CSwitch

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_DBGPRINT (0x00040000)

  Permite que as chamadas DbgPrint e DbgPrintEx sejam convertidas em eventos ETW.

• EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)

  Habilita o seguinte tipo de evento FileIo (você também deve habilitar EVENT_TRACE_FLAG_DISK_IO):

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  Habilita os seguintes tipos de evento DiskIo :

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  Habilita o seguinte tipo de evento DiskIo :

  • DiskIo_TypeGroup2

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  Habilita o seguinte tipo de evento Thread :

  • ReadyThread

  Esse valor tem suporte no Windows 7, Windows Server 2008 R2 e posterior.

• EVENT_TRACE_FLAG_DPC (0x00000020)

  Habilita o seguinte tipo de evento PerfInfo :

  • DPC

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  Habilita os seguintes tipos de evento DiskIo :

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  Habilita os seguintes tipos de evento FileIo :

  • FileIo_OpEnd

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  Habilita o seguinte tipo de evento FileIo :

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  Habilita o seguinte tipo de evento Image :

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  Habilita o seguinte tipo de evento PerfInfo :

  • ISR

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_JOB (0x00080000)

  Esse valor tem suporte no Windows 10

• EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)

  Habilita o seguinte tipo de evento PageFault_V2 :

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  Habilita o seguinte tipo de evento PageFault_V2 :

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)

  Habilita os tipos de evento TcpIp e UdpIp .

• EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)

  Não execute um rundown de configuração do sistema.

  Esse valor tem suporte em Windows 8, Windows Server 2012 e posterior.

• EVENT_TRACE_FLAG_PROCESS (0x00000001)

  Habilita o seguinte tipo de evento Process :

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  Habilita o seguinte tipo de evento Process_V2 :

  • Process_V2_TypeGroup2

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  Habilita o seguinte tipo de evento PerfInfo :

  • SampledProfile

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_REGISTRY (0x00020000)

  Habilita os tipos de evento do Registro .

• EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)

  Habilita os tipos de evento SplitIo .

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)

  Habilita o seguinte tipo de evento PerfInfo :

  • SysCallEnter
  • SysCallExit

  Esse valor tem suporte no Windows Vista e posterior.

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  Habilita o seguinte tipo de evento Thread :

  • Thread_TypeGroup1

• EVENT_TRACE_FLAG_VAMAP (0x00008000)

  Habilita o tipo de evento map e unmap (excluindo arquivos de imagem).

  Esse valor tem suporte em Windows 8, Windows Server 2012 e posterior.

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)

  Habilita o seguinte tipo de evento PageFault_V2 :

  • PageFault_VirtualAlloc

  Esse valor tem suporte no Windows 7, Windows Server 2008 R2 e posterior.

DUMMYUNIONNAME

DUMMYUNIONNAME.AgeLimit

Não usado.

Windows 2000: Atraso de tempo antes que os buffers não utilizados sejam liberados, em minutos. O padrão é de 15 minutos.

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

Na saída, o número de buffers alocados para o pool de buffers da sessão de rastreamento de eventos.

FreeBuffers

Na saída, o número de buffers alocados, mas não utilizados no pool de buffers da sessão de rastreamento de eventos.

EventsLost

Na saída, o número de eventos que não foram registrados.

BuffersWritten

Na saída, o número de buffers gravados.

LogBuffersLost

Na saída, o número de buffers que não puderam ser gravados no arquivo de log.

RealTimeBuffersLost

Na saída, o número de buffers que não puderam ser entregues em tempo real ao consumidor.

LoggerThreadId

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

LogFileNameOffset

Deslocamento (em bytes) desde o início da memória alocada dessa estrutura até o início da cadeia de caracteres terminada em nul que contém o nome do arquivo de log.

O nome do arquivo normalmente tem uma .etl extensão. Todas as pastas no caminho já devem existir (o ETW não criará pastas para você). O caminho pode ser relativo, absoluto, local ou remoto. As variáveis de ambiente no caminho não serão expandidas. O usuário deve ter permissão para gravar na pasta.

O nome do arquivo de log é limitado a 1.024 caracteres. Se você definir LogFileMode como EVENT_TRACE_PRIVATE_LOGGER_MODE ou EVENT_TRACE_FILE_MODE_NEWFILE, reserve memória suficiente para incluir o identificador de processo que será acrescentado ao nome do arquivo para sessões de agentes privados e o número sequencial adicionado aos arquivos de log criados usando o novo modo de log de arquivos.

Se você não quiser registrar eventos em um arquivo de log (por exemplo, se especificar apenas EVENT_TRACE_REAL_TIME_MODE ), defina LogFileNameOffset como 0. Se você especificar apenas o log em tempo real e também fornecer um deslocamento com um nome de arquivo de log válido, o ETW usará o nome do arquivo de log para criar um arquivo de log sequencial e eventos de log para o arquivo de log, além de enviar os eventos para consumidores em tempo real. O ETW também criará o arquivo de log sequencial se LogFileMode for 0 e você fornecer um deslocamento com um nome de arquivo de log válido.

Se você quiser registrar eventos em um arquivo de log, deverá reservar memória suficiente para essa estrutura para incluir o nome do arquivo de log e o nome da sessão seguindo a estrutura. O nome do arquivo de log deve seguir o nome da sessão na memória. Confira comentários para obter um exemplo.

Os arquivos de rastreamento são criados usando o descritor de segurança padrão, o que significa que o arquivo de log terá a mesma ACL que o diretório pai. Se você quiser acessar os arquivos restritos, crie um diretório pai com as ACLs apropriadas.

LoggerNameOffset

Deslocamento (em bytes) desde o início da memória alocada da estrutura até o início da cadeia de caracteres terminada em nul que contém o nome da sessão.

O nome da sessão é limitado a 1.024 caracteres. O nome da sessão não diferencia maiúsculas de minúsculas. O sistema não iniciará uma nova sessão se outra sessão com o mesmo nome já estiver em execução.

Windows 2000: Os nomes de sessão diferenciam maiúsculas de minúsculas. Como resultado, sessões com nomes diferentes somente no caso são permitidas. No entanto, para reduzir a confusão, você deve garantir que seus nomes de sessão sejam exclusivos.

Comentários

Ao alocar a memória para essa estrutura, você deve alocar memória suficiente para incluir o nome da sessão e o nome do arquivo de log seguindo a estrutura. O nome da sessão deve vir antes do nome do arquivo de log na memória. Você deve copiar o nome do arquivo de log para o deslocamento, mas não copiar o nome da sessão para o deslocamento. A função StartTrace copia o nome para você.

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

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

Os eventos de provedores são gravados nos buffers de uma sessão. Quando um buffer em um arquivo ou sessão em tempo real está cheio (ou quando o FlushTimer expira), a sessão libera o buffer gravando os eventos em um arquivo de log, entregando-os a um consumidor em tempo real ou ambos. Se os buffers de uma sessão forem preenchidos mais rapidamente do que podem ser liberados, novos buffers serão alocados e adicionados ao pool de buffers da sessão, até MaximumBuffers. Além desse limite, a sessão descarta eventos de entrada até que um buffer fique disponível. Cada sessão mantém um registro do número de eventos descartados (consulte o membro EventsLost ).

Para exibir estatísticas de sessão, como EventsLost enquanto a sessão estiver em execução, chame a função ControlTrace e defina o parâmetro ControlCode como EVENT_TRACE_CONTROL_QUERY.

Requisitos

Confira também

StartTrace

ControlTrace

QueryAllTraces

Constantes do modo de registro em log

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER