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