Configuração e início de uma sessão de rastreamento de eventos
Para configurar uma sessão de rastreamento de eventos, use a estrutura EVENT\_TRACE\_PROPERTIES para especificar as propriedades da sessão. A memória alocada para a estrutura EVENT_TRACE_PROPERTIES deve ser grande o suficiente para conter também os nomes de sessão e arquivo de log que seguem a estrutura na memória.
Depois de especificar as propriedades da sessão, chame a função StartTrace para iniciar a sessão. Se a função for bem-sucedida, o parâmetro SessionHandle conterá o identificador de sessão e a propriedade LoggerNameOffset conterá o deslocamento para o nome da sessão.
Para habilitar os provedores que você deseja registrar eventos na sessão, chame a função EnableTrace para habilitar provedores clássicos e a função EnableTraceEx para habilitar provedores baseados em manifesto. Para habilitar os provedores que você deseja registrar eventos na sessão filtrando em condições específicas no Windows 8.1, no Windows Server 2012 R2 e posteriores, chame a função EnableTraceEx2.
Além disso, você também pode rastrear informações adicionais sobre um evento com uma chamada para a função TraceSetInformation. TraceSetInformation coloca informações de rastreamento adicionais na seção de dados estendidos de um evento e pode incluir informações como as informações da versão do rastreamento ou quais provedores estão registrados no sistema no momento. Para obter mais informações, consulte Recuperação dos dados de rastreamento de eventos adicionais.
Até oito sessões de rastreamento podem habilitar e receber eventos do mesmo provedor baseado em manifesto. No entanto, só uma sessão de rastreamento pode habilitar um provedor clássico. Se mais de uma sessão de rastreamento tentasse habilitar um provedor clássico, a primeira sessão deixaria de receber eventos quando a segunda sessão habilitasse o provedor. Por exemplo, se a sessão A tivesse habilitado o provedor 1 e, em seguida, a sessão B tivesse habilitado o provedor 1, só a sessão B receberia eventos do provedor 1.
Você pode usar qualquer uma das três funções para habilitar um provedor, mas poderá perder a funcionalidade se usar EnableTrace para habilitar um provedor baseado em manifesto, pois você não poderá fornecer um valor MatchAllKeyword, especificar itens de dados estendidos a serem incluídos no evento ou fornecer dados de filtro definidos pelo provedor. Para obter mais informações, consulte a seção Comentários de cada função.
No Windows 8.1, no Windows Server 2012 R2 e posteriores, os filtros de carga de evento, escopo e caminhada de pilha podem ser usados pela função EnableTraceEx2 e pelas estruturas ENABLE_TRACE_PARAMETERS e EVENT_FILTER_DESCRIPTOR para filtrar condições específicas em uma sessão do agente de log. Para obter mais informações sobre filtros de payload de evento, consulte as funções TdhCreatePayloadFilter e TdhAggregatePayloadFilters e as estruturas ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTOR e PAYLOAD_FILTER_PREDICATE.
Para determinar o nível e as palavras-chave usadas para habilitar um provedor baseado em manifesto, use um dos seguintes comandos:
- Logman query provider-name
- Wevtutil gp provider-name
Os comandos só listam o nível e as palavras-chave, e o provedor deve documentar todos os requisitos de dados do filtro para controladores potenciais.
Para enumerar os provedores baseados em manifesto, use Wevtutil ep.
Para provedores clássicos, cabe ao provedor documentar e disponibilizar para possíveis controladores os níveis de gravidade ou habilitar sinalizadores aos quais ele dá suporte. Se quiser ser habilitado por qualquer controlador, o provedor deverá aceitar 0 para o nível de gravidade e habilitar sinalizadores e interpretar 0 como uma solicitação para realizar o log padrão (seja lá o que for).
Você pode habilitar o provedor antes ou depois que ele se registrar. Depois de habilitar o provedor, o ETW vai acabar chamando a função de retorno de chamada do provedor. Se o provedor não estiver registrado, o ETW chamará a função de retorno de chamada do provedor depois que ele se registrar.
Você também pode usar a função EnableTrace para desabilitar o provedor (impedi-lo de registrar eventos na sessão) ou para atualizar o nível de log ou habilitar sinalizadores do provedor. Com a função EnableTraceEx , você pode desabilitar o provedor ou atualizar o nível, as palavras-chave, os dados estendidos e os dados de filtro. Sempre que você chama a função EnableTrace ou EnableTraceEx , o ETW chama a função de retorno de chamada do provedor. O provedor permanece habilitado para a sessão até que a sessão desabilite o provedor.
Para interromper a sessão de rastreamento após a coleta de eventos, chame a função ControlTrace e passe EVENT_TRACE_CONTROL_STOP como o código de controle. Para especificar a sessão a ser interrompida, você pode passar o identificador de sessão de rastreamento de eventos obtido de uma chamada anterior para a função StartTrace ou o nome de uma sessão iniciada anteriormente. Não se esqueça de desabilitar todos os provedores antes de interromper a sessão. Se você interromper a sessão antes de desabilitar o provedor pela primeira vez, o ETW desabilitará o provedor e tentará chamar a função de retorno de chamada de controle do provedor. Se o aplicativo que iniciou a sessão terminar sem desabilitar o provedor ou chamar a função ControlTrace , o provedor permanecerá habilitado.
Se ControlTrace for bem-sucedido, as propriedades da sessão serão atualizadas para refletir os valores finais da propriedade e executar estatísticas para a sessão de rastreamento de eventos.
Para obter um exemplo que inicia uma sessão de rastreamento de eventos, consulte o seguinte:
- Exemplo que cria uma sessão e habilita um provedor baseado em manifesto – inicia uma sessão de rastreamento, habilita um provedor baseado em manifesto, desabilita o provedor e interrompe a sessão.
Para obter detalhes sobre como iniciar uma sessão de rastreamento, consulte um dos seguintes:
- Configuração e início de uma sessão SystemTraceProvider
- Configuração e início da sessão do NT Kernel Logger
- Configuração e início de uma sessão do AutoLogger
- Configuração e início da sessão do agente de log global
- Configuração e início de uma sessão de agente de log privado
Tópicos relacionados