EVENT_DESCRIPTOR 구조체(evntprov.h)

아티클
03/11/2023

EVENT_DESCRIPTOR 구조에는 ETW 이벤트에 대한 정보(메타데이터)가 포함됩니다.

구문

typedef struct _EVENT_DESCRIPTOR {
  USHORT    Id;
  UCHAR     Version;
  UCHAR     Channel;
  UCHAR     Level;
  UCHAR     Opcode;
  USHORT    Task;
  ULONGLONG Keyword;
} EVENT_DESCRIPTOR, *PEVENT_DESCRIPTOR;

멤버

Id

매니페스트 기반 이벤트를 식별하는 데 사용되는 16비트 숫자입니다.

매니페스트 기반 ETW의 경우 Provider.DecodeGuid + Event.Id + Event.Version 조합은 이벤트를 고유하게 식별해야 합니다. 즉, DecodeGuid, Id 및 Version이 동일한 모든 이벤트는 필드 이름, 필드 형식 또는 필드 순서를 변경하지 않고 동일한 필드 집합을 가져야 합니다.

매니페스트가 없는 ETW(예: TraceLogging)의 경우 ID 필드는 일반적으로 의미가 없으며 일반적으로 0으로 설정됩니다. TraceLogging 이벤트는 일반적으로 이벤트 ID가 아닌 이벤트 이름으로 식별됩니다.

Version

매니페스트 기반 이벤트의 버전을 지정하는 데 사용되는 8비트 숫자입니다.

버전은 특정 ID가 있는 이벤트의 정의에 대한 수정 버전을 나타냅니다. 지정된 ID를 가진 모든 이벤트에는 유사한 의미 체계가 있어야 하지만 버전 변경은 이벤트 세부 정보의 사소한 수정(예: 필드 형식 변경 또는 새 필드 추가)을 나타내는 데 사용할 수 있습니다.

Channel

특수 이벤트 처리를 사용하도록 설정하는 데 사용되는 8비트 숫자입니다.

매니페스트 기반 이벤트는 일반적으로 채널 0을 사용합니다.
TraceLogging 기반 이벤트는 일반적으로 채널 11을 사용합니다.
공급자 특성이 있는 매니페스트 기반 이벤트는 일반적으로 채널 12를 사용합니다.
이벤트 로그 이벤트와 함께 다른 채널 값을 사용할 수 있습니다.

16 미만의 채널 값은 ETW 런타임에서 특별 처리를 사용하도록 Microsoft에서 사용하도록 예약되어 있습니다. 채널 값 16 이상은 ETW 런타임(채널 0과 동일하게 처리됨)에서 무시되며 사용자 정의 의미 체계를 지정할 수 있습니다.

Level

이벤트의 심각도 또는 중요도를 설명하는 데 사용되는 8비트 숫자입니다.

중요

이벤트 수준은 이벤트를 필터링하는 기본 수단입니다. 항상 모든 이벤트에 의미 있는(0이 아닌) 수준을 할당합니다.

수준 값 0~5는 Microsoft에서 정의합니다(및 winmeta.h참조evntrace.h). 수준 값 6~15는 예약되어 있습니다. 수준 값 16~255는 이벤트 공급자가 정의할 수 있습니다.

값	의미 체계
LOG_ALWAYS (0)	이벤트는 수준 기반 이벤트 필터링을 무시합니다. 이벤트는 이 수준을 사용하면 안 됩니다.
Critical (1)	오류
오류 (2)	오류
경고 (3)	경고
정보 (4)	정보 제공
자세한 정보 표시 (5)	자세히

이벤트 컬렉션 세션은 수준 필터를 설정할 수 있습니다. 즉, 세션은 에서 eventDescriptor.Level <= session.LevelFilter만 이벤트를 허용합니다. 수준이 0인 이벤트는 수준 기반 필터링을 무시합니다.

Opcode

이벤트를 특수 의미 체계로 표시하는 데 사용되는 8비트 숫자입니다. 이 값은 추적 디코더에서 이벤트를 구성하고 상호 연결하는 데 사용할 수 있습니다. 전역적으로 인식되는 opcode 값은 winmeta.h에 정의됩니다. 대부분의 이벤트는 INFO(0)를 사용합니다. Opcode 값 10~239는 사용자 정의 의미 체계를 지정할 수 있습니다.

Opcodes START(1) 및 STOP(2)은 다음과 같이 ETW 활동의 시작과 끝을 나타내는 데 사용됩니다.

일반적으로 EventActivityIdControl을 사용하여 추적 내에서 고유한 활동 ID를 생성합니다.
opcode = START, activity ID = 생성된 활동 ID 및 관련 활동 ID = 부모 활동 ID(있는 경우)를 사용하여 시작 이벤트를 작성합니다.
opcode = INFO, 활동 ID = 생성된 활동 ID를 사용하여 여러 활동 정보 이벤트를 작성합니다.
opcode = STOP, 활동 ID = 생성된 활동 ID를 사용하여 중지 이벤트를 작성합니다.

그런 다음 추적 디코딩 도구는 해당 활동 ID에 따라 이러한 이벤트를 그룹으로 구성할 수 있습니다.

Task

이벤트 또는 관련 이벤트 그룹에 주석을 추가하는 데 사용되는 16비트 숫자입니다.

이벤트 작업 코드는 공급자가 정의한 모든 용도로 사용할 수 있습니다. 작업 코드 0은 이벤트에 특별한 작업 코드가 할당되지 않았음을 나타내는 데 사용되는 기본값입니다. ETW 매니페스트는 각 작업 코드에 지역화된 문자열 할당을 지원합니다. 작업 코드는 이벤트를 범주로 그룹화하거나 지역화된 "작업" 문자열을 각 이벤트와 연결하는 데 사용할 수 있습니다.

Keyword

이벤트 범주 집합에서 이벤트의 멤버 자격을 나타내는 데 사용되는 64비트 비트 마스크입니다.

중요

이벤트 키워드(keyword) 이벤트를 필터링하는 기본 수단입니다. 항상 모든 이벤트에 의미 있는(0이 아닌) 키워드(keyword) 할당합니다.

키워드(keyword) 상위 16비트(비트 마스크 0xFFFF000000000000)는 Microsoft에서 정의합니다. 키워드(keyword) 하위 48비트(비트 마스크 0x0000FFFFFFFFFFFF)는 이벤트 공급자에 의해 정의됩니다. 예를 들어 이벤트 공급자는 비트 0(비트 마스크 0x1)을 "I/O" 범주로 정의하고 비트 1(비트 마스크 0x2)을 "UI" 범주로 정의하고 비트 2(비트 마스크 0x4)를 "성능 측정" 범주로 정의할 수 있습니다. 이 시나리오에서 이벤트는 해당 키워드(keyword) 0x5 설정하여 이벤트가 "I/O" 및 "성능 측정" 범주 모두에 있음을 나타낼 수 있습니다.

이벤트 컬렉션 세션은 MatchAnyKeyword 및 MatchAllKeyword 필터를 설정할 수 있습니다. 즉, 세션은 다음 식이 true인 이벤트만 수락합니다.

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

키워드(keyword) 0인 이벤트는 일반적으로 키워드(keyword) 기반 필터링을 무시합니다.

팁

Windows 10 버전 1507 이상부터 이벤트 컬렉션 세션은 키워드(keyword) 0으로 설정된 이벤트를 제외할 수 있습니다. 이렇게 하려면 공급자를 EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 구성할 때 EnableTraceEx2에 EnableProperty 전달되는 ENABLE_TRACE_PARAMETERS 구조의 필드에 플래그를 포함합니다.

설명

이 구조체는 EventWrite를 호출하여 이벤트를 작성할 때 사용됩니다. EventEnabled를 호출할 때 이를 사용하여 이벤트를 생성해야 하는지 여부를 확인할 수도 있습니다(즉, 이벤트 수신기가 이벤트에 관심이 있는지 여부를 확인).

참고

대부분의 이벤트 공급자는 EVENT_DESCRIPTOR 직접 사용하지 않습니다. 대신 대부분의 이벤트 공급자는 EventRegister, EventWriteEx 및 EventUnregister에 대한 호출을 래핑하는 ETW 프레임워크를 사용하여 구현됩니다. 예를 들어 이벤트 매니페스트를 작성한 다음 메시지 컴파일러 를 사용하여 이벤트에 대한 C/C++ 코드를 생성하거나 TraceLogging 을 사용하여 매니페스트가 필요하지 않을 수 있습니다. 이 구조체의 멤버가 계측 매니페스트와 어떻게 관련되는지에 대한 자세한 내용은 EventDefinitionType 복합 형식의 특성을 참조하세요.

이 구조체는 EventRecordCallback 콜백과 함께 ProcessTrace를 사용하여 이벤트를 사용할 때 이벤트 레코드와 함께 반환되는 EVENT_HEADER 구조체에 포함됩니다.

참고

MOF 기반 이벤트를 처리할 때 이벤트 ID는 ID 필드가 아닌 Opcode 필드에 포함됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
머리글	evntprov.h(Evntprov.h 포함)