StartKernelTrace

Essa função registra e inicia uma sessão de rastreamento de eventos do kernel. Você também pode habilitar o stackwalking para determinados eventos de kernel usando essa função.

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

Parâmetros

TraceHandle [out]
Armazena um identificador em uma sessão de rastreamento de eventos. Esse parâmetro será definido como zero se o identificador não for válido. Esse parâmetro não deve ser comparado com INVALID_HANDLE_VALUE. Não use esse identificador se a função falhar.

Propriedades [in, out]
Armazena um ponteiro para uma estrutura de EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES configura determinados aspectos do comportamento da sessão.

O primeiro membro da estrutura EVENT_TRACE_PROPERTIES é uma estrutura WNODE_HEADER, conhecida aqui como Wnode.

O EVENT_TRACE_PROPERTIES a seguir. Os membros do Wnode devem ser definidos para configurar o controle de rastreamento do kernel.

Buffersize
Esse membro contém o tamanho total, em bytes, da memória alocada para as propriedades da sessão de rastreamento de eventos. O tamanho da memória deve incluir espaço suficiente para armazenar os seguintes dados:

• A estrutura EVENT_TRACE_PROPERTIES.

• A cadeia de caracteres de nome da sessão.

• A cadeia de caracteres de nome do arquivo de log.

Guid
Cada sessão de rastreamento deve ter um GUID definido para fazer referência à sessão.

Para uma sessão do agente do kernel NT, esse membro deve ser definido como SystemTraceControlGuid. Para obter mais informações sobre constantes de modo de registro em log, consulte Constantes do Agente do Kernel NT.

ClientContext
Esse membro define a resolução do relógio usada quando o carimbo de data/hora de registro em log para cada evento é calculado. O valor padrão para esse membro é um contador de desempenho de consulta.

É possível especificar um dos seguintes valores:

• 1: QPC (contador de desempenho de consulta). O QPC fornece um carimbo de data/hora de alta resolução (100 nanossegundos), mas é relativamente mais caro de recuperar. Use essa resolução se você tiver altas taxas de eventos ou se o consumidor mesclar eventos de buffers diferentes. Em computadores mais antigos, o carimbo de data/hora pode não ser preciso porque, às vezes, o contador ignora devido a erros de hardware.

• 2: Hora do sistema. O tempo do sistema fornece um carimbo de data/hora de baixa resolução (10 milissegundos), mas é relativamente menos caro de recuperar. Se o volume de eventos for alto, a resolução do tempo do sistema poderá 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.

• 3: Contador de ciclo de CPU. O contador de CPU fornece o carimbo de data/hora de maior resolução e é o menos caro a ser recuperado. No entanto, o contador de CPU não é confiável e não deve ser usado na produção. Por exemplo, em alguns computadores, o temporizador altera a frequência devido a alterações térmicas e de energia, além de parar em alguns estados. Se o hardware não der suporte a esse tipo de relógio, o ETW usará a hora do sistema. No Windows Server 2003, Windows XP com SP1 e Windows XP, não há suporte para esse valor. Ele foi introduzido no Windows Server 2003 com SP1 e Windows XP com SP2.

Sinalizadores
Esse membro deve conter WNODE_FLAG_TRACED_GUID para indicar que a estrutura contém informações de rastreamento de eventos e as informações são enviadas a um agente. WNODE_FLAG_TRACED_GUID é definido em Evntrace.h.

Os seguintes membros EVENT_TRACE_PROPERTIES também devem ser definidos:

LogFileMode
Indica quais modos de registro em log devem ser usados na sessão de rastreamento de eventos do kernel. Você pode usar esse membro para especificar que os eventos devem ser gravados em um arquivo de log, um consumidor em tempo real ou ambos.

Esse membro também pode ser usado para especificar que a sessão é uma sessão de agente privado. Um ou mais modos podem ser especificados. Para obter uma lista dos modos possíveis, consulte Constantes de modo de registro em log.

Nota Não especifique o log em tempo real, a menos que haja consumidores em tempo real prontos para consumir os eventos. Se não houver consumidores em tempo real, os eventos serão gravados em um arquivo de reprodução. O tamanho do arquivo de reprodução é limitado. Se o limite for atingido, nenhum novo evento será registrado no arquivo de log ou no arquivo de reprodução. As funções de registro em log falham com STATUS_LOG_FILE_FULL.

EnableFlags
Esse membro é usado apenas para sessões de agente de kernel NT. Ele identifica para o agente do kernel quais eventos rastrear. Usando OR lógico, esse membro pode conter um ou mais valores. Além dos eventos especificados, o agente do kernel também registra eventos de configuração de hardware.

Os seguintes sinalizadores de controle de rastreamento estão disponíveis além dos fornecidos pelo EVENT_TRACE_PROPERTIES:

• EVENT_TRACE_FLAG_DISPATCHER

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC

LogFileNameOffset
Esse número representa o deslocamento desde o início da memória alocada para a estrutura até o início da cadeia de caracteres terminada em nulo que contém o nome do arquivo de log.

As seguintes considerações se aplicam:

• A extensão de nome de arquivo deve ser .etl.

• Todas as pastas no caminho devem existir.

• O caminho pode ser relativo, absoluto, local ou remoto.

• O caminho não deve conter variáveis de ambiente, pois essas variáveis não são expandidas.

• O usuário que inicia o rastreamento deve ter permissão de gravação na pasta.

• O nome do arquivo de log é limitado a 1024 caracteres.

• Se você definir LogFileMode como EVENT_TRACE_PRIVATE_LOGGER_MODE ou EVENT_TRACE_FILE_MODE_NEWFILE, aloque memória suficiente para incluir o identificador de processo que é acrescentado ao nome do arquivo para sessões de agente privado 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, especifique apenas EVENT_TRACE_REAL_TIME_MODE), defina LogFileNameOffset como zero. 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 nome do arquivo de log será usado para criar um arquivo de log sequencial e eventos de log para o arquivo de log. O arquivo de log sequencial também será criado se LogFileMode for zero 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á alocar 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.

• 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 restringir o acesso aos arquivos, crie um diretório pai com as ACLs apropriadas.

LoggerNameOffset
Esse membro representa o deslocamento desde o início da memória alocada para a estrutura até o início da cadeia de caracteres terminada em nulo que contém o nome da sessão.

As seguintes considerações se aplicam:

• O nome da sessão é limitado a 1024 caracteres.

• O nome da sessão não diferencia maiúsculas de minúsculas e deve ser exclusivo.

• Ao alocar memória para essa estrutura, a memória suficiente deve ser reservada 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. O nome do arquivo de log deve ser copiado para a área de deslocamento. Essa função grava o nome da sessão definido por KERNEL_LOGGER_NAME.

De acordo com o tipo de arquivo de log escolhido, pode ser necessário definir o membro MaximumFileSize .

Nota Não é necessário definir o nome do agente no LoggerNameOffset porque essa função sempre usa o valor KERNEL_LOGGER_NAME para chamar StartKernelTrace. Essa função verifica se o Wnode.Guid corresponde a SystemTraceControlGuid; caso contrário, retornará ERROR_INVALID_PARAMETER. Se Wnode.Guid corresponder a KernelRundownGuid, o nome do agente deverá ser especificado. O KernelRundownGuid é o GUID de controle usado para registrar eventos como informações de processo existentes, informações de thread, imagens carregadas por processo e configuração de hardware, como CPU, vídeo, disco, cartões de rede, serviços, energia, Plug and Play e canais de IDE de disco.

Valor Retornado

ERROR_SUCCESS indica êxito.

Os valores de erro possíveis são descritos na tabela a seguir.

Se a função falhar por um motivo diferente daqueles listados, um código de erro do sistema será retornado.

Comentários

Se StackTracingEventIds contiver eventos que não estão habilitados no EVENT_TRACE_PROPERTIES. O campo EnableFlags ou não pôde ser decodificado pelo Controle de Rastreamento do Kernel, esses sinalizadores são ignorados e nenhum código de erro é retornado.

Requisitos:

Versões: Disponível a partir do Windows Vista. Essa estrutura é distribuída com o Windows Performance Analyzer.

Cabeçalhos: Declarado em KernelTraceControl.h. Inclua KernelTraceControl.h.

Biblioteca: Contido em KernelTraceControl.dll.

Tópicos relacionados

Funções

Injeção personalizada de informações do sistema