Função StartTraceA (evntrace.h)

  • Artigo

A função StartTrace registra e inicia uma sessão de rastreamento de eventos.

Importante

As sessões de rastreamento de eventos entre processos são um recurso limitado do sistema. Os desenvolvedores devem evitar iniciar sessões de rastreamento de eventos em computadores cliente. Quando as sessões de rastreamento de eventos forem necessárias, elas deverão ser limitadas ao menor escopo possível: use o menor número possível de sessões, use uma sessão somente em processo, se possível (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), inicie apenas o rastreamento quando a coleção for especificamente necessária para um cenário, interrompa o rastreamento assim que o cenário for concluído, limite a quantidade de memória usada pela sessão, e usam filtros de eventos estritos para que você não colete eventos desnecessários.

Sintaxe

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parâmetros

[out] TraceHandle

Recebe o identificador para a sessão de rastreamento de eventos para uso subsequente com APIs como ControlTrace.

Não use esse identificador se a função falhar. Não compare o identificador de sessão com INVALID_HANDLE_VALUE. O identificador de sessão será 0 se o identificador não for válido.

[in] InstanceName

Cadeia de caracteres terminada em nulo que contém o nome da sessão de rastreamento de eventos. O nome da sessão é limitado a 1.024 caracteres, não diferencia maiúsculas de minúsculas e deve ser exclusivo.

Importante

Use um nome descritivo para sua sessão para que a propriedade e o uso da sessão possam ser determinados a partir do nome da sessão. Não use um GUID ou outro valor não determinístico ou não descritivo. Não acrescente dígitos aleatórios para tornar o nome da sessão exclusivo. As sessões ETW são um recurso limitado, portanto, o componente não deve iniciar várias sessões. Se a sessão do componente já estiver em execução quando o componente for iniciado, o componente deverá limpar a sessão órfã em vez de criar uma segunda sessão.

Essa função copia o nome da sessão que você fornece para o deslocamento para o qual o membro LoggerNameOffset de Properties aponta.

[in, out] Properties

Ponteiro para uma estrutura EVENT_TRACE_PROPERTIES que especifica o comportamento da sessão. Veja a seguir os principais membros da estrutura a ser definida:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

Dependendo do tipo de arquivo de log que você escolher criar, talvez você também precise especificar um valor para MaximumFileSize. Consulte a seção Comentários para obter mais informações sobre como definir o parâmetro Properties e o comportamento da sessão.

Começando com Windows 10, versão 1703: para melhorar o desempenho em cenários de processo cruzado, agora você pode passar a filtragem para StartTrace ao iniciar agentes privados de todo o sistema. Você precisará passar a nova estrutura de EVENT_TRACE_PROPERTIES_V2 para incluir informações de filtragem. Consulte Configurando e iniciando uma sessão de agente privado para obter mais detalhes.

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 de InstanceName.

  • ERROR_INVALID_PARAMETER

    Uma das seguintes condições é verdadeira:

    • As propriedades são NULL.
    • TraceHandle é NULL.
    • 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 é SystemTraceControlGuid, mas o parâmetro InstanceName não é KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Uma sessão com o mesmo nome ou GUID já está em execução.

  • ERROR_BAD_PATHNAME

    Você pode receber esse erro por um dos seguintes motivos:

    • Outra sessão já está usando o nome de arquivo especificado pelo membro LogFileNameOffset da estrutura Properties .
    • LogFileMode e LogFileNameOffset são zero.

  • ERROR_DISK_FULL

    Não há espaço livre suficiente na unidade para o arquivo de log. Isso ocorrerá se:

    • MaximumFileSize é diferente de zero e não há bytes MaximumFileSize disponíveis para o arquivo de log
    • a unidade é uma unidade do sistema e não há mais 200 MB disponíveis
    • MaximumFileSize é zero e não há mais 200 MB disponíveis

    Escolha uma unidade com mais espaço ou diminua o tamanho especificado em MaximumFileSize (se usado).

  • ERROR_ACCESS_DENIED

    Somente usuários com privilégios administrativos, 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.

    Se o usuário for membro do grupo Usuários do Log de Desempenho, ele poderá não ter permissão para criar o arquivo de log na pasta especificada.

  • ERROR_NO_SYSTEM_RESOURCES

    Uma das seguintes condições é verdadeira:

    • A sessão de registro em log usa o sinalizador EVENT_TRACE_SYSTEM_LOGGER_MODE e o número máximo de agentes do sistema (8) foi atingido.

    • O número máximo de sessões de registro em log no sistema foi atingido. Nenhum novo agente pode ser criado até que uma sessão de registro em log seja interrompida. Na maioria dos sistemas, o número máximo de sessões de registro em log é 64.

      Você pode alterar o número máximo de sessões de log para um sistema editando a chave REG_DWORD em HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. Os valores permitidos são de 32 a 256, inclusive. Uma reinicialização é necessária para que qualquer alteração entre em vigor.

      Observe que os agentes usam recursos do sistema. Aumentar o número de agentes no sistema terá um custo de desempenho se esses slots forem preenchidos. Esse limite existe para evitar o uso excessivo de recursos do sistema.

      Importante

      O limite só deve ser ajustado manualmente por um administrador do sistema para habilitar cenários específicos. A configuração EtwMaxLoggers não deve ser modificada automaticamente por um programa ou driver.

      Antes de Windows 10, versão 1709, esse é um limite fixo de 64 agentes para agentes não privados.

Comentários

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

A sessão permanece ativa até que a sessão seja interrompida, o computador seja reiniciado, ocorra um erro de E/S ou o tamanho máximo do arquivo seja atingido para logs não circulares. Para interromper uma sessão de rastreamento de eventos, chame a função ControlTrace e defina o parâmetro ControlCode como EVENT_TRACE_CONTROL_STOP.

Não é possível iniciar mais de uma sessão com o mesmo GUID de sessão (conforme especificado por Properties.Wnode.Guid). Na maioria dos casos, você definirá Properties.Wnode.Guid como all-zero ( ou seja, GUID_NULL) para permitir que o sistema ETW gere um novo GUID para a sessão.

Para especificar uma sessão de agente privado, defina o membro Wnode.Guid de Propriedades como o GUID de controle do provedor, não o GUID de controle da sessão do agente privado. O provedor deve ter registrado o GUID antes de chamar StartTrace.

Você não usa essa função para iniciar uma sessão de agente global (preterida). Para obter detalhes sobre como iniciar uma sessão de agente global, consulte Configurando e iniciando a sessão global do agente.

Agentes do sistema

Para que o agente seja um agente do sistema e receba eventos do SystemTraceProvider ou de outros provedores de sistema, qualquer um dos seguintes deve ser verdadeiro:

  • O LogFileMode do membro Propriedades inclui o sinalizador EVENT_TRACE_SYSTEM_LOGGER_MODE (preferencial).
  • O membro PropriedadesWnode.Guid está definido como SystemTraceControlGuid ou GlobalLoggerGuid (preterido – não deve ser usado para o novo código porque entrará em conflito com outros componentes que também tentam usar esses GUIDs).
  • InstanceName é definido como KERNEL_LOGGER_NAME (preterido – não deve ser usado para o novo código porque entrará em conflito com outros componentes que também tentam usar esse nome).

Observação

 Um agente do sistema deve definir o membro EnableFlags da estrutura EVENT_TRACE_PROPERTIES para indicar quais eventos SystemTraceProvider devem ser incluídos no rastreamento.

Como os agentes do sistema recebem eventos de kernel especiais, eles estão sujeitos a restrições adicionais:

  • Não pode haver mais de 8 agentes do sistema ativos no mesmo sistema.
  • Os agentes do sistema não podem ser criados em um contêiner do Windows Server.
  • Os agentes do sistema não podem usar o sinalizador EVENT_TRACE_USE_PAGED_MEMORY .
  • Antes de Windows 10, versão 1703, não mais do que dois tipos de relógio distintos podem ser usados simultaneamente por qualquer agente do sistema. Por exemplo, se um agente do sistema ativo estiver usando o tipo de relógio "contador de ciclo de CPU" e outro agente do sistema ativo estiver usando o tipo de relógio "Contador de desempenho de consulta", qualquer tentativa de iniciar um agente do sistema usando o tipo de relógio "Hora do sistema" falhará porque exigiria a ativação de um terceiro tipo de relógio. Devido a essa limitação, a Microsoft recomenda fortemente que os agentes do sistema não usem o tipo de relógio "Hora do sistema".
  • A partir do Windows 10, versão 1703, a restrição de tipo de relógio foi removida. Todos os três tipos de relógio agora podem ser usados simultaneamente por agentes do sistema.

Para especificar uma sessão NT Kernel Logger (preterida), defina InstanceName como KERNEL_LOGGER_NAME e o membro Wnode.Guid de Properties como SystemTraceControlGuid. Se você não especificar o GUID como SystemTraceControlGuid, o ETW substituirá o valor guid e o definirá como SystemTraceControlGuid.

Exemplos

Para obter um exemplo que usa StartTrace, consulte Configurando e iniciando uma sessão de rastreamento de eventos.

Observação

O cabeçalho evntrace.h define StartTrace 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

   
Cliente mínimo com suporte Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 [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
DLL Sechost.dll em Windows 8.1 e Windows Server 2012 R2; Advapi32.dll em Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista

Confira também

ControlTrace

EVENT_TRACE_PROPERTIES