EventWrite 함수(evntprov.h)
현재 스레드의 작업 ID를 사용하는 ETW 이벤트를 씁니다.
구문
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[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] 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 이벤트를 작성할 수 없더라도 계속 실행되고 이벤트를 계속 보고해야 하므로 릴리스 빌드는 일반적으로 오류 코드를 무시해야 합니다.
설명
대부분의 이벤트 공급자는 EventWrite를 직접 호출하지 않습니다. 대신 대부분의 이벤트 공급자는 EventRegister, EventWrite 및 EventUnregister에 대한 호출을 래핑하는 ETW 프레임워크를 사용하여 구현됩니다. 예를 들어 이벤트 매니페스트를 작성한 다음 메시지 컴파일러 를 사용하여 이벤트에 대한 C/C++ 코드를 생성하거나 TraceLogging 을 사용하여 매니페스트가 필요하지 않을 수 있습니다.
EventWrite 는 ProviderId( RegHandle에서 결정됨), 수준, 키워드 및 기타 이벤트 특성에 따라 이벤트를 적절한 추적 세션으로 라우팅합니다. 이 이벤트를 기록하는 추적 세션이 없으면 이 함수는 아무 작업도 수행하지 않고 ERROR_SUCCESS 반환합니다.
추적 세션에서 기록되지 않는 이벤트의 성능 영향을 줄이기 위해 EventEnabled 를 호출하여 데이터를 준비하고 EventWrite를 호출하기 전에 추적 세션이 이벤트를 기록하고 있는지 여부를 확인할 수 있습니다.
EventWrite 는 이벤트의 활동 ID를 현재 스레드의 활동 ID로 설정합니다. EventWrite 는 이벤트에 관련 활동 ID를 포함하지 않습니다. 다른 활동 ID를 지정하거나 관련 활동 ID를 추가하려면 EventWriteTransfer를 사용합니다.
EventWrite는 Filter의 경우 0, 플래그의 경우 0, ActivityId의 경우 NULL, RelatedActivityId의 경우 NULL이 있는 EventWriteEx와 동일합니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntprov.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |