TraceEventInstance 함수(evntrace.h)

아티클
08/23/2023

RegisterTraceGuids 기반("클래식") 이벤트 공급자는 TraceEventInstance 함수를 사용하여 구조화된 이벤트를 instance 식별자가 있는 이벤트 추적 세션으로 보냅니다.

이벤트는 instance 식별자를 사용하여 이벤트를 트랜잭션과 연결합니다. 이 함수를 사용하여 관련 이벤트 간의 계층적 관계를 추적할 수도 있습니다.

구문

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

매개 변수

[in] TraceHandle

이벤트 instance 기록하는 이벤트 추적 세션에 대한 핸들입니다. 공급자는 ControlCallback 구현에서 GetTraceLoggerHandle 함수를 호출할 때 핸들을 가져옵니다.

[in] EventTrace

EVENT_INSTANCE_HEADER 구조체에 대한 포인터입니다. 이벤트별 데이터는 필요에 따라 구조체에 추가됩니다. 기록할 수 있는 가장 큰 이벤트는 64K입니다. EVENT_INSTANCE_HEADER 구조체의 다음 멤버에 대한 값을 지정해야 합니다.

크기
플래그
RegHandle

공급자가 제공하는 정보의 복잡성에 따라 다음 멤버에 대한 값을 지정하는 것도 고려해야 합니다.

Class.Type
Class.Level

관련 이벤트 간의 계층 관계를 추적하려면 ParentRegHandle 멤버도 설정합니다.

[in] InstInfo

이 이벤트 추적 클래스 및 instance 식별자에 대한 등록 핸들을 포함하는 EVENT_INSTANCE_INFO 구조체에 대한 포인터입니다. CreateTraceInstanceId 함수를 사용하여 구조를 초기화합니다.

[in] ParentInstInfo

부모 이벤트 추적 클래스 및 해당 instance 식별자에 대한 등록 핸들을 포함하는 EVENT_INSTANCE_INFO 구조체에 대한 포인터입니다. CreateTraceInstanceId 함수를 사용하여 구조를 초기화합니다. 계층 관계를 추적하지 않는 경우 NULL 로 설정합니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.

ERROR_INVALID_FLAGS

EVENT_INSTANCE_HEADERFlags 멤버는 WNODE_FLAG_TRACED_GUID 포함하지 않습니다.
ERROR_OUTOFMEMORY

함수 호출을 완료할 메모리가 부족했습니다. 이 오류 코드의 원인은 다음 설명 섹션에 설명되어 있습니다.
ERROR_INVALID_PARAMETER

다음 중 하나에 해당합니다.
- EventTrace 는 NULL입니다.
- pInstInfo 는 NULL입니다.
- pInstInfo의 멤버는 NULL입니다.
- TraceHandle 은 NULL입니다.
- EVENT_INSTANCE_HEADERSize 멤버가 잘못되었습니다.
ERROR_INVALID_HANDLE

TraceHandle 이 잘못되거나 NT 커널 로거 세션 핸들을 지정합니다.
ERROR_NOT_ENOUGH_MEMORY

세션에 기록할 여유 버퍼가 없습니다. 많은 이벤트가 발생할 때 디스크 하위 시스템에 과부하가 걸리거나 버퍼 수가 너무 적은 경우 이러한 현상이 발생할 수 있습니다. 더 많은 버퍼를 사용할 수 있게 될 때까지 차단하는 대신 TraceEvent 는 이벤트를 삭제합니다.

Windows 2000 및 Windows XP: 지원되지 않습니다.
ERROR_OUTOFMEMORY

버퍼 풀이 최대 크기에 도달하지는 않았지만 추가 버퍼를 할당할 수 있는 메모리가 부족하고 이벤트를 받을 수 있는 버퍼가 없으므로 이벤트가 삭제됩니다.
ERROR_MORE_DATA

단일 이벤트의 데이터는 여러 버퍼에 걸쳐 있습니다. 추적 이벤트는 이벤트 추적 세션의 버퍼 크기에서 EVENT_INSTANCE_HEADER 구조체의 크기를 뺀 값으로 제한됩니다.

설명

MOF 기반 ETW 공급자는 이 함수를 호출합니다.

참고

대부분의 개발자는 이 함수를 호출하지 않습니다. 이 API는 MOF 기반 ETW를 지원하지만 MOF 기반 ETW는 매니페스트 기반 ETW를 위해 더 이상 사용되지 않습니다. 또한 대부분의 MOF 기반 공급자는 ETW API를 직접 호출하는 대신 MC.exe 생성된 래퍼 함수를 사용합니다.

공급자가 이 함수를 호출하기 전에 공급자

RegisterTraceGuids 함수를 호출하여 자체 및 이벤트 추적 클래스를 등록해야 합니다.
CreateTraceInstanceId 함수를 호출하여 등록된 이벤트 추적 클래스에 대한 instance 식별자를 만들어야 합니다.
사용하도록 설정해야 합니다. 컨트롤러는 EnableTrace 함수를 호출하여 공급자를 사용하도록 설정합니다.

이벤트는 로그 파일에 기록되거나, 이벤트 추적 소비자에게 실시간으로 전송되거나, 둘 다에 기록됩니다. StartTrace에 전달된 EVENT_TRACE_PROPERTIES 구조체의 LogFileMode 멤버는 이벤트가 전송되는 위치를 정의합니다.

추적 이벤트는 발생하는 순서대로 작성됩니다.

관련 없는 이벤트를 추적하려면 TraceEvent 함수를 사용합니다.

Windows XP: 제대로 작동하지 않습니다.

예제

CreateTraceInstanceId 및 TraceEventInstance를 사용하여 관련 이벤트 집합을 생성하는 예제는 이벤트 인스턴스 추적을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	evntrace.h
라이브러리	Advapi32.lib
DLL	Advapi32.dll