Função ControlTraceA (evntrace.h)

A função ControlTrace libera, consulta, atualiza ou interrompe a sessão de rastreamento de eventos especificada.

Sintaxe

ULONG WMIAPI ControlTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Parâmetros

TraceId

[in] InstanceName

Nome de uma sessão de rastreamento de eventos ou NULL. Você deve especificar InstanceName se TraceHandle for 0.

Para especificar a sessão do Agente do Kernel NT, defina InstanceName como KERNEL_LOGGER_NAME.

[in, out] Properties

Ponteiro para uma estrutura de EVENT_TRACE_PROPERTIES inicializada. Essa estrutura deve ser zerado antes de definir qualquer campo.

Se ControlCodeespecificar EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY ou EVENT_TRACE_CONTROL_FLUSH, você só precisará definir os membros Wnode.BufferSize, Wnode.Guid, LoggerNameOffset e LogFileNameOffset da estrutura EVENT_TRACE_PROPERTIES . Se a sessão for uma sessão privada, você também precisará definir LogFileMode. Você pode usar o nome máximo da sessão (1024 caracteres) e os comprimentos máximos do nome do arquivo de log (1024 caracteres) para calcular o tamanho e os deslocamentos do buffer, se não forem conhecidos.

Se ControlCodeespecificar EVENT_TRACE_CONTROL_UPDATE, na entrada, os membros deverão especificar os novos valores para as propriedades a serem atualizadas. Na saída, Properties contém as propriedades e estatísticas da sessão de rastreamento de eventos. Você pode atualizar as propriedades a seguir.

• EnableFlags: defina esse membro como 0 para desabilitar todos os provedores do sistema. Defina isso como um valor diferente de zero para especificar os provedores de sistema que você deseja habilitar ou manter habilitados. Isso pode ser diferente de zero apenas para agentes do sistema.

• FlushTimer: defina esse membro se quiser alterar o tempo de espera antes de liberar buffers. Se esse membro for 0, o membro não será atualizado.

• LogFileNameOffset: defina esse membro se quiser alternar para outro arquivo de log ou liberar um rastreamento do modo de buffer para um novo arquivo de log. Se esse membro for 0, o nome do arquivo não será atualizado. Se o deslocamento não for zero e você não alterar o nome do arquivo de log, a função retornará um erro.

• LogFileMode: defina esse membro se quiser ativar e desativar EVENT_TRACE_REAL_TIME_MODE . Para desativar o consumo em tempo real, defina esse membro como 0. Para ativar o tempo real (criando uma sessão que registra em disco, bem como entregando eventos em tempo real), defina esse membro como EVENT_TRACE_REAL_TIME_MODE e ele será OR'd com os modos atuais.

• MaximumBuffers: defina esse membro se desejar alterar o número máximo de buffers que o ETW usa. Se esse membro for 0, o membro não será atualizado.

Para sessões de agente privado, você pode atualizar apenas os membros LogFileNameOffset e FlushTimer .

Se você estiver usando uma estrutura de EVENT_TRACE_PROPERTIES recém-inicializada, remova a estrutura e defina Wnode.BufferSize, Wnode.Guid e Wnode.Flags e os valores que deseja atualizar.

Se você estiver reutilizando uma estrutura EVENT_TRACE_PROPERTIES (ou seja, usando uma estrutura que você passou anteriormente para StartTrace ou ControlTrace), defina o membro LogFileNameOffset como 0, a menos que você esteja alterando o nome do arquivo de log e certifique-se de definir EVENT_TRACE_PROPERTIES. Wnode.Flags para WNODE_FLAG_TRACED_GUID.

A partir do Windows 10, versão 1703: Para obter um melhor desempenho em cenários de processo cruzado, agora você pode passar informações de filtragem para ControlTrace para agentes privados em todo o sistema. Você precisará usar a estrutura EVENT_TRACE_PROPERTIES_V2 para incluir informações de filtragem. Consulte Configurando e iniciando uma sessão de agente privado para obter mais detalhes.

[in] ControlCode

Função de controle solicitada. É possível especificar um dos seguintes valores:

• EVENT_TRACE_CONTROL_FLUSH: libera os buffers ativos da sessão.

  Isso pode ser usado com uma sessão na memória (uma sessão iniciada com o sinalizador EVENT_TRACE_BUFFERING_MODE ) para gravar os dados do rastreamento em um arquivo.

  Normalmente, você não precisa liberar sessões baseadas em arquivo ou em tempo real porque o ETW liberará automaticamente um buffer quando ele estiver cheio (ou seja, quando ele não tiver espaço para o próximo evento), quando o FlushTimer da sessão de rastreamento expirar ou quando a sessão de rastreamento for fechada.

  Windows 2000: Não há suporte para esse valor.

• EVENT_TRACE_CONTROL_QUERY: recupera as propriedades e estatísticas da sessão.

• EVENT_TRACE_CONTROL_STOP: interrompe a sessão. O identificador de sessão não é mais válido.

• EVENT_TRACE_CONTROL_UPDATE: atualiza as propriedades da sessão.

• EVENT_TRACE_CONTROL_INCREMENT_FILE: se a sessão tiver o EVENT_TRACE_FILE_MODE_NEWFILE, atualizará a sessão para alternar para o próximo arquivo imediatamente, em vez de aguardar o preenchimento do arquivo anterior. Com suporte a partir da Atualização de outubro de 2018 do Windows 10.

• EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: altera uma sessão de modo de arquivo para uma sessão em tempo real (habilita a entrega em tempo real e desabilita a gravação de eventos no arquivo ETL). Com suporte a partir da Atualização de outubro de 2020 do Windows 10.

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos códigos de erro do sistema. Veja a seguir alguns erros comuns e suas causas.

• ERROR_BAD_LENGTH

  Uma das seguintes condições é verdadeira:

  • O membro Wnode.BufferSize de Propriedades especifica um tamanho incorreto.
  • As propriedades não têm espaço suficiente alocado para conter uma cópia do nome da sessão e do nome do arquivo de log (se usado).

• ERROR_INVALID_PARAMETER

  Uma das seguintes condições é verdadeira:

  • As propriedades são NULL.
  • InstanceName e TraceHandle são NULL.
  • InstanceName é NULL e TraceHandle não é um identificador válido.
  • O membro LogFileNameOffset de Properties não é válido.
  • O membro LoggerNameOffset de Properties não é válido.
  • O membro LogFileMode de Propriedades especifica uma combinação de sinalizadores que não é válida.
  • O membro Wnode.Guid de Properties é SystemTraceControlGuid, mas o parâmetro InstanceName não KERNEL_LOGGER_NAMEé .

• ERROR_BAD_PATHNAME

  Outra sessão já está usando o nome do arquivo especificado pelo membro LogFileNameOffset da estrutura Properties .

• ERROR_MORE_DATA

  O buffer para EVENT_TRACE_PROPERTIES é muito pequeno para conter todas as informações da sessão. Se você não precisar das informações de propriedade da sessão, poderá ignorar esse erro. Se você receber esse erro ao interromper a sessão, o ETW já terá interrompido a sessão antes de gerar esse erro.

• ERROR_ACCESS_DENIED

  Somente usuários em execução com privilégios administrativos elevados, usuários no grupo Usuários do Log de Desempenho e serviços em execução como LocalSystem, LocalService, NetworkService podem controlar sessões de rastreamento de eventos. Para conceder a um usuário restrito a capacidade de controlar sessões de rastreamento, adicione-as ao grupo Usuários do Log de Desempenho. Somente usuários com privilégios administrativos e serviços em execução como LocalSystem podem controlar uma sessão do Agente do Kernel NT.

  Windows XP e Windows 2000: Qualquer pessoa pode controlar uma sessão de rastreamento.

• ERROR_WMI_INSTANCE_NOT_FOUND

  A sessão fornecida não está em execução.

Comentários

Os controladores de rastreamento de eventos chamam essa função.

Essa função substitui as funções FlushTrace, QueryTrace, StopTrace e UpdateTrace .

Requisitos

Confira também

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace