TraceEvent 함수(evntrace.h)
RegisterTraceGuids 기반("클래식") 이벤트 공급자는 TraceEvent 함수를 사용하여 구조적 이벤트를 이벤트 추적 세션으로 보냅니다.
구문
ULONG WMIAPI TraceEvent(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_TRACE_HEADER EventTrace
);
매개 변수
[in] TraceHandle
이벤트를 기록하는 이벤트 추적 세션에 대한 핸들입니다. 공급자는 ControlCallback 구현에서 GetTraceLoggerHandle 함수를 호출할 때 핸들을 가져옵니다.
[in] EventTrace
EVENT_TRACE_HEADER 구조체에 대한 포인터입니다. 이벤트별 데이터는 필요에 따라 구조체에 추가됩니다. 기록할 수 있는 가장 큰 이벤트는 64K보다 약간 작습니다. EVENT_TRACE_HEADER 구조체의 다음 멤버에 대한 값을 지정해야 합니다.
- 크기
- Guid 또는 GuidPtr
- 플래그
공급자가 제공하는 정보의 복잡성에 따라 다음 멤버에 대한 값을 지정하는 것도 고려해야 합니다.
- Class.Type
- Class.Level
반환 값
함수가 성공하면 반환 값이 ERROR_SUCCESS.
함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.
ERROR_INVALID_FLAG_NUMBER
EVENT_TRACE_HEADER 구조체의 Flags 멤버가 잘못되었습니다.
ERROR_INVALID_HANDLE
TraceHandle 이 잘못되거나 NT 커널 로거 세션 핸들을 지정합니다.
ERROR_NOT_ENOUGH_MEMORY
세션에 기록할 여유 버퍼가 없습니다. 많은 이벤트가 발생할 때 디스크 하위 시스템에 과부하가 걸리거나 버퍼 수가 너무 적은 경우 이러한 현상이 발생할 수 있습니다. 더 많은 버퍼를 사용할 수 있게 될 때까지 차단하는 대신 TraceEvent 는 이벤트를 삭제합니다.
세션의 버퍼 수 및 크기를 늘리거나 기록되는 이벤트 수 또는 이벤트 크기를 줄이는 것이 좋습니다.
Windows 2000: 지원되지 않습니다.
ERROR_OUTOFMEMORY
버퍼 풀이 최대 크기에 도달하지는 않았지만 추가 버퍼를 할당할 수 있는 메모리가 부족하고 이벤트를 받을 수 있는 버퍼가 없으므로 이벤트가 삭제됩니다.
ERROR_INVALID_PARAMETER
다음 중 하나에 해당합니다.
- TraceHandle 은 NULL입니다.
- EventTrace 는 NULL입니다.
- EVENT_TRACE_HEADER 구조체의 Size 멤버가 잘못되었습니다.
ERROR_MORE_DATA
단일 이벤트의 데이터는 여러 버퍼에 걸쳐 있습니다. 추적 이벤트는 이벤트 추적 세션 버퍼의 크기에서 EVENT_TRACE_HEADER 구조체의 크기를 뺀 값으로 제한됩니다.
설명
MOF 기반 ETW 공급자는 이 함수를 호출합니다.
참고
대부분의 개발자는 이 함수를 호출하지 않습니다. 이 API는 MOF 기반 ETW를 지원하지만 MOF 기반 ETW는 매니페스트 기반 ETW를 위해 더 이상 사용되지 않습니다. 또한 대부분의 MOF 기반 공급자는 ETW API를 직접 호출하는 대신 MC.exe 생성된 래퍼 함수를 사용합니다.
공급자가 이 함수를 호출하기 전에 공급자
- RegisterTraceGuids 함수를 호출하여 자체 및 이벤트 추적 클래스를 등록해야 합니다.
- 사용하도록 설정해야 합니다. 컨트롤러는 EnableTrace 함수를 호출하여 공급자를 사용하도록 설정합니다.
이벤트는 로그 파일에 기록되거나, 이벤트 추적 소비자에게 실시간으로 전송되거나, 둘 다에 기록됩니다. StartTrace에 전달된 EVENT_TRACE_PROPERTIES 구조체의 LogFileMode 멤버는 이벤트가 전송되는 위치를 정의합니다.
추적 이벤트는 발생하는 순서대로 작성됩니다.
관련 이벤트 집합을 추적하려면 TraceEventInstance 함수를 사용합니다.
Windows Vista에서는 EventWrite 함수를 사용하여 이벤트를 기록해야 합니다.
예제
TraceEvent를 사용하는 예제는 추적 이벤트를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | evntrace.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |