Função EnableTraceEx (evntrace.h)

Um controlador de sessão de rastreamento chama EnableTraceEx para configurar como um provedor de eventos ETW registra eventos em uma sessão de rastreamento.

Essa função está obsoleta. A função EnableTraceEx2 substitui essa função.

Sintaxe

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Parâmetros

[in] ProviderId

A ID do provedor (GUID de controle) do provedor de eventos que você deseja configurar.

[in, optional] SourceId

Um GUID que pode identificar exclusivamente a origem dessa solicitação de configuração ou NULL se nenhuma identidade de origem for necessária (equivalente a definir SourceId como &GUID_NULL). Se especificado, esse valor será usado como o parâmetro SourceId ao invocar EnableCallback do provedor.

TraceId

[in] IsEnabled

Defina como 1 para habilitar o recebimento de eventos do provedor ou para ajustar as configurações usadas ao receber eventos do provedor (por exemplo, para alterar o nível e as palavras-chave). Defina como 0 para desabilitar o recebimento de eventos do provedor.

[in] Level

Um valor que indica o nível máximo de eventos que você deseja que o provedor escreva. O provedor normalmente grava um evento se o nível do evento for menor ou igual a esse valor, além de atender aos critérios MatchAnyKeyword e MatchAllKeyword .

A Microsoft define a semântica dos níveis 1 a 5, conforme mostrado abaixo. Valores mais baixos indicam eventos mais graves. Cada valor de EnableLevel habilita o nível especificado e todos os níveis mais graves. Por exemplo, se você especificar TRACE_LEVEL_WARNING, o consumidor receberá aviso, erro e eventos críticos.

As TRACE_LEVEL constantes são definidas em evntrace.h. Constantes equivalentes WINMETA_LEVEL são definidas em winmeta.h.

[in] MatchAnyKeyword

Máscara de bits de 64 bits de palavras-chave que determinam as categorias de eventos que você deseja que o provedor escreva. O provedor normalmente grava um evento se os bits de palavra-chave do evento corresponderem a qualquer um dos bits definidos nesse valor ou se o evento não tiver nenhum bit de palavra-chave definido, além de atender aos critérios Level e MatchAllKeyword .

[in] MatchAllKeyword

Máscara de bits de 64 bits de palavras-chave que restringe os eventos que você deseja que o provedor grave. O provedor normalmente grava um evento se os bits de palavra-chave do evento corresponderem a todos os bits definidos nesse valor ou se o evento não tiver nenhum bit de palavra-chave definido, além de atender aos critérios Level e MatchAnyKeyword .

Esse valor é frequentemente definido como 0.

[in] EnableProperty

Sinalizadores que especificam comportamentos especiais que o runtime do ETW deve habilitar ao coletar eventos desse provedor. Para habilitar comportamentos especiais, especifique um ou mais dos sinalizadores a seguir. Caso contrário, defina EnableProperty como 0.

[in, optional] EnableFilterDesc

Uma estrutura EVENT_FILTER_DESCRIPTOR que aponta para os dados de filtro. O provedor usa isso para filtrar dados para impedir que eventos que não correspondam aos critérios de filtro sejam gravados na sessão. O provedor determina o layout dos dados e como ele aplica o filtro aos dados do evento. Uma sessão pode passar apenas um filtro para o provedor.

Uma sessão pode chamar a função TdhEnumerateProviderFilters para pesquisar os filtros para os quais um provedor registrou suporte.

Retornar valor

Se a função for bem-sucedida, 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_INVALID_PARAMETER

  Uma das seguintes condições é verdadeira:

  • ProviderId é NULL.
  • TraceHandle é NULL.

• ERROR_INVALID_FUNCTION

  Não é possível atualizar o nível quando o provedor não está registrado.

• ERROR_NO_SYSTEM_RESOURCES

  Excedeu o número de sessões de rastreamento que podem habilitar o provedor.

• ERROR_ACCESS_DENIED

  Somente usuários com privilégios administrativos, usuários no Performance Log Users grupo e serviços em execução como LocalSystem, LocalServiceou NetworkService podem habilitar provedores de eventos para uma sessão entre processos. Para conceder a um usuário restrito a capacidade de habilitar um provedor de eventos, adicione-o Performance Log Users ao grupo ou consulte EventAccessControl.

  Windows XP e Windows 2000: Qualquer pessoa pode habilitar um provedor de eventos.

Comentários

Os controladores de rastreamento de eventos chamam essa função para configurar os provedores de eventos que gravam eventos na sessão. Por exemplo, um controlador pode chamar essa função para começar a coletar eventos de um provedor, ajustar o nível ou as palavras-chave dos eventos que estão sendo coletados de um provedor ou parar de coletar eventos de um provedor.

Essa função está obsoleta. Para funcionalidade adicional, o novo código deve usar EnableTraceEx2.

Na maioria dos casos, uma chamada para EnableTraceEx pode ser convertida em EnableTraceEx2 da seguinte maneira:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

Em cenários mais complexos, uma chamada para EnableTraceEx pode ser convertida em EnableTraceEx2 da seguinte maneira:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

Para obter detalhes adicionais sobre a semântica de configuração de provedores para uma sessão, consulte a documentação de EnableTraceEx2.

Requisitos

Confira também

StartTrace

EnableTraceEx2