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,
[in] TRACEHANDLE TraceHandle,
[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 haja uma chamada correspondente para EnableTrace. Nesses casos, EnableTrace será invocado com SourceId definido como GUID_NULL.
[in] TraceHandle
Identificador da sessão de rastreamento de eventos para a qual você está configurando o provedor.
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, em seguida, obter o identificador do campo Wnode.HistoricContext dos dados retornados EVENT_TRACE_PROPERTIES .
[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, seu 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 grave |
| 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 palavra-chave do evento corresponderem a qualquer um dos bits definidos nesse valor ou se o evento não tiver palavra-chave bits definidos, 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 palavra-chave do evento corresponderem a todos os bits definidos nesse valor ou se o evento não tiver palavra-chave bits definidos, 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 um palavra-chave de 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.
Valor retornado
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 Usersgrupo e serviços em execução comoLocalSystem,LocalServiceouNetworkServicepodem 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 aoPerformance Log Usersgrupo 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
| 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de