EtwWrite 함수(wdm.h)

아티클
03/08/2023

EtwWrite 함수는 커널 모드 드라이버 코드에서 이벤트를 게시하기 위한 추적 함수입니다.

구문

NTSTATUS EtwWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

매개 변수

[in] RegHandle

이벤트 공급자 등록에 성공하면 EtwRegister 함수에서 반환되는 이벤트 공급자 등록 핸들에 대한 포인터입니다.

[in] EventDescriptor

EVENT_DESCRIPTOR 구조체에 대한 포인터입니다.

[in, optional] ActivityId

이벤트와 연결된 활동을 나타내는 식별자입니다. ActivityID는 관련 이벤트를 그룹화할 수 있는 방법을 제공하며 엔드 투 엔드 추적에 사용됩니다.

[in] UserDataCount

UserData의 EVENT_DATA_DESCRIPTOR 구조체 수입니다.

[in, optional] UserData

EVENT_DATA_DESCRIPTOR 구조체의 배열에 대한 포인터입니다.

반환 값

이벤트가 성공적으로 게시되면 EtwWrite 는 STATUS_SUCCESS 반환합니다.

이벤트 공급자 등록 핸들에 대한 포인터가 유효하지 않으면 EtwWrite 는 STATUS_INVALID_HANDLE 반환합니다. EtwWrite가 호출되기 전에 이벤트 공급자를 등록해야 합니다. EtwWrite는 이벤트를 기록할 수 없는 경우 STATUS_INVALID_HANDLE 반환할 수도 있습니다.

UserDataCount에 지정된 EVENT_DATA_DESCRIPTOR 구조체 수가 허용되는 최대값(128)보다 크면 EtwWrite는 STATUS_INVALID_PARAMETER 반환합니다.

ActivityID가 지정되었지만 이벤트와 연결된 데이터를 기록하는 데 사용할 수 있는 메모리가 부족한 경우 EtwWrite는 STATUS_NO_MEMORY 반환합니다.

공급자가 세션에 대해 사용하도록 설정되지 않은 경우 EtwWrite 는 STATUS_SUCCESS 반환하고 이벤트는 기록되지 않습니다.

이벤트는 여러 가지 이유로 손실될 수 있습니다. 예를 들어 이벤트 속도가 너무 높거나 이벤트 크기가 버퍼 크기보다 큰 경우입니다. 이러한 경우 해당 로거에 대한 EVENT_TRACE_PROPERTIES 구조의 멤버인 EventsLost 카운터가 기록되지 않은 이벤트 수로 업데이트됩니다.

설명

EtwWrite 함수는 사용자 모드 EventWrite 함수와 동일한 커널 모드입니다. 게시하는 이벤트에 대한 소비자가 있는지 확인하려면 EtwEventEnabled 또는 EtwProviderEnabled를 호출하여 EtwWrite 호출 앞에 올 수 있습니다.

EtwWrite 함수를 호출하여 이벤트를 게시하려면 먼저 EtwRegister에 공급자를 등록해야 합니다. EtwRegister 및 EtwUnregister 함수로 바인딩된 코드를 벗어나는 추적 호출을 해서는 안 됩니다. 최상의 성능을 위해 DriverEntry 루틴에서 EtwRegister 함수를 호출하고 DriverUnload 루틴에서 EtwUnregister 함수를 호출할 수 있습니다.

EtwWrite 함수에서 선택적 UserData 매개 변수를 사용하여 추가 이벤트 데이터를 기록하는 경우 EventDataDescCreate 매크로를 사용하여 EVENT_DATA_DESCRIPTOR 구조체 만들기를 간소화할 수 있습니다. 다음 예제에서는 EventDataDescCreate 매크로를 사용하여 디바이스 이름과 해당 상태 사용하여 EVENT_DATA_DESCRIPTOR 구조를 초기화합니다. EventDataDescCreate 매크로는 데이터에 대한 포인터를 저장합니다(즉, 데이터 복사본을 저장하지 않음). EtwWrite 호출이 반환될 때까지 포인터는 유효한 상태로 유지되어야 합니다.

IRQL에서 EtwWrite 를 호출할 수 있습니다. 그러나 IRQL이 APC_LEVEL보다 크면 EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer 함수에 전달된 모든 데이터는 페이징할 수 없어야 합니다. 즉, irQL에서 실행되는 커널 모드 루틴이 APC_LEVEL 초과하면 페이지 가능한 메모리에 액세스할 수 없습니다. EtwWrite, EtwWriteEx, EtwWriteString 및 EtwWriteTransfer 함수에 전달된 데이터는 IRQL이 무엇인지에 관계없이 시스템 공간 메모리에 있어야 합니다.

예제

 
 //
 // Register the provider with ETW in DriverEntry
 // Unregister the provider in DriverUnload 
    //
 //  Build the EVENT_DATA_DESCRIPTOR structures using 
 //   the EventDataDescCreate macros 
 
 if (RegHandle != (REGHANDLE)NULL) {
 //
 // Log an Event with : DeviceNameLength
 //                      DeviceName
 //                      Status
 //
 
 EventDataDescCreate(&EventDataDescriptor[0],
                            (PVOID)&DeviceName.Length,
 sizeof(USHORT));
 

 EventDataDescCreate(&EventDataDescriptor[1],
                            (PVOID)DeviceName.Buffer,
 DeviceName.Length);
 
 EventDataDescCreate(&EventDataDescriptor[2],
                            (PVOID)&Status,
 sizeof(ULONG));
 
 EtwWrite(RegHandle,            // Handle from EtwRegister
                 &StartEvent,          // EventDescriptor
                 NULL,                 // Activity ID
                 3,                    // Number of data items
 EventDataDescriptor); // Array of data descriptors
    }              

//

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	모든 수준(설명 섹션 참조)