Função EnableTraceEx (evntrace.h)

Artigo
06/12/2024

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.

Observação

Nem sempre há um mapeamento direto entre uma chamada para EnableTrace e uma chamada correspondente para EnableCallback do provedor. Por exemplo, se EnableTrace for chamado para um provedor que ainda não foi registrado, a chamada para EnableCallback será adiada até que o registro ocorra e, se uma sessão de consumidor de rastreamento for interrompida, o ETW invocará EnableCallback mesmo que não tenha havido uma chamada correspondente para EnableTrace. Nesses casos, EnableTrace será invocado com SourceId definido como GUID_NULL.

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.

Valor	Significado
TRACE_LEVEL_CRITICAL (1)	Eventos anormais de saída ou encerramento
TRACE_LEVEL_ERROR (2)	Eventos de erro graves
TRACE_LEVEL_WARNING (3)	Eventos de aviso, como falhas de alocação
TRACE_LEVEL_INFORMATION (4)	Eventos informativos sem erro
TRACE_LEVEL_VERBOSE (5)	Eventos de diagnóstico detalhados

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.

Observação

Vários desses sinalizadores indicam que o ETW deve incluir informações extras em cada evento. Os dados são gravados na seção de item de dados estendido do evento.

Valor	Significado
EVENT_ENABLE_PROPERTY_SID	Inclua o SID (identificador de segurança) do usuário nos dados estendidos.
EVENT_ENABLE_PROPERTY_TS_ID	Inclua o identificador de sessão do terminal nos dados estendidos.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	A sessão de rastreamento não deve registrar eventos que tenham uma palavra-chave 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

Requisito	Valor
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	Advapi32.lib
DLL	Advapi32.dll

Confira também

StartTrace

EnableTraceEx2

Compartilhar via

Função EnableTraceEx (evntrace.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Requisitos

Confira também

Comentários

Recursos adicionais