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(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Parâmetros

[in] TraceHandle

Manipule para uma sessão de rastreamento de eventos ou 0. Você deve especificar um SessionHandle diferente de zero se SessionName for NULL. O ETW ignorará o identificador se SessionName não for NULL.

A função StartTrace retorna esse identificador quando um novo rastreamento é iniciado. Para obter o identificador de um rastreamento existente, use ControlTrace para consultar as propriedades de rastreamento com base no nome do rastreamento e obter o identificador do campo Wnode.HistoricalContext dos dados retornados EVENT_TRACE_PROPERTIES .

[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 InstanceNamecomo 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 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 para a 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 somente 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 você quiser alternar para outro arquivo de log ou para liberar um rastreamento de 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 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 quiser 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, zera 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 passada 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.

Começando com Windows 10, versão 1703: para melhorar o desempenho em cenários de processo cruzado, agora você pode passar informações de filtragem para ControlTrace para agentes privados de 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ções 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 do Atualização de outubro de 2018 para o 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 do Windows 10 Atualização de outubro de 2020.

Observação

Não é seguro liberar buffers ou interromper uma sessão de rastreamento de DllMain (pode causar deadlock).

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 Properties especifica um tamanho incorreto.
  • As propriedades não têm espaço suficiente alocado para manter 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 Properties especifica uma combinação de sinalizadores que não são válidos.
  • 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 de 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 de 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 .

Observação

O cabeçalho evntrace.h define ControlTrace 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 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	evntrace.h
Biblioteca	Sechost.lib em Windows 8.1 e Windows Server 2012 R2; Advapi32.lib em Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP
DLL	Sechost.dll em Windows 8.1 e Windows Server 2012; Advapi32.dll em Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP

Confira também

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace