estrutura EVENT_FILTER_DESCRIPTOR (evntprov.h)
A estrutura EVENT_FILTER_DESCRIPTOR define os dados de filtro que uma sessão passa para a função de retorno de chamada habilitada do provedor.
Sintaxe
typedef struct _EVENT_FILTER_DESCRIPTOR {
ULONGLONG Ptr;
ULONG Size;
ULONG Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;
Membros
Ptr
Um ponteiro para os dados de filtro para o tipo de filtro especificado no membro Type .
Se o membro Type estiver definido como EVENT_FILTER_TYPE_PID, o membro Ptr apontará para uma matriz de PIDs (IDs de processo).
Se o membro Type estiver definido como EVENT_FILTER_TYPE_EVENT_ID, o membro Ptr apontará para uma estrutura EVENT_FILTER_EVENT_ID que contém uma matriz de IDs de evento e um valor booliano que determina se o rastreamento está habilitado ou desabilitado para as IDs de evento especificadas.
Se o membro Type estiver definido como EVENT_FILTER_TYPE_STACKWALK, o membro Ptr apontará para uma estrutura EVENT_FILTER_EVENT_ID que contém uma matriz de IDs de evento e um valor booliano que determina se o rastreamento de pilha está habilitado ou desabilitado para as IDs de evento especificadas.
Se o membro Type estiver definido como EVENT_FILTER_TYPE_SCHEMATIZED, consulte a estrutura EVENT_FILTER_HEADER para obter detalhes sobre como construir o filtro.
Size
O tamanho dos dados, em bytes.
O limite máximo de tamanho de dados varia de acordo com o membro Type especificado (o tipo do filtro). O tamanho máximo dos dados, em bytes, para muitos dos tipos de filtro é limitado a MAX_EVENT_FILTER_DATA_SIZE, definido no arquivo de cabeçalho evntprov.h como 1024.
Type
Um valor definido pelo provedor que identifica o filtro. Para filtros definidos em um manifesto de instrumentação, defina esse membro como EVENT_FILTER_TYPE_SCHEMATIZED.
Os valores possíveis para esse membro são definidos no arquivo de cabeçalho evntprov.h .
EVENT_FILTER_TYPE_NONE (0x00000000)
Sem filtros.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)
Um filtro esquematizado.
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 na chamada EnableTrace, EnableTraceEx ou EnableTraceEx2 . Cabe ao controlador e ao provedor definir e interpretar esses filtros e o controlador só deve registrar eventos aplicáveis. 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 são definidos. A função TdhEnumerateProviderFilters pode ser usada para recuperar os filtros definidos em um manifesto.
Para obter mais informações sobre filtros esquematizados, consulte Definindo filtros.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)
Reservado para uso interno.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)
Usado para capturar um rundown de uma sessão de rastreamento específica. O parâmetro ControlCode passado para a função EnableTraceEx deve ser definido como EVENT_CONTROL_CODE_CAPTURE_STATE e o parâmetro ProviderId deve ser SystemTraceControlGuid. A estrutura EVENT_FILTER_DESCRIPTOR deve apontar para um único TRACEHANDLE que representa uma sessão ETW atual. Um rundown será executado para essa sessão específica.
EVENT_FILTER_TYPE_PID (0x80000004)
A ID do processo. Esse é um dos filtros de escopo.
Filtrar eventos ETW com base em IDs de processo resultará em um fluxo de eventos (arquivo ou em tempo real) que contém os eventos dos provedores apenas nos processos especificados. Ele habilitará apenas o provedor nos processos cujos PIDs são fornecidos. A lista de PIDs são os PIDs dos processos em execução no momento em que EnableTraceEx2 é chamado e habilitará o provedor em todos os processos (para os quais os PIDs são fornecidos) nesse momento específico. A lista de PIDs não será armazenada na sessão. Portanto, quando um processo é encerrado e, em seguida, reaparece, o provedor nele não será habilitado automaticamente para a sessão de rastreamento. O filtro-blob baseado em PIDs só é válido para uma sessão do agente do modo kernel porque a sessão do agente privado é executada dentro de um processo de modo de usuário.
O número máximo de IDs de processo que podem ser filtradas é limitado por MAX_EVENT_FILTER_PID_COUNT definido no arquivo de cabeçalho evntprov.h como 8.
Caso um filtro de ID de processo seja fornecido, o provedor será habilitado apenas nos processos do modo de usuário. Caso o mesmo provedor seja registrado por um driver no modo kernel, ele não será habilitado.
Isso é usado com EVENT_TRACE_PROPERTIES_V2 para agentes privados de todo o sistema.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)
O nome do arquivo executável. Esse é um dos filtros de escopo.
Isso é usado com EVENT_TRACE_PROPERTIES_V2 para agentes privados de todo o sistema.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)
A ID do pacote. Esse é um dos filtros de escopo
Isso pode ser usado para filtrar provedores para eventos emitidos de um determinado pacote de aplicativos da Windows Store.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)
A PRAID (ID relativa do aplicativo) do pacote. Esse é um dos filtros de escopo
Isso pode ser usado para filtrar provedores para eventos emitidos de um determinado pacote de aplicativos da Windows Store.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)
O conteúdo do evento (o conteúdo do evento).
O tamanho máximo dos dados, em bytes, para um filtro de conteúdo de evento é limitado a MAX_EVENT_FILTER_PAYLOAD_SIZE definido no arquivo de cabeçalho evntprov.h para 4096.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)
A ID do evento.
Esse recurso permite habilitar ou desabilitar a filtragem para uma lista de eventos. O filtro fornecido inclui uma estrutura EVENT_FILTER_EVENT_ID que contém uma matriz de IDs de evento e um valor booliano que indica se deseja habilitar ou desabilitar a filtragem para os eventos especificados. Cada chamada de gravação de evento passará por essa matriz rapidamente para descobrir se habilitar ou desabilitar o registro em log do evento.
Quando aplicado a um provedor de TraceLogging, esse filtro será ignorado, pois os eventos tracelogging não têm IDs de eventos estáticos.
O número máximo de IDs de evento permitidas na estrutura EVENT_FILTER_EVENT_ID é limitado por MAX_EVENT_FILTER_EVENT_ID_COUNT definido no arquivo de cabeçalho evntprov.h para 64.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)
O nome do evento TraceLogging.
Esse recurso permite habilitar ou desabilitar eventos tracelogging com base em seus nomes. O filtro fornecido inclui uma estrutura EVENT_FILTER_EVENT_NAME que contém uma matriz de nomes de eventos, palavra-chave bitmasks e nível para filtrar e um valor booliano que indica se os eventos descritos devem ser habilitados ou desabilitados. Quando aplicado a um provedor não TraceLogging, esse filtro é ignorado, pois esses eventos não têm nomes especificados em seu conteúdo.
Nota: Disponível no Windows 10, versão 1709 e posterior.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)
Uma caminhada de pilha.
Quando o stack walking é habilitado para um provedor, a pilha é capturada para todos os eventos gerados pelo provedor. Na maioria das vezes, o usuário só está interessado em pilha de apenas determinado número de eventos.
Esse recurso permite habilitar ou desabilitar o andamento da pilha em uma lista de eventos. O filtro fornecido inclui uma estrutura EVENT_FILTER_EVENT_ID que contém uma matriz de IDs de evento e um valor booliano que indica se a captura de pilha deve ser habilitada ou desabilitada para os eventos especificados. Cada chamada de gravação de evento passará por essa matriz rapidamente para descobrir se a pilha deve ser capturada ou não.
Quando aplicado a um provedor de TraceLogging, esse filtro será ignorado, pois os eventos tracelogging não têm IDs de evento estáticas.
Se você optar por usar esse filtro, ainda deverá especificar EVENT_ENABLE_PROPERTY_STACK_TRACE na estrutura ENABLE_TRACE_PARAMETERS ao habilitar o provedor para que todas as pilhas sejam coletadas de um provedor.
O número máximo de IDs de evento permitidas na estrutura EVENT_FILTER_EVENT_ID é limitado por MAX_EVENT_FILTER_EVENT_ID_COUNT definido no arquivo de cabeçalho evntprov.h para 64.
Nota: Disponível no Windows 10, versão 1709 e posterior.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)
Um nome de evento TraceLogging.
Esse recurso permite a filtragem da coleção de pilhas para eventos traceLogging com base nos nomes dos eventos. O filtro fornecido inclui uma estrutura EVENT_FILTER_EVENT_NAME que contém uma matriz de nomes de eventos, palavra-chave bitmasks e nível para filtrar e um valor booliano que indica se as pilhas devem ser coletadas ou não para os eventos descritos.
Quando aplicado a um provedor não TraceLogging, esse filtro é ignorado, pois esses eventos não têm nomes especificados em seu conteúdo.
Se você optar por usar esse filtro, ainda deverá especificar EVENT_ENABLE_PROPERTY_STACK_TRACE na estrutura ENABLE_TRACE_PARAMETERS ao habilitar o provedor para que todas as pilhas sejam coletadas de um provedor.
Nota: Disponível no Windows 10, versão 1709 e posterior.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)
Nível de evento e palavra-chave.
Esse recurso permite a filtragem da coleção de pilhas para eventos com base em seu nível e palavra-chave. O filtro fornecido inclui uma estrutura EVENT_FILTER_LEVEL_KW que contém palavra-chave bitmasks e o nível para filtrar, bem como um valor booliano que indica se as pilhas devem ser coletadas ou não para os eventos descritos.
Se você optar por usar esse filtro, ainda deverá especificar EVENT_ENABLE_PROPERTY_STACK_TRACE na estrutura ENABLE_TRACE_PARAMETERS ao habilitar o provedor para que todas as pilhas sejam coletadas de um provedor.
Nota: Disponível no Windows 10, versão 1709 e posterior.
Comentários
O provedor determina o layout dos dados e sua finalidade.
Em Windows 8.1,Windows Server 2012 R2 e posteriores, os filtros de conteúdo de evento, escopo e caminhada de pilha podem ser usados pela função EnableTraceEx2 e as estruturas ENABLE_TRACE_PARAMETERS e EVENT_FILTER_DESCRIPTOR para filtrar condições específicas em uma sessão de agente. Para obter mais informações sobre filtros de conteúdo de eventos, consulte as funções EnableTraceEx2, TdhCreatePayloadFilter e TdhAggregatePayloadFilters e as estruturas ENABLE_TRACE_PARAMETERS e PAYLOAD_FILTER_PREDICATE .
Requisitos
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Cabeçalho | evntprov.h |
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