EventWriteEx 함수(evntprov.h)
활동 ID, 선택적 관련 활동 ID, 세션 필터 및 특수 옵션을 사용하여 ETW 이벤트를 씁니다.
구문
ULONG EVNTAPI EventWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
매개 변수
[in] RegHandle
공급자의 등록 핸들입니다. 핸들은 EventRegister에서 제공됩니다. 생성된 이벤트는 핸들과 연결된 ProviderId를 사용합니다.
[in] EventDescriptor
ID, 버전, 수준, 키워드, 채널, Opcode 및 작업을 포함한 이벤트 정보(메타데이터)를 사용하여 EVENT_DESCRIPTOR.
중요
ProviderId, Level 및 Keyword는 이벤트를 필터링하기 위한 기본 수단입니다. 다른 종류의 필터링이 가능하지만 오버헤드가 훨씬 더 높습니다. 항상 0이 아닌 수준을 할당하고 모든 이벤트에 키워드(keyword).
[in] Filter
64비트 비트 마스크 값입니다. 각 집합 비트는 이 이벤트를 특정 추적 세션에서 제외해야 했음을 나타냅니다.
Filter 매개 변수는 EnableCallback의 FilterData를 기반으로 사용자 지정 이벤트 필터링을 수행하는 이벤트 공급자와 함께 사용됩니다.
사용자 지정 이벤트 필터를 지원하지 않거나 이벤트를 모든 추적 세션에 기록해야 하는 경우 필터 를 0으로 설정합니다. 그렇지 않으면 필터 를 이벤트를 받지 않아야 하는 세션 식별자의 비트 OR로 설정합니다.
[in] Flags
일반적인 이벤트 처리의 경우 플래그 를 0으로 설정합니다.
특수 이벤트 처리를 위해 플래그를 EVENT_WRITE_FLAG 값의 조합으로 설정합니다.
EVENT_WRITE_FLAG_INPRIVATE (0x2)
이 이벤트는 EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE 옵션을 설정한 모든 로거에서 제외되어야 했음을 나타냅니다.
[in, optional] ActivityId
이 이벤트의 128비트 활동 ID에 대한 선택적 포인터입니다. NULL이 아닌 경우 EventWriteEx 는 이벤트의 활동 ID에 대해 지정된 값을 사용합니다. NULL인 경우 EventWriteEx 는 현재 스레드의 활동 ID를 사용합니다.
추적 처리 도구는 이벤트의 활동 ID를 사용하여 이벤트를 활동이라는 그룹으로 구성할 수 있습니다. 활동 ID에 대한 자세한 내용은 EventActivityIdControl을 참조하세요.
[in, optional] RelatedActivityId
이 이벤트의 활동의 부모인 128비트 활동 ID에 대한 선택적 포인터입니다. NULL이 아닌 경우 EventWriteEx 는 이벤트의 관련 활동 ID에 대해 지정된 값을 사용합니다. NULL이면 이벤트에 관련 활동 ID가 없습니다. 관련 활동 ID는 일반적으로 활동의 START 이벤트(Opcode = START로 기록된 활동의 첫 번째 이벤트)에 설정됩니다.
추적 처리 도구는 이벤트의 관련 활동 ID를 사용하여 활동 간의 관계를 확인할 수 있습니다. 예를 들어 관련 작업은 새로 시작된 활동의 부모입니다. 관련 활동 ID에 대한 자세한 내용은 EventActivityIdControl을 참조하세요.
[in] UserDataCount
UserData의 EVENT_DATA_DESCRIPTOR 구조체 수입니다. 최대 수는 128입니다.
[in, optional] UserData
이벤트에 포함할 데이터를 설명하는 UserDataCountEVENT_DATA_DESCRIPTOR 구조체의 배열입니다. UserDataCount가 0인 경우 UserData는 NULL일 수 있습니다.
각 EVENT_DATA_DESCRIPTOR 이벤트에 포함할 하나의 메모리 블록을 설명합니다. 지정된 블록은 패딩이나 맞춤 없이 이벤트 콘텐츠를 형성하기 위해 연결됩니다. 매니페스트 기반 디코딩을 사용하는 경우 이벤트 콘텐츠는 매니페스트의 이벤트와 연결된 템플릿에 지정된 레이아웃과 일치해야 합니다.
반환 값
성공하거나 오류 코드가 있는 경우 ERROR_SUCCESS 반환합니다. 가능한 오류 코드에는 다음이 포함됩니다.
- ERROR_INVALID_PARAMETER: 하나 이상의 매개 변수가 잘못되었습니다.
- ERROR_INVALID_HANDLE: 공급자의 등록 핸들이 잘못되었습니다.
- ERROR_ARITHMETIC_OVERFLOW: 이벤트 크기가 허용되는 최대값(64KB - 헤더)보다 큽니다.
- ERROR_MORE_DATA: 세션 버퍼 크기가 이벤트에 비해 너무 작습니다.
- ERROR_NOT_ENOUGH_MEMORY: 채워진 버퍼가 디스크로 플러시하려고 하지만 디스크 IO가 충분히 빠르게 발생하지 않을 때 발생합니다. 디스크가 느리고 이벤트 트래픽이 많은 경우에 발생합니다. 결국 더 이상 무료(빈) 버퍼가 없고 이벤트가 삭제됩니다.
- STATUS_LOG_FILE_FULL: 실시간 재생 파일이 가득 찼습니다. 실시간 소비자가 재생 파일의 이벤트를 사용할 때까지 이벤트는 세션에 기록되지 않습니다.
오류 코드는 주로 디버깅 및 진단 시나리오에서 사용하기 위한 것입니다. 대부분의 프로덕션 코드는 ETW 이벤트를 작성할 수 없더라도 계속 실행되고 계속해서 이벤트를 보고해야 하므로 릴리스 빌드는 일반적으로 오류 코드를 무시해야 합니다.
설명
대부분의 이벤트 공급자는 EventWriteEx를 직접 호출하지 않습니다. 대신 대부분의 이벤트 공급자는 EventRegister, EventWriteEx 및 EventUnregister에 대한 호출을 래핑하는 ETW 프레임워크를 사용하여 구현됩니다. 예를 들어 이벤트 매니페스트를 작성한 다음 메시지 컴파일러 를 사용하여 이벤트에 대한 C/C++ 코드를 생성하거나 TraceLogging 을 사용하여 매니페스트가 필요하지 않을 수 있습니다.
EventWriteEx 는 ProviderId( RegHandle에서 결정됨), 수준, 키워드 및 기타 이벤트 특성에 따라 이벤트를 적절한 추적 세션으로 라우팅합니다. 이 이벤트를 기록하는 추적 세션이 없으면 이 함수는 아무 작업도 수행하지 않고 ERROR_SUCCESS 반환합니다.
추적 세션에 의해 기록되지 않은 이벤트의 성능 영향을 줄이기 위해 EventEnabled 를 호출하여 데이터를 준비하고 EventWriteEx를 호출하기 전에 추적 세션이 이벤트를 기록하고 있는지 여부를 확인할 수 있습니다.
공급자는 세션이 이벤트 데이터를 기반으로 이벤트를 필터링하는 데 사용하는 필터를 정의할 수 있습니다. 핵심 필터는 수준 및 키워드를 기반으로 합니다. 이벤트 공급자는 더 복잡한 필터를 지원할 수 있습니다. 이벤트 공급자는 EnableCallback의 FilterData 매개 변수에서 필터 정보를 받을 수 있습니다. 공급자는 필터를 평가하고 EventWriteEx의 Filter 매개 변수를 사용하여 특정 추적 세션이 필터를 통과하지 않았으므로 이벤트를 수신하지 않아야 함을 나타낼 수 있습니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 7 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2008 R2 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntprov.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |