다음을 통해 공유


TraceEventInstance 함수(evntrace.h)

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

    다음 중 하나에 해당합니다.

    • EventTraceNULL입니다.
    • pInstInfoNULL입니다.
    • pInstInfo의 멤버는 NULL입니다.
    • TraceHandleNULL입니다.
    • 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: 제대로 작동하지 않습니다.

예제

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

요구 사항

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

추가 정보

CreateTraceInstanceId

EVENT_INSTANCE_HEADER

EVENT_INSTANCE_INFO

RegisterTraceGuids

TraceEvent