PEVENT_RECORD_CALLBACK 콜백 함수(evntrace.h)

아티클
08/23/2023

소비자는 추적 처리 세션에서 이벤트를 수신하기 위해 이 콜백을 구현합니다.

PEVENT_RECORD_CALLBACK 형식은 이 콜백 함수에 대한 포인터를 정의합니다. EventRecordCallback 은 애플리케이션 정의 함수 이름의 자리 표시자입니다.

구문

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

매개 변수

[in] EventRecord

이벤트 정보를 포함하는 EVENT_RECORD 구조체에 대한 포인터입니다.

반환 값

없음

설명

ETW가 이벤트를 전달하기 위해 호출하는 함수를 지정하려면 OpenTrace 함수에 전달하는 EVENT_TRACE_LOGFILE 구조체의 EventRecordCallback, Context 및 ProcessTraceMode 멤버를 설정합니다.

EventRecordCallback을 콜백 함수의 주소로 설정합니다.
컨텍스트를 콜백에 제공된 각 EVENT_RECORDUserContext 필드에 포함해야 하는 값으로 설정합니다.
추적을 처리할 때 사용할 플래그로 ProcessTraceMode 를 설정합니다. EventRecordCallback을 사용하려면 ProcessTraceMode 값에 PROCESS_TRACE_MODE_EVENT_RECORD 포함해야 합니다.

참고

EventRecordCallback 함수가 ProcessTrace에서 잘못된 데이터를 수신하는 경우 OpenTrace에 ProcessTraceMode 제공된 구조의 EVENT_TRACE_LOGFILE 필드에 지정된 플래그를 두 번 검사. EVENT_TRACE_LOGFILE의 EventCallback 및 EventRecordCallback 필드는 공용 구조체의 겹치는 멤버입니다. ProcessTraceMode 필드에 플래그가 PROCESS_TRACE_MODE_EVENT_RECORD 포함된 경우 ProcessTrace는 EventRecordCallback 함수 서명을 사용하여 콜백을 호출합니다. 그렇지 않으면 ProcessTrace 는 EventCallback 함수 서명을 사용하여 콜백을 호출합니다.

OpenTrace를 사용하여 추적 처리 세션을 만든 후 ProcessTrace 함수를 호출하여 이벤트 수신을 시작합니다.

ProcessTrace가 추적에서 이벤트 처리를 시작하면 기록된 이벤트의 데이터가 아닌 추적(메타데이터)에 대한 데이터가 포함된 하나 이상의 가상 이벤트로 콜백을 호출할 수 있습니다. 이러한 가상 이벤트에는 EventHeader.ProviderId 가 로 설정 EventTraceGuid 되고 가상 이벤트의 내용에 따라 EventHeader.EventDescriptor.Opcode 가 설정됩니다. 예를 들어 각 추적 파일의 첫 번째 이벤트는 TRACE_LOGFILE_HEADER 정보를 포함하는 Opcode 0이 있는 가상 이벤트입니다.

받는 다른 모든 이벤트에는 공급자별 이벤트 데이터가 포함됩니다. EVENT_RECORD EventHeader.ProviderId 및 EventHeader.EventDescriptor 멤버를 사용하여 받은 이벤트의 유형을 확인합니다.

이벤트가 잘 알려진 공급자에서 제공되고 데이터의 레이아웃을 알고 있는 경우 사용자 고유의 시스템을 사용하여 이벤트를 디코딩할 수 있습니다.
EventHeader.Flags 필드에 플래그가 EVENT_HEADER_FLAG_TRACE_MESSAGE 포함된 경우 이벤트는 WPP 메시지입니다. 적절한 디코딩 정보(TMF 또는 PDB 파일)를 사용할 수 있는 경우 TdhGetProperty 또는 TdhGetWppProperty를 사용하여 이벤트를 디코딩할 수 있습니다.
그렇지 않으면 이벤트가 MOF 기반, 매니페스트 기반 또는 TraceLogging 이벤트일 수 있습니다. 적절한 디코딩 정보를 사용할 수 있는 경우 TdhGetEventInformation을 사용하여 이벤트를 디코딩할 수 있습니다.
- 이벤트가 MOF 기반 디코딩을 사용하는 경우 TdhGetEventInformation 은 시스템의 WMI 데이터 저장소에서 이벤트 디코딩 정보를 찾습니다.
- 이벤트에서 매니페스트 기반 디코딩을 사용하는 경우 TdhGetEventInformation 은 시스템의 등록된 매니페스트 또는 TdhLoadManifest 또는 TdhLoadManifestFromBinary를 통해 프로세스별 디코딩 컨텍스트에 로드된 매니페스트 또는 이진 파일에서 이벤트 디코딩 정보를 찾습니다.
- 이벤트가 TraceLogging 기반 디코딩을 사용하는 경우 TdhGetEventInformation 은 이벤트 내에서 디코딩 정보를 사용합니다.

대부분의 경우 이벤트가 발생한 순서(타임스탬프 순서)로 콜백에 전달됩니다. 그러나 특정 상황에서는 이벤트가 원래 순서대로 전달되지 않을 수 있습니다.

추적이 세션 타임스탬프에 시스템 시간을 사용하는 경우(즉, 추적 세션이 2로 properties.Wnode.ClientContext 설정됨) 세션이 이벤트를 수집하는 동안 시스템 클록이 뒤로 조정되면 일부 이벤트가 순서대로 전달될 수 있습니다. 이를 방지하려면 ClientContext를 0으로 설정하여 기본 타임스탬프(QPC 시간)를 가져옵니다.
부정확한 클록의 타임스탬프를 사용하여 추적을 수집하는 경우 다른 CPU의 타임스탬프가 동일한 이벤트가 순서대로 전달될 수 있습니다. 이는 시스템 시간이 틱하기 때문에 추적이 세션 타임스탬프에 시스템 시간을 사용할 때 가장 자주 발생합니다. 이 문제는 LogFileMode 플래그에서 로 세션을 EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING 시작하여 방지할 수 있지만 추적 성능에 상당한 부정적인 영향을 미칠 수 있습니다. Windows 10 시작: 시스템 시간 클록 유형은 GetSystemTimePreciseAsFileTime을 사용하여 이 문제의 가능성을 줄입니다.
추적이 손상되었거나 파일 내에서 예상 타임스탬프 규칙을 유지하지 않는 하위 수준 API를 사용하여 생성되었거나 이벤트를 작성할 때 타임스탬프 재정의 옵션을 사용하는 경우 일부 이벤트가 순서대로 전달될 수 있습니다.

기술 세부 정보: 이벤트는 버퍼에 저장됩니다. 각 버퍼는 일반적으로 각 CPU에 대해 하나의 스트림인 버퍼 스트림에 할당됩니다. ProcessTrace 구현에서는 버퍼의 모든 이벤트가 타임스탬프별로 정렬되고 각 버퍼에 해당 버퍼의 스트림에 있는 다른 버퍼의 범위와 겹치지 않는 단일 시간 동안의 이벤트가 포함되어 있다고 가정합니다. 이러한 가정이 충족되지 않으면 ProcessTrace는 순서가 잘못된 이벤트를 제공할 수 있습니다.

실시간 추적 컬렉션 세션에 연결된 추적 처리 세션이 없으면 버퍼가 가득 찼을 때까지 수집된 이벤트는 시스템에서 버퍼링됩니다. 추적 처리 세션이 실시간 추적 컬렉션 세션에 연결되면 추적 처리 세션은 세션에 대한 가상 이벤트, 버퍼링된 이벤트를 수신한 다음 새로 생성된 실시간 이벤트 수신을 시작합니다. 두 번째 실시간 처리 세션이 동일한 추적 컬렉션 세션에 연결하는 경우 가상 이벤트와 새로 생성된 실시간 이벤트를 수신합니다(두 번째 추적 처리 세션은 이전 이벤트를 수신하지 않음).

중요

실시간 세션에서 이벤트를 처리할 때 처리 콜백이 각 이벤트를 처리하는 데 너무 많은 시간이 걸리고 이벤트가 너무 빨리 도착하면 뒤처지게 됩니다. 시스템은 데이터 손실을 방지하기 위해 이벤트를 버퍼링하지만 이로 인해 시스템 리소스 사용량(예: 메모리 및 디스크 사용량)이 증가합니다. 세션 필터(예: 각 공급자에 대한 수준 및 키워드(keyword) 필터)를 사용하여 들어오는 이벤트의 속도를 줄이고, 콜백에서 초기 필터링을 수행하여 전체 처리가 필요하지 않은 이벤트를 건너뛰고, 처리 스레드를 차단하지 않도록 가능한 한 빨리 반환하도록 콜백을 최적화하여 이 문제를 방지합니다.

이벤트 데이터 해석에 대한 자세한 내용은 이벤트 사용 및 TDH를 사용하여 이벤트 데이터 검색을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	evntrace.h