EVENT_FILTER_DESCRIPTOR 구조체(evntprov.h)

아티클
08/23/2023

EVENT_FILTER_DESCRIPTOR 구조는 세션이 공급자의 콜백 사용 함수에 전달하는 필터 데이터를 정의합니다.

구문

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

멤버

Ptr

Type 멤버에 지정된 필터 형식의 필터 데이터에 대한 포인터입니다.

Type 멤버가 EVENT_FILTER_TYPE_PID 설정된 경우 Ptr 멤버는 PID(프로세스 ID) 배열을 가리킵니다.

Type 멤버가 EVENT_FILTER_TYPE_EVENT_ID 설정된 경우 Ptr 멤버는 이벤트 ID 배열과 지정된 이벤트 ID에 대해 추적을 사용하도록 설정하거나 사용하지 않도록 설정할지 여부를 결정하는 부울 값이 포함된 EVENT_FILTER_EVENT_ID 구조를 가리킵니다.

Type 멤버가 EVENT_FILTER_TYPE_STACKWALK 설정된 경우 Ptr 멤버는 이벤트 ID 배열이 포함된 EVENT_FILTER_EVENT_ID 구조와 지정된 이벤트 ID에 대해 스택 추적을 사용하도록 설정하거나 사용하지 않도록 설정할지 여부를 결정하는 부울 값을 가리킵니다.

Type 멤버가 EVENT_FILTER_TYPE_SCHEMATIZED 설정된 경우 필터 생성에 대한 자세한 내용은 EVENT_FILTER_HEADER 구조를 참조하세요.

Size

데이터의 크기(바이트)입니다.

최대 데이터 크기 제한은 지정된 Type 멤버(필터의 형식)에 따라 달라집니다. 많은 필터 형식의 최대 데이터 크기(바이트)는 evntprov.h 헤더 파일에 1024로 정의된 MAX_EVENT_FILTER_DATA_SIZE 제한됩니다.

Type

필터를 식별하는 공급자 정의 값입니다. 계측 매니페스트에 정의된 필터의 경우 이 멤버를 EVENT_FILTER_TYPE_SCHEMATIZED 설정합니다.

이 멤버에 대한 가능한 값은 evntprov.h 헤더 파일에 정의되어 있습니다.

EVENT_FILTER_TYPE_NONE (0x00000000)

필터가 없습니다.
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

스키마화된 필터입니다.

공급자 쪽 필터링이라고도 하는 기존의 필터링 설정입니다. 컨트롤러는 사용자 지정 필터 집합을 EnableTrace, EnableTraceEx 또는 EnableTraceEx2 호출에서 공급자에게 전달되는 이진 개체로 정의합니다. 이러한 필터를 정의하고 해석하는 것은 컨트롤러 및 공급자의 역할이며 컨트롤러는 해당 이벤트만 기록해야 합니다. 필터링할 수 있는 이진 개체의 형식과 형식이 정의되지 않았으므로 컨트롤러와 공급자를 긴밀하게 결합해야 합니다. TdhEnumerateProviderFilters 함수를 사용하여 매니페스트에 정의된 필터를 검색할 수 있습니다.

스키마화된 필터에 대한 자세한 내용은 필터 정의를 참조하세요.
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

내부용으로 예약된 속성입니다.
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

특정 추적 세션의 런다운을 캡처하는 데 사용됩니다. EnableTraceEx 함수에 전달된 ControlCode 매개 변수는 EVENT_CONTROL_CODE_CAPTURE_STATE 설정해야 하며 ProviderId 매개 변수는 SystemTraceControlGuid여야 합니다. EVENT_FILTER_DESCRIPTOR 구조는 현재 ETW 세션을 나타내는 단일 TRACEHANDLE을 가리킵니다. 해당 특정 세션에 대한 런다운이 수행됩니다.
EVENT_FILTER_TYPE_PID (0x80000004)

프로세스 ID입니다. 이 필터는 scope 필터 중 하나입니다.

프로세스 ID를 기반으로 ETW 이벤트를 필터링하면 지정된 프로세스에 있는 공급자의 이벤트만 포함하는 이벤트 스트림(파일 또는 실시간)이 생성됩니다. PID가 제공되는 프로세스에서만 공급자를 사용하도록 설정합니다. PID 목록은 EnableTraceEx2 가 호출될 때 실행되는 프로세스의 PID이며 특정 시간에 모든 프로세스(PID가 제공됨)에서 공급자를 사용하도록 설정합니다. PID 목록은 세션에 저장되지 않습니다. 따라서 프로세스가 종료된 후 다시 나타나면 프로세스의 공급자가 추적 세션에 자동으로 사용하도록 설정되지 않습니다. 프라이빗 로거 세션이 사용자 모드 프로세스 내에서 실행되기 때문에 PID 기반 filter-blob은 커널 모드 로거 세션에만 유효합니다.

필터링할 수 있는 최대 프로세스 ID 수는 evntprov.h 헤더 파일에 정의된 MAX_EVENT_FILTER_PID_COUNT 의해 8로 제한됩니다.

프로세스 ID 필터가 제공되는 경우 공급자는 사용자 모드 프로세스에서만 사용하도록 설정됩니다. 동일한 공급자가 커널 모드 드라이버에 의해 등록된 경우 사용하도록 설정되지 않습니다.

이는 시스템 전체 프라이빗 로거에 대한 EVENT_TRACE_PROPERTIES_V2 함께 사용됩니다.
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

실행 파일 이름입니다. 이 필터는 scope 필터 중 하나입니다.

이는 시스템 전체 프라이빗 로거에 대한 EVENT_TRACE_PROPERTIES_V2 함께 사용됩니다.
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

패키지 ID scope 필터 중 하나입니다.

공급자를 특정 Windows 스토어 앱 패키지에서 내보낸 이벤트로 필터링하는 데 사용할 수 있습니다.
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

PRAID(패키지 상대 앱 ID)입니다. scope 필터 중 하나입니다.

공급자를 특정 Windows 스토어 앱 패키지에서 내보낸 이벤트로 필터링하는 데 사용할 수 있습니다.
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

이벤트 페이로드(이벤트의 콘텐츠)입니다.

이벤트 페이로드 필터의 최대 데이터 크기(바이트)는 evntprov.h 헤더 파일에 정의된 MAX_EVENT_FILTER_PAYLOAD_SIZE 4096으로 제한됩니다.
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

이벤트 ID입니다.

이 기능을 사용하면 이벤트 목록에 대한 필터링을 사용하거나 사용하지 않도록 설정할 수 있습니다. 제공된 필터에는 이벤트 ID 배열을 포함하는 EVENT_FILTER_EVENT_ID 구조와 지정된 이벤트에 대한 필터링을 사용하거나 사용하지 않도록 설정할지 여부를 나타내는 부울 값이 포함됩니다. 각 이벤트 쓰기 호출은 이 배열을 빠르게 통과하여 이벤트 로깅을 사용하거나 사용하지 않도록 설정할지 여부를 확인합니다.

TraceLogging 공급자에 적용하면 TraceLogging 이벤트에 정적 이벤트 ID가 없으므로 이 필터는 무시됩니다.

EVENT_FILTER_EVENT_ID 구조에 허용되는 최대 이벤트 ID 수는 evntprov.h 헤더 파일에 정의된 MAX_EVENT_FILTER_EVENT_ID_COUNT 64로 제한됩니다.
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

TraceLogging 이벤트 이름입니다.

이 기능을 사용하면 이름에 따라 TraceLogging 이벤트를 사용하거나 사용하지 않도록 설정할 수 있습니다. 제공된 필터에는 이벤트 이름, 키워드(keyword) 비트 마스크 및 필터링할 수준 배열이 포함된 EVENT_FILTER_EVENT_NAME 구조와 설명된 이벤트를 사용하거나 사용하지 않도록 설정할지 여부를 나타내는 부울 값이 포함됩니다. 비 TraceLogging 공급자에 적용하면 해당 이벤트에 페이로드에 지정된 이름이 없으므로 이 필터는 무시됩니다.

참고: Windows 10 버전 1709 이상에서 사용할 수 있습니다.
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

스택 워크.

공급자에 대해 스택 워크를 사용하도록 설정하면 공급자가 생성한 모든 이벤트에 대해 스택이 캡처됩니다. 대부분의 경우 사용자는 특정 수의 이벤트에서만 스택에 관심이 있습니다.

이 기능을 사용하면 이벤트 목록에서 스택을 사용하거나 사용하지 않도록 설정할 수 있습니다. 제공된 필터에는 이벤트 ID 배열을 포함하는 EVENT_FILTER_EVENT_ID 구조와 지정된 이벤트에 대해 스택 캡처를 사용하거나 사용하지 않도록 설정할지 여부를 나타내는 부울 값이 포함됩니다. 각 이벤트 쓰기 호출은 이 배열을 빠르게 통과하여 스택을 캡처해야 하는지 여부를 확인합니다.

TraceLogging 공급자에 적용하면 TraceLogging 이벤트에 정적 이벤트 ID가 없으므로 이 필터는 무시됩니다.

이 필터를 사용하도록 선택하는 경우 공급자가 공급자로부터 모든 스택을 수집할 수 있도록 설정할 때 ENABLE_TRACE_PARAMETERS 구조에서 EVENT_ENABLE_PROPERTY_STACK_TRACE 지정해야 합니다.

EVENT_FILTER_EVENT_ID 구조에 허용되는 최대 이벤트 ID 수는 evntprov.h 헤더 파일에 정의된 MAX_EVENT_FILTER_EVENT_ID_COUNT 64로 제한됩니다.

참고: Windows 10 버전 1709 이상에서 사용할 수 있습니다.
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

TraceLogging 이벤트 이름입니다.

이 기능을 사용하면 이벤트 이름을 기반으로 TraceLogging 이벤트에 대한 스택 컬렉션을 필터링할 수 있습니다. 제공된 필터에는 이벤트 이름 배열, 키워드(keyword) 비트 마스크 및 필터링할 수준이 포함된 EVENT_FILTER_EVENT_NAME 구조와 설명된 이벤트에 대한 스택 수집 여부를 나타내는 부울 값이 포함됩니다.

비 TraceLogging 공급자에 적용하면 해당 이벤트에 페이로드에 지정된 이름이 없으므로 이 필터는 무시됩니다.

이 필터를 사용하도록 선택하는 경우 공급자가 공급자로부터 모든 스택을 수집할 수 있도록 설정할 때 ENABLE_TRACE_PARAMETERS 구조에 EVENT_ENABLE_PROPERTY_STACK_TRACE 지정해야 합니다.

참고: Windows 10 버전 1709 이상에서 사용할 수 있습니다.
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

이벤트 수준 및 키워드(keyword).

이 기능을 사용하면 해당 수준 및 키워드(keyword) 따라 이벤트에 대한 스택 컬렉션을 필터링할 수 있습니다. 제공된 필터에는 필터링할 키워드(keyword) 비트 마스크 및 수준이 포함된 EVENT_FILTER_LEVEL_KW 구조와 설명된 이벤트에 대한 스택 수집 여부를 나타내는 부울 값이 포함됩니다.

이 필터를 사용하도록 선택하는 경우 공급자가 공급자로부터 모든 스택을 수집할 수 있도록 설정할 때 ENABLE_TRACE_PARAMETERS 구조에 EVENT_ENABLE_PROPERTY_STACK_TRACE 지정해야 합니다.

참고: Windows 10 버전 1709 이상에서 사용할 수 있습니다.

설명

공급자는 데이터의 레이아웃과 용도를 결정합니다.

Windows 8.1, Windows Server 2012 R2 이상에서는 EnableTraceEx2 함수와 ENABLE_TRACE_PARAMETERS 및 EVENT_FILTER_DESCRIPTOR 구조에서 이벤트 페이로드, scope 및 스택 워크 필터를 사용하여 로거 세션의 특정 조건을 필터링할 수 있습니다. 이벤트 페이로드 필터에 대한 자세한 내용은 EnableTraceEx2, TdhCreatePayloadFilter 및 TdhAggregatePayloadFilters 함수 및 ENABLE_TRACE_PARAMETERS 및 PAYLOAD_FILTER_PREDICATE 구조를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
머리글	evntprov.h