Função EnableTraceEx2 (evntrace.h)

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

Essa função substitui as funções EnableTrace e EnableTraceEx.

Sintaxe

ULONG WMIAPI EnableTraceEx2(
                 CONTROLTRACE_ID          TraceId,
  [in]           LPCGUID                  ProviderId,
  [in]           ULONG                    ControlCode,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    Timeout,
  [in, optional] PENABLE_TRACE_PARAMETERS EnableParameters
);

Parâmetros

TraceId

[in] ProviderId

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

[in] ControlCode

Você pode especificar um dos seguintes códigos de controle:

[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 Level 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 constantes TRACE_LEVEL são definidas em evntrace.h. As constantes de WINMETA_LEVEL equivalentes 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 qualquer dos bits definidos nesse valor ou se o evento não tiver nenhum conjunto de bits de palavra-chave, além de atender aos critérios de de Nível e MatchAllKeyword critérios.

[in] MatchAllKeyword

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

Esse valor é frequentemente definido como 0.

[in] Timeout

Se tempo limite for 0, essa função começará a configurar o provedor de forma assíncrona e retornará imediatamente (ou seja, retornará sem esperar que os retornos de chamada do provedor sejam concluídos).

Caso contrário, essa função começará a configurar o provedor e começará a aguardar a conclusão da configuração, inclusive aguardando a conclusão de todos os retornos de chamada do provedor. Se a configuração for concluída antes do tempo limite especificado, essa função retornará ERROR_SUCCESS. Caso contrário, essa função retornará ERROR_TIMEOUT.

Para esperar para sempre, defina como INFINITE .

[in, optional] EnableParameters

Os parâmetros de rastreamento usados para habilitar o provedor. Para obter detalhes, consulte ENABLE_TRACE_PARAMETERS.

Valor de retorno

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

  Um parâmetro está incorreto.

  Isso poderá ocorrer se qualquer uma das seguintes opções for verdadeira:

  • O ProviderId é NULL.
  • O TraceHandle é 0.

• ERROR_TIMEOUT

  O valor do tempo limite expirou antes da conclusão do retorno de chamada de habilitação. Para obter detalhes, consulte o parâmetro Timeout.

• ERROR_INVALID_FUNCTION

  Você não pode 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 grupo Performance Log Users 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 ao grupo Performance Log Users ou veja EventAccessControl.

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

Observações

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 coletados de um provedor ou parar de coletar eventos de um provedor.

O comportamento de habilitação para um provedor depende de quais APIs o provedor usa.

• Um provedor que usa RegisterTraceGuids (por exemplo, um provedor que usa WPP ou MOF baseado em TMF) usa o sistema de habilitação herdado (às vezes chamado de "ETW clássico"). Quando um provedor herdado é habilitado ou reconfigurado para uma sessão, o runtime do ETW notifica o provedor e fornece acesso ao nível, aos 32 bits baixos da máscara MatchAnyKeyword e à ID da sessão. Em seguida, o provedor usa sua própria lógica para decidir quais eventos devem ser habilitados e envia esses eventos diretamente para a sessão especificada. Os dados de evento enviados ao ETW em runtime incluem o GUID de decodificação do evento e a ID da mensagem, mas não incluem o GUID de controle do evento, o nível ou as palavras-chave. O ETW verifica se o provedor tem as permissões necessárias e adiciona os dados de evento à sessão especificada.
  • Como os eventos são enviados diretamente para uma sessão específica sem informações de guid de controle, nível ou palavra-chave, o ETW não pode executar nenhuma filtragem ou roteamento adicional para provedores que usam o sistema de habilitação herdado. Cada evento pode ser roteado para no máximo uma sessão.
• Um provedor que usa eventRegister (por exemplo, um provedor baseado em manifesto ou um provedor traceLogging) usa o sistema de habilitação moderno (às vezes chamado de "ETW vermelho"). Quando um provedor moderno é habilitado ou reconfigurado para uma sessão, o runtime do ETW notifica o provedor com o nível, a máscara MatchAnyKeyword de 64 bits, a máscara MatchAllKeyword de 64 bits e todos os dados de filtragem personalizados do lado do provedor especificados pelo controlador de rastreamento. Em seguida, o provedor usa sua própria lógica para decidir quais eventos devem ser habilitados, embora a maioria dos provedores apenas duplica a lógica de EventProviderEnabled. O provedor envia os eventos habilitados ao ETW para roteamento. Os dados de evento enviados ao ETW incluem o GUID de controle do evento, a ID da mensagem, o nível e as palavras-chave. Em seguida, o ETW executa filtragem adicional conforme apropriado, roteando o evento para as sessões apropriadas.
  • Como os eventos são enviados ao ETW com informações descritivas, o ETW pode executar filtragem e roteamento adicionais antes de adicionar o evento à sessão. Os eventos podem ser roteado para mais de uma sessão, se apropriado.

Para provedores que usam o sistema de habilitação moderno (ou seja, provedores que usam EventRegister), o ETW dá suporte a vários recursos que podem ser solicitados pelo controlador de sessão de rastreamento por meio de EnableTraceEx2EnableParameters. (Consulte EVENT_FILTER_DESCRIPTOR para obter detalhes.)

• de filtragem esquematizada – essa é a configuração de filtragem tradicional, também chamada de filtragem do lado do provedor. O controlador define um conjunto personalizado de filtros como um objeto binário que é passado para o provedor no FilterData do EnableCallback. Cabe ao controlador e ao provedor definir e interpretar esses filtros. Em seguida, o provedor pode usar o parâmetro EventWriteExFilter para indicar sessões para as quais um evento não deve ser enviado devido à filtragem do lado do provedor. Isso requer um acoplamento próximo do controlador e do provedor, pois o tipo e o formato do objeto binário do que pode ser filtrado não está definido. A função TdhEnumerateProviderFilters pode ser usada para recuperar os filtros definidos em um manifesto.
• de filtragem de escopo – determinados provedores estão habilitados ou não para uma sessão com base em se atendem ou não aos critérios especificados pelos filtros de escopo. Há vários tipos de filtros de escopo que permitem filtragem com base na ID do processo (PID), no nome do arquivo executável, na ID do aplicativo e no nome do pacote do aplicativo. Esse recurso tem suporte no Windows 8.1, Windows Server 2012 R2 e posterior.
• de filtragem do Stackwalk – isso notifica o ETW para executar apenas uma caminhada de pilha para um determinado conjunto de IDs de evento ou nomes de eventos (para eventos traceLogging). Esse recurso tem suporte no Windows 8.1, Windows Server 2012 R2 e posterior.
• de filtragem de atributo – para provedores de manifesto, os eventos podem ser filtrados com base em atributos de evento, como nível, palavra-chave, ID do evento ou nome do evento.
• de filtragem de conteúdo de evento – para provedores de manifesto, os eventos podem ser filtrados em tempo real com base em se atendem ou não a uma expressão lógica com base em um ou mais predicados.

Sempre que EnableTraceEx2 é chamado, os filtros para o provedor nessa sessão são substituídos pelos novos parâmetros definidos pelos parâmetros passados para a função EnableTraceEx2 . Vários filtros passados em uma única chamada EnableTraceEx2 podem ser combinados com um efeito aditivo, mas os filtros passados em uma chamada subsequente substituirão o conjunto anterior de filtros.

Para desabilitar a filtragem e habilitar todos os provedores/eventos na sessão de log, chame EnableTraceEx2 com o parâmetro EnableParameters apontando para uma estrutura de ENABLE_TRACE_PARAMETERS com o membro FilterDescCount definido como 0.

Cada filtro passado para a função EnableTraceEx2 é especificado por um membro tipo no EVENT_FILTER_DESCRIPTOR. Uma matriz de estruturas de EVENT_FILTER_DESCRIPTOR é passada na estrutura ENABLE_TRACE_PARAMETERS passada no parâmetro EnableParameters para a função EnableTraceEx2.

Cada tipo de filtro (um membro tipo de específico) só pode aparecer uma vez em uma chamada para a função EnableTraceEx2. Alguns tipos de filtro permitem que várias condições sejam incluídas em um único filtro. O número máximo de filtros que podem ser incluídos em uma chamada para EnableTraceEx2 é definido por MAX_EVENT_FILTERS_COUNT (definido no arquivo de cabeçalho Evntprov.h; o valor pode ser alterado em versões futuras do SDK do Windows).

Cada tipo de filtro tem seus próprios limites de tamanho ou entidade com base no membro tipo específico na estrutura EVENT_FILTER_DESCRIPTOR. A lista abaixo indica esses limites.

• EVENT_FILTER_TYPE_SCHEMATIZED

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Número de elementos permitidos: Definido por provedor e controlador

• EVENT_FILTER_TYPE_PID

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Número de elementos permitidos: MAX_EVENT_FILTER_PID_COUNT (8)

• EVENT_FILTER_TYPE_EXECUTABLE_NAME

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Número de elementos permitidos: uma única cadeia de caracteres que pode conter vários nomes de arquivo executáveis separados por ponto-e-vírgula.

• EVENT_FILTER_TYPE_PACKAGE_ID

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Número de elementos permitidos: uma única cadeia de caracteres que pode conter várias IDs de pacote separadas por ponto-e-vírgula.

• EVENT_FILTER_TYPE_PACKAGE_APP_ID

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_DATA_SIZE (1024)
  • Número de elementos permitidos: uma única cadeia de caracteres que pode conter várias PRAIDs (IDs de aplicativo relativas ao pacote) separadas por ponto-e-vírgula.

• EVENT_FILTER_TYPE_PAYLOAD

  • Limite de tamanho do filtro: MAX_EVENT_FILTER_PAYLOAD_SIZE (4096)
  • Número de elementos permitidos: 1

• EVENT_FILTER_TYPE_EVENT_ID

  • Limite de tamanho do filtro: não definido
  • Número de elementos permitidos: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

• EVENT_FILTER_TYPE_STACKWALK

  • Limite de tamanho do filtro: não definido
  • Número de elementos permitidos: MAX_EVENT_FILTER_EVENT_ID_COUNT (64)

Palavras-chave definem categorias de evento. Por exemplo, se o provedor definir InitializationKeyword = 0x1 (palavra-chave bit 0), FileOperationKeyword = 0x2 (palavra-chave bit 1) e CalculationKeyword = 0x4 (palavra-chave bit 2), você pode definir MatchAnyKeyword para (InitializationKeyword | CalculationKeyword) = 5 para receber eventos de inicialização e cálculo, mas não eventos de arquivo.

Quando usado com provedores modernos ( baseados em manifesto ou TraceLogging), um valor MatchAnyKeyword de 0 é tratado da mesma forma que um MatchAnyKeyword valor de 0xFFFFFFFFFFFFFFFF, ou seja, habilita todas as palavras-chave de evento. No entanto, esse comportamento não se aplica a provedores herdados (MOF ou WPP baseado em TMF). Para habilitar todas as palavras-chave de evento de um provedor herdado, defina MatchAnyKeyword como 0xFFFFFFFF. Para habilitar todas as palavras-chave de evento de provedores herdados e modernos, defina MatchAnyKeyword como 0xFFFFFFFFFFFFFFFF.

Se a palavra-chave de um evento for zero, o provedor gravará o evento na sessão, independentemente do MatchAnyKeyword e máscaras de MatchAllKeyword. (Esse comportamento pode ser desabilitado usando o sinalizador EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0.)

Para indicar que você deseja habilitar um Grupo de Provedores, use o sinalizador EVENT_ENABLE_PROPERTY_PROVIDER_GROUP no enableProperty membro do EnableParameters.

Quando você chama EnableTraceEx2, o provedor pode ou não estar registrado. Se o provedor já estiver registrado, o ETW chamará a função de retorno de chamada do provedor (se houver) e a sessão começará a receber eventos. Se o provedor ainda não estiver registrado, o ETW chamará a função de retorno de chamada do provedor (se houver) imediatamente após o provedor se registrar e a sessão começará a receber eventos. Se o provedor ainda não estiver registrado, a função de retorno de chamada do provedor não receberá a ID de origem.

Se o provedor estiver registrado e já estiver habilitado para sua sessão, você pode chamar EnableTraceEx2 novamente para atualizar os parâmetros Level, MatchAnyKeyword, Parâmetros de MatchAllKeyword e os EnableProperty e EnableFilterDesc membros do EnableParameters.

No Windows 8.1, no Windows Server 2012 R2 e posterior, os filtros de conteúdo, escopo e caminhada de pilha podem ser usados pela função EnableTraceEx2 e as estruturas ENABLE_TRACE_PARAMETERS e EVENT_FILTER_DESCRIPTOR para filtrar em condições específicas em uma sessão do agente. Para obter mais informações sobre filtros de conteúdo de evento, consulte as funções TdhCreatePayloadFiltere TdhAggregatePayloadFilters e as estruturas ENABLE_TRACE_PARAMETERS, EVENT_FILTER_DESCRIPTORe PAYLOAD_FILTER_PREDICATE.

Eventos especiais do provedor de rastreamento do sistema não podem ser habilitados ou desabilitados EnableTraceEx2. Eles só podem ser habilitados por meio do campo EnableFlags de EVENT_TRACE_PROPERTIES quando o rastreamento é iniciado pela primeira vez por StartTrace.

A partir do Windows 11, eventos do provedor de rastreamento do sistema podem ser habilitados usando EnableTraceEx2.

Até oito sessões de rastreamento podem habilitar e receber eventos do mesmo provedor moderno ( baseado em manifesto ou TraceLogging). No entanto, apenas uma sessão de rastreamento pode habilitar um provedor herdado (MOF, WPP baseado em TMF). Se mais de uma sessão tentar habilitar um provedor herdado, a primeira sessão interromperá o recebimento de eventos quando a segunda sessão habilitar o mesmo provedor. Por exemplo, se a Sessão A habilitasse um provedor herdado e a Sessão B habilitasse o mesmo provedor, somente a Sessão B receberia eventos desse provedor.

Um provedor permanece habilitado para a sessão até que a sessão desabilite o provedor. Se o aplicativo que iniciou a sessão terminar sem desabilitar o provedor, o provedor permanecerá habilitado.

Para determinar o nível e as palavras-chave usadas para habilitar um provedor baseado em manifesto, use um dos seguintes comandos:

• provedores de consulta do logman de nome do provedor
• wevtutil gp provider-name

Para provedores clássicos, cabe ao provedor documentar e disponibilizar aos controladores potenciais os níveis de severidade ou habilitar sinalizadores compatíveis. Se o provedor quiser ser habilitado por qualquer controlador, o provedor deverá aceitar 0 para o nível de severidade e habilitar sinalizadores e interpretar 0 como uma solicitação para executar o registro em log padrão (o que quer que seja).

Se você usar EnableTraceEx2 para habilitar um provedor clássico, a seguinte tradução ocorrerá:

• O parâmetro Level é o mesmo que definir o parâmetro EnableLevel em EnableTrace.
• O MatchAnyKeyword é o mesmo que definir o parâmetro EnableFlag em EnableTrace exceto que o valor da palavra-chave é truncado de um valor de 64 bits para um valor de 32 bits.
• No de retorno de chamada do ControlCallback, o provedor pode chamar GetTraceEnableLevel para obter o nível e GetTraceEnableFlags para obter o sinalizador de habilitação.
• O outro parâmetro não é usado.

Exemplos

O exemplo a seguir mostra o uso do EnableTraceEx2 com filtros de carga usando as funções TdhCreatePayloadFilter e TdhAggregatePayloadFilters para filtrar condições específicas em uma sessão de agente.

#define INITGUID
#include <windows.h>
#include <stdlib.h>
#include <stdio.h>
#include <strsafe.h>
#include <evntrace.h>
#include <tdh.h>

#define MAXIMUM_SESSION_NAME 1024

#define PATH_TO_MANIFEST_FILE L"c:\\ExampleManifest.man"

//
// The following definitions would be found in the include file generated by
// message compiler from the manifest file.
//

// Provider Example-Provider Event Count 2
EXTERN_C __declspec(selectany) const GUID EXAMPLE_PROVIDER = {0x37a59b93, 0xbb25, 0x4cee, {0x97, 0xaa, 0x8b, 0x6a, 0xcd, 0xc, 0x4d, 0xf8}};

//
// Event Descriptors
//
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_1 = { 0x1, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_1_value 0x1
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR Example_Event_2 = { 0x2, 0x0, 0x0, 0x1, 0x0, 0x0, 0x0 };
#define Example_Event_2_value 0x2

//
// (End of snippet from include file)
//

// Allocate an EVENT_TRACE_PROPERTIES structure and set the needed logging session properties
PEVENT_TRACE_PROPERTIES AllocateTraceProperties(
    _In_opt_ PCWSTR LoggerName,
    _In_opt_ PCWSTR LogFileName
)
{
    PEVENT_TRACE_PROPERTIES TraceProperties = NULL;
    ULONG BufferSize;

    BufferSize = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME + MAX_PATH) * sizeof(WCHAR);

    TraceProperties = (PEVENT_TRACE_PROPERTIES)malloc(BufferSize);
    if (TraceProperties == NULL) {
        printf("Unable to allocate %d bytes for properties structure.\n", BufferSize);
        goto Exit;
    }

    //
    // Set the session properties.
    //
    ZeroMemory(TraceProperties, BufferSize);
    TraceProperties->Wnode.BufferSize = BufferSize;
    TraceProperties->Wnode.Flags = WNODE_FLAG_TRACED_GUID;
    TraceProperties->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
    TraceProperties->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAXIMUM_SESSION_NAME * sizeof(WCHAR));

    if (LoggerName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LoggerNameOffset),
            MAXIMUM_SESSION_NAME,
            LoggerName);
    }

    if (LogFileName != NULL) {
        StringCchCopyW((LPWSTR)((PCHAR)TraceProperties + TraceProperties->LogFileNameOffset),
            MAX_PATH,
            LogFileName);
    }

Exit:
    return TraceProperties;
}

// Free the EVENT_TRACE_PROPERTIES structure previously allocated
VOID FreeTraceProperties(
    _In_ PEVENT_TRACE_PROPERTIES TraceProperties
)
{
    free(TraceProperties);
    return;
}

// Set the values needed in a PAYLOAD_FILTER_PREDICATE for a single payload filter
FORCEINLINE VOID PayloadPredicateCreate(
    _Out_ PAYLOAD_FILTER_PREDICATE* Predicate,
    _In_ PCWSTR FieldName,
    USHORT CompareOp,
    PCWSTR Value
)
{
    Predicate->FieldName = (PWSTR)FieldName;
    Predicate->CompareOp = CompareOp;
    Predicate->Value = (PWSTR)Value;
    return;
}

int __cdecl wmain()
{
    UINT i;
    PVOID EventFilters[2];
    EVENT_FILTER_DESCRIPTOR FilterDescriptor;
    UINT PredicateCount;
    PAYLOAD_FILTER_PREDICATE Predicates[3];
    ULONG FilterCount;
    ULONG Status = ERROR_SUCCESS;
    TRACEHANDLE SessionHandle = 0;
    PEVENT_TRACE_PROPERTIES TraceProperties;
    BOOLEAN TraceStarted = FALSE;
    PCWSTR LoggerName = L"MyTrace";
    ENABLE_TRACE_PARAMETERS EnableParameters;

    ZeroMemory(EventFilters, sizeof(EventFilters));
    ZeroMemory(Predicates, sizeof(Predicates));
    TraceProperties = NULL;
    FilterCount = 0;

    //
    // Load the manifest for the provider
    //
    Status = TdhLoadManifest((PWSTR)PATH_TO_MANIFEST_FILE);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    //
    // INCLUDE Example_Event_1 IF
    //     Example_Event_1.Initiator == "User" AND
    //     7 <= Example_Event_1.Level <= 16
    //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        (PWSTR)L"Initiator",
        PAYLOADFIELD_IS,
        (PWSTR)L"User");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Level",
        PAYLOADFIELD_BETWEEN,
        L"7,16");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_1,
        FALSE,      // Match all predicates (AND)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Create predicates that match the following high-level expression:
    // INCLUDE Example_Event_2 IF
    //      Example_Event_2.Title CONTAINS "UNI" OR
    //      Example_Event_2.InstanceId == {0E95CFBC-58D4-44BA-BE40-E63A853536DF} OR
    //      Example_Event_2.ErrorCode != 0      //
    PredicateCount = 0;

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"Title",
        PAYLOADFIELD_CONTAINS,
        L"UNI");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"InstanceId",
        PAYLOADFIELD_IS,
        L" {0E95CFBC-58D4-44BA-BE40-E63A853536DF}");

    PayloadPredicateCreate(
        &Predicates[PredicateCount++],
        L"ErrorCode",
        PAYLOADFIELD_NE,
        L"0");

    Status = TdhCreatePayloadFilter(
        &EXAMPLE_PROVIDER,
        &Example_Event_2,
        FALSE,      // Match any predicates (OR)
        PredicateCount,
        Predicates,
        &EventFilters[FilterCount++]);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCreatePayloadFilter() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Combine the interim filters into a final filter descriptor.
    //
    Status = TdhAggregatePayloadFilters(
        FilterCount,
        EventFilters,
        NULL,
        &FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhAggregatePayloadFilters() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the interim filters
    //
    for (i = 0; i < FilterCount; i++) {

        Status = TdhDeletePayloadFilter(&EventFilters[i]);
        if (Status != ERROR_SUCCESS) {
            printf("TdhDeletePayloadFilter() failed with %lu\n", Status);
            goto Exit;
        }
    }

    //
    // Create a new trace session
    //
    //
    // Allocate EVENT_TRACE_PROPERTIES structure and perform some
    // basic initialization.
    //
    // N.B. LoggerName will be populated during StartTrace call.
    //
    TraceProperties = AllocateTraceProperties(NULL, L"SystemTrace.etl");
    if (TraceProperties == NULL) {
        Status = ERROR_OUTOFMEMORY;
        goto Exit;
    }

    TraceProperties->LogFileMode = EVENT_TRACE_FILE_MODE_SEQUENTIAL | EVENT_TRACE_SYSTEM_LOGGER_MODE;
    TraceProperties->MaximumFileSize = 100; // Limit file size to 100MB max
    TraceProperties->BufferSize = 512; // Use 512KB trace buffers
    TraceProperties->MinimumBuffers = 8;
    TraceProperties->MaximumBuffers = 64;

    Status = StartTraceW(&SessionHandle, LoggerName, TraceProperties);
    if (Status != ERROR_SUCCESS) {
        printf("StartTrace() failed with %lu\n", Status);
        goto Exit;
    }

    TraceStarted = TRUE;

    //
    // Enable the provider to a trace session with filtering enabled on the
    // provider
    //
    ZeroMemory(&EnableParameters, sizeof(EnableParameters));
    EnableParameters.Version = ENABLE_TRACE_PARAMETERS_VERSION_2;
    EnableParameters.EnableFilterDesc = &FilterDescriptor;
    EnableParameters.FilterDescCount = 1;

    Status = EnableTraceEx2(
        SessionHandle,
        &EXAMPLE_PROVIDER,
        EVENT_CONTROL_CODE_ENABLE_PROVIDER,
        TRACE_LEVEL_VERBOSE,
        0,
        0,
        0,
        &EnableParameters);
    if (Status != ERROR_SUCCESS) {
        printf("EnableTraceEx2() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Clean up the payload descriptor
    //
    Status = TdhCleanupPayloadEventFilterDescriptor(&FilterDescriptor);
    if (Status != ERROR_SUCCESS) {
        printf("TdhCleanupPayloadEventFilterDescriptor() failed with %lu\n", Status);
        goto Exit;
    }

    //
    // Collect trace for 30 seconds
    //
    Sleep(30 * 1000);

Exit:

    //
    // Stop tracing.
    //
    if (TraceStarted != FALSE) {
        Status = ControlTraceW(SessionHandle, NULL, TraceProperties, EVENT_TRACE_CONTROL_STOP);
        if (Status != ERROR_SUCCESS) {
            printf("StopTrace() failed with %lu\n", Status);
        }
    }

    if (TraceProperties != NULL) {
        FreeTraceProperties(TraceProperties);
    }

    TdhUnloadManifest((PWSTR)PATH_TO_MANIFEST_FILE);

    return Status;
}

Requisitos

Consulte também

StartTrace

ControlTrace

EnableCallback

ENABLE_TRACE_PARAMETERS

EVENT_FILTER_DESCRIPTOR