TraceLoggingRegister 함수(traceloggingprovider.h)

아티클
03/13/2024

이벤트를 기록하는 데 사용할 수 있도록 TraceLogging 공급자를 등록합니다. 등록은 공급자가 등록 취소되거나 프로세스가 종료될 때까지 유효합니다.

구문

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

매개 변수

hProvider

등록할 TraceLogging 공급자의 핸들입니다. 핸들을 아직 등록하지 않아야 합니다.

반환 값

사용자 모드 코드에서 이 함수를 호출하면 함수는 를 반환합니다 HRESULT. 매크로를 SUCCEEDED() 사용하여 함수의 성공 여부를 확인합니다.

커널 모드 코드에서 이 함수를 호출하면 함수는 를 반환합니다 NTSTATUS. 매크로를 NT_SUCCESS() 사용하여 함수의 성공 여부를 확인합니다.

참고

TraceLoggingRegister에서 반환된 오류 코드는 주로 디버깅 및 진단 시나리오에 사용하기 위한 것입니다. ETW 공급자를 등록하지 못한 경우에도 대부분의 프로덕션 코드는 계속 실행되어야 하므로 릴리스 빌드는 일반적으로 TraceLoggingRegister에서 반환된 오류 코드를 무시해야 합니다.

설명

구성 요소가 실행되기 시작하면 구성 요소의 모든 TraceLogging 공급자 핸들이 등록되지 않은 상태가 되고 공급자의 핸들을 사용하여 이벤트를 생성하려는 시도는 자동으로 무시됩니다. 공급자가 이벤트를 작성하려면 TraceLoggingRegister를 사용하여 공급자를 등록해야 합니다. 일반적으로 구성 요소를 시작하는 동안(예: , , wmain, DllMain(DLL_PROCESS_ATTACH)WinMain또는 DriverEntry)main에서 이 작업을 수행합니다. 구성 요소 종료 시 TraceLoggingUnregister를 호출하여 공급자 등록을 취소합니다.

이미 등록된 공급자 핸들에서 TraceLoggingRegister 를 호출하지 마세요. 핸들의 등록을 취소한 다음 필요한 경우 다시 등록할 수 있지만 핸들을 반복적으로 등록 및 등록 취소하면 성능 문제가 발생할 수 있으며 피해야 합니다(예: 등록하지 않고, 몇 가지 이벤트를 작성한 다음, 등록을 취소합니다. 대신 구성 요소 시작 시 한 번 등록하고 구성 요소 종료 시 등록 취소).

TraceLoggingRegister는 동일한 핸들에서 TraceLoggingRegister 또는 TraceLoggingUnregister에 대한 다른 호출과 관련하여 스레드로부터 안전하지 않습니다. 다른 스레드가 동일한 핸들에서 TraceLoggingRegister 또는 TraceLoggingUnregister를 동시에 호출할 수 있는 경우 TraceLoggingRegister를 호출하지 마세요.

TraceLoggingRegister가 실패하면 공급자 핸들은 등록되지 않은 상태로 유지되고 공급자 핸들의 모든 사용은 안전한 no-ops가 됩니다. 특히 등록되지 않은 공급자 핸들을 사용하여 TraceLoggingWrite 또는 TraceLoggingUnregister 를 호출하는 것은 안전한 no-op입니다.

중요

DLL 또는 드라이버가 공급자 핸들에서 TraceLoggingRegister를 호출하는 경우 DLL 또는 드라이버가 언로드되기 전에 해당 공급자 핸들에서 TraceLoggingUnregister를 호출해야 합니다. TraceLoggingUnregister를 호출하지 않고 DLL이 언로드되는 경우 프로세스는 이후에 충돌할 수 있습니다. 드라이버가 TraceLoggingUnregister를 호출하지 않고 언로드하는 경우 시스템이 이후에 충돌할 수 있습니다. TraceLoggingRegister 함수는 ETW 구성 콜백을 설정하고 TraceLoggingUnregister는 콜백을 취소합니다. 콜백이 취소되지 않고 모듈이 언로드되면 다음에 ETW가 콜백을 호출하려고 할 때 충돌이 발생합니다.

경고

드라이버가 TraceLoggingRegister를 호출한 다음 DriverEntry 중에 오류가 발생하는 경우 DriverEntry에서 오류를 반환하기 전에 TraceLoggingUnregister를 호출해야 합니다. 드라이버가 DriverEntry에서 오류를 반환하고 TraceLoggingUnregister 를 호출하지 않으면 시스템이 충돌하는 경우 일반 드라이버 정리 루틴이 호출되지 않습니다.

TraceLoggingRegister 는 다음을 수행합니다.

EventRegister를 호출하여 ETW에 대한 연결을 엽니다.
EventRegister가 성공하면 InformationClassEventProviderSetTraits를 사용하여 TraceLoggingSetInformation을 호출하여 TraceLogging 지원에 대한 공급자를 구성합니다.

TraceLoggingRegister 호출은 콜백 및 컨텍스트 매개 변수에 대해 NULL을 사용하여 TraceLoggingRegisterEx를 호출하는 것과 동일합니다. 세션이 공급자를 사용하거나 사용하지 않도록 설정할 때 ETW 사용 콜백을 받아야 하는 경우 TraceLoggingRegisterEx를 사용합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
머리글	traceloggingprovider.h
라이브러리	Advapi32.lib