커널 모드 드라이버 및 구성 요소에 대한 TraceLogging

아티클
02/07/2024

이 항목에서는 커널 모드 드라이버 및 구성 요소 내에서 TraceLogging API를 사용하는 방법을 설명합니다.

필수 조건:

Windows 10
Visual Studio 2013 이상
Windows 10 SDK
Windows 10용 WDK(Windows 드라이버 키트)

TraceLogging 헤더 파일 포함

TraceLogging API를 사용하려면 TraceLogging 헤더 파일 TraceLoggingProvider.h를 포함합니다. 다른 TraceLogging API 헤더 파일인 TraceLoggingActivity.h는 C++로 작성된 사용자 모드 드라이버에서만 사용할 수 있습니다.

#include <wdm.h>
#include <TraceLoggingProvider.h>

참고

커널 모드 드라이버를 개발할 때 TraceLoggingProvider.h에는 wdm.h 파일이 필요합니다.

드라이버를 TraceLogging 공급자로 선언

TRACELOGGING_DECLARE_PROVIDER 매크로를 추가하여 공급자 핸들 변수를 선언합니다. 매크로에는 다음 구문이 있습니다.
```
TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
```
다음 예제 TraceLogging 문은 g_hProvider 변수를 선언합니다.
```
TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
```
TRACELOGGING_DECLARE_PROVIDER 사용하여 선언하는 변수는 코드의 뒷부분에서 TRACELOGGING_DEFINE_PROVIDER 매크로를 호출할 때 공급자에 대한 핸들이 됩니다.

참고

추적 로깅 공급자에 대한 핸들을 전역적으로 사용할 수 있도록 헤더 파일에 이 매크로를 배치할 수 있습니다.
TRACELOGGING_DEFINE_PROVIDER 매크로를 추가하고 추적 공급자 및 추적 공급자 핸들의 이름을 지정합니다. 핸들은 1단계에서 선언한 변수입니다. 매크로의 구문은 다음과 같습니다.
```
TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])
```
예를 들어 다음 문은 MyTraceLoggingProviderKM이라는 공급자를 정의하고 핸들 g_hProvider 할당합니다. providerId 매개 변수는 ETW 공급자 GUID입니다.
```
TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
    (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));
```
TRACELOGGING_DEFINE_PROVIDER 매크로는 공급자에 대한 스토리지를 할당하고 공급자에 대한 전역 핸들인 해당 변수를 정의합니다. 공급자 이름은 문자열 리터럴(변수 아님)이어야 하며 '\0' 문자를 포함하지 않아야 합니다. 핸들의 핸들과 복사본은 원래 핸들이 scope 있는 한 유효합니다.

TRACELOGGING_DEFINE_PROVIDER 매크로를 사용하여 핸들을 처음 만들면 공급자가 등록되지 않은 상태입니다. 이 상태에서 공급자는 등록될 때까지 추적 쓰기 호출을 무시합니다.

참고

커널 모드의 경우 공급자 메타데이터가 명시적으로 TLG_METADATA_SEGMENT(.rdata)에 저장되지만 핸들(예: g_hProvider) 및 공급자 이름(예: "MyTraceLoggingProviderKM")에 대해 만든 변수는 세그먼트에 명시적으로 할당되지 않으며 현재 암시적 세그먼트를 사용합니다.

TRACELOGGING_DEFINE_PROVIDER 매크로는 전달된 변수가 페이지가 없는 풀에 있을 것으로 예상합니다. 아직 그렇지 않은 경우 호출자는 TRACELOGGING_DEFINE_PROVIDER 매크로를 호출하기 전에 #pragma data_seg(uniqueVarName의 경우) 또는 #pragma const_seg 통해 const 세그먼트(g_hMyProvider)를 통해 데이터 세그먼트를 설정해야 합니다.

TraceLogging을 사용하여 드라이버 등록

DriverEntry 함수에서 TraceLogging 공급자를 등록해야 합니다. TraceLogging을 사용하여 공급자를 등록하려면 DriverEntry에 TraceLoggingRegister 매크로를 추가합니다.

// Register the TraceLogging provider in the DriverEntry method.
TraceLoggingRegister(g_hProvider);

드라이버 언로드 또는 정리 루틴에서 공급자 등록 취소

DriverUnload 또는 cleanup 함수에서 TraceLogging 공급자의 등록을 취소합니다.

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hProvider);

코드에서 이벤트 기록

TraceLogging은 이벤트 로깅을 위한 매크로를 제공합니다.

기본 매크로는 TraceLoggingWrite입니다. 이 매크로에는 다음 구문이 있습니다.

TraceLoggingWrite(g_hProvider, "EventName", args...)

여기서 g_hProvider 정의한 공급자에 대한 핸들이고 "EventName"은 특정 이벤트를 식별하는 데 사용하는 문자열 리터럴(변수 아님)입니다. printf 또는 DbgPrint와 마찬가지로 TraceLoggingWrite 매크로는 가변적인 수의 추가 매개 변수(최대 99개)를 지원합니다. 매개 변수(인수)는 TraceLoggingLevel, TraceLoggingInt32 또는 TraceLoggingString과 같은 TraceLogging 래퍼 매크로여야 합니다. TraceLogging 래퍼 매크로는 TraceLoggingProvider.h에 정의되어 있습니다.

참고

C++를 사용하는 경우 TraceLoggingValue 래퍼 매크로를 사용하여 형식에 맞게 자동으로 조정할 수 있습니다. C에서 드라이버를 작성하는 경우 형식별 필드 매크로(예: TraceLoggingInt32 또는 TraceLoggingUnicodeString)를 사용해야 합니다.

다음 예제에서는 g_hProvider 공급자에 대한 이벤트를 기록합니다. 이벤트를 "MyDriverEntryEvent"라고 합니다. 매크로는 TraceLoggingPointer 및 TraceLoggingUnicodeString 래퍼를 사용하여 드라이버 개체에 대한 포인터와 추적 로그에 대한 레지스트리 경로를 작성합니다. TraceLoggingUnicodeString 래퍼는 선택적 이름을 사용합니다. 이 예제에서 "RegPath"는 RegistryPath 값의 이름입니다. 이름을 지정하지 않으면 값이 이름으로 사용됩니다.

TraceLoggingWrite(
        g_hProvider,
        "MyDriverEntryEvent",
        TraceLoggingPointer(DriverObject),
        TraceLoggingUnicodeString(RegistryPath, "RegPath")); 
);

커널 모드 드라이버(C)를 계측하는 경우 TraceLoggingProvider.h에 연결하고 TraceLoggingWrite, TraceLoggingWriteActivity 또는 TraceLoggingActivityMarker 매크로를 사용할 수 있습니다. 추적 로깅의 예는 추적 로깅 예제를 참조하세요.

C++로 작성된 드라이버 또는 구성 요소를 계측하는 경우 TraceLoggingProvider.h 및 TraceLoggingActivity.h에 연결합니다. C++ 헤더에 연결할 때 TraceLoggingWriteStart, TraceLoggingWriteStop 및 TraceLoggingWriteTagged 매크로를 사용하여 이벤트를 기록할 수 있습니다.

TraceLogging 데이터를 캡처하고 보는 방법의 예는 추적 로깅 데이터 캡처 및 보기를 참조하세요.

다음을 통해 공유