PENABLECALLBACK 콜백 함수(evntprov.h)

아티클
08/23/2023

ETW 이벤트 공급자는 필요에 따라 구성 변경 알림을 수신하도록 EnableCallback 함수를 정의합니다. PENABLECALLBACK 형식은 이 콜백 함수에 대한 포인터를 정의합니다. EnableCallback 은 애플리케이션 정의 함수 이름의 자리 표시자입니다.

구문

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

매개 변수

[in] SourceId

공급자를 사용하거나 사용하지 않도록 설정하는 호출자가 지정한 GUID입니다.

값은 EnableTraceEx의 SourceId 매개 변수 또는 EnableTraceEx2에 전달되는 ENABLE_TRACE_PARAMETERSSourceId 필드에서 가져옵니다.

참고

SourceId는 EnableTraceEx 또는 EnableTraceEx2 API 호출에 지정된 세션 값입니다. 세션의 GUID와 같거나 같지 않을 수 있습니다.

SourceId 는 알림에 원본 식별자가 없는 여러 시나리오에서 GUID_NULL 설정됩니다. 예를 들어 공급자를 시작하기 전에 추적 세션이 공급자를 사용하도록 설정하거나, 공급자가 중지되거나, 추적 컨트롤러가 SourceId를 지정하지 않고 EnableTrace API를 호출할 때 이 문제가 발생할 수 있습니다.

[in] IsEnabled

이 알림에 해당하는 ControlCode를 나타냅니다. 다음 값 중 하나일 수 있습니다.

값	의미
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	공급자를 사용하도록 설정한 세션이 없습니다.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	하나 이상의 세션이 공급자를 사용하도록 설정했습니다.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	세션에서 공급자가 해당 상태 정보를 기록할 것을 요청합니다. 공급자는 일반적으로 공급자 상태를 포함하는 이벤트를 작성하여 응답합니다.

참고

IsEnabled 값은 이 이벤트를 트리거한 EnableTrace API에 전달된 ControlCode와 동일하지 않을 수 있습니다. 예를 들어 두 세션에서 이 공급자를 사용하도록 설정하고 한 세션에서 를 호출 EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...)하여 이 공급자를 사용하지 않도록 설정하는 경우 공급자는 다른 세션에서 공급자를 계속 사용하도록 설정되어 있으므로 IsEnabled 가 로 EVENT_CONTROL_CODE_ENABLE_PROVIDER 설정된 알림을 받게 됩니다.

DISABLE_PROVIDER 알림을 받은 후 공급자는 모든 이벤트를 사용하지 않도록 설정하여 성능을 최적화할 수 있습니다. ENABLE_PROVIDER 알림을 받은 후 공급자는 이벤트 작성을 사용하도록 설정해야 합니다. 또한 Level, MatchAnyKeyword 및 MatchAllKeyword 필터의 값을 기록한 다음, 설명에 설명된 대로 필터를 전달하는 이벤트만 작성하여 성능을 최적화할 수 있습니다. CAPTURE_STATE 알림을 받은 후 공급자는 적절한 것으로 보이는 모든 작업을 수행할 수 있으며 일반적으로 구성 요소의 구성 또는 상태를 설명하는 이벤트를 작성합니다.

공급자는 인식하거나 지원하지 않는 IsEnabled 값으로 알림을 무시해야 합니다.

[in] Level

공급자가 작성해야 하는 이벤트의 세부 정보를 지정하는 값입니다. 컨트롤 코드 EVENT_CONTROL_CODE_ENABLE_PROVIDER 사용하여 호출되는 경우 공급자는 Level 값을 기록해야 하며, 이후에 이벤트의 세부 정보 표시 수준이 기록된 수준보다 큰 이벤트를 건너뛰어야 합니다. 즉, 이벤트가 기록되어야 하는 경우에만 기록해야 합니다.

eventDescriptor.Level <= recorded.Level

알림의 수준은 이 이벤트 공급자의 GUID를 사용하여 EnableTrace, EnableTraceEx 또는EnableTraceEx2 호출에서 추적 컨트롤러가 지정 한 최대 수준입니다. 즉, 여러 세션이 서로 다른 세부 정보 표시 수준에서 이 이벤트 공급자의 이벤트를 기록하는 경우 EnableCallback 알림에 대한 Level 매개 변수는 수준 중 가장 높은(가장 자세한 정보)로 설정됩니다.

[in] MatchAnyKeyword

공급자가 작성해야 하는 이벤트의 범주를 지정하는 비트 마스크 값입니다. 제어 코드 EVENT_CONTROL_CODE_ENABLE_PROVIDER 사용하여 호출되는 경우 공급자는 MatchAnyKeyword 값을 기록해야 하며, 이후에 이벤트의 키워드(keyword) 0이 아니고 기록된 MatchAnyKeyword의 비트가 없는 이벤트를 건너뛰어야 합니다. 즉, 이벤트는

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

알림의 MatchAnyKeyword는 이 이벤트 공급자의 GUID에 대해 EnableTrace, EnableTraceEx 및EnableTraceEx2 호출에서 추적 컨트롤러가 지정한 match-any-keywords(플래그 사용)의 공용 구조체(OR)입니다. 즉, 여러 세션이 서로 다른 일치 키워드(keyword) 필터를 사용하여 이 이벤트 공급자의 이벤트를 기록하는 경우 EnableCallback 알림에 대한 MatchAnyKeyword 매개 변수는 세션의 키워드(keyword) 일치 필터의 비트OR 단위로 설정됩니다.

MatchAllKeyword

공급자가 작성해야 하는 이벤트의 범주를 지정하는 비트 마스크 값입니다. 제어 코드 EVENT_CONTROL_CODE_ENABLE_PROVIDER 알림을 받으면 공급자는 MatchAllKeyword 값을 기록해야 하며, 이후에 이벤트의 키워드(keyword) 0이 아니고 기록된 MatchAllKeyword의 모든 비트가 없는 이벤트를 건너뛰어야 합니다. 즉, 이벤트는

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

알림의 MatchAllKeyword는 이 이벤트 공급자의 GUID에 대해 EnableTraceEx 및 EnableTraceEx2 호출에서 추적 컨트롤러가 지정한 match-all-keywords의 분리(AND)입니다. 즉, 여러 세션이 서로 다른 일치 키워드(keyword) 필터를 사용하여 이 이벤트 공급자의 이벤트를 기록하는 경우 EnableCallback 알림에 대한 MatchAllKeyword 매개 변수는 세션의 키워드(keyword) 일치 필터의 비트AND 단위로 설정됩니다.

[in, optional] FilterData

이벤트 공급자에 대한 필터 데이터가 있는 EVENT_FILTER_DESCRIPTOR 대한 포인터입니다.

각 세션은 필터를 하나만 지정할 수 있습니다. 콜백 알림의 필터 설명자에는 공급자를 사용하도록 설정할 때 필터 데이터를 지정한 각 세션에서 하나의 필터가 포함됩니다.

필터 데이터는 콜백 내에서만 유효합니다. 콜백이 반환된 후 데이터가 필요한 경우 공급자는 데이터의 로컬 복사본을 만들어야 합니다.

[in, optional] CallbackContext

콜백에 대한 컨텍스트입니다. EventRegister라는 이벤트 공급자가 사용될 때 사용된 CallbackContext 매개 변수의 값입니다.

반환 값

없음

설명

구성 변경 알림이 필요한 ETW 이벤트 공급자는 EventRegister를 통해 등록할 때 EnableCallback 구현에 대한 포인터를 제공해야 합니다. ETW는 공급자와 관련된 추적 세션의 구성을 변경할 때 공급자의 EnableCallback 함수를 호출합니다. 예를 들어 추적 세션 컨트롤러가 EnableTraceEx2 를 통해 추적을 구성하거나 ControlTrace를 통해 추적을 중지하는 경우 ETW는 결과 업데이트된 구성으로 공급자의 EnableCallback 함수를 호출합니다.

참고

대부분의 이벤트 공급자는 EnableCallback 을 직접 구현하지 않습니다. 대신, 대부분의 이벤트 공급자는 자체 EnableCallback 구현을 제공하고 EventRegister, EventWrite 및 EventUnregister에 대한 호출을 래핑하는 ETW 프레임워크를 사용하여 구현됩니다. 예를 들어 이벤트 매니페스트를 작성한 다음 메시지 컴파일러 를 사용하여 이벤트에 대한 C/C++ 코드를 생성하거나 TraceLogging 을 사용하여 매니페스트가 필요하지 않을 수 있습니다. ETW 프레임워크는 일반적으로 알림의 Level, MatchAnyKeyword및 값을 기록하는 EnableCallback 함수를 구현하며 MatchAllKeyword 프레임워크는 기록된 값을 자동으로 사용하여 이벤트를 필터링합니다. ETW 프레임워크는 일반적으로 사용자가 사용자 지정 알림 처리가 필요한 경우 사용자가 제공한 콜백 호출을 지원합니다. 예를 들어 TraceLoggingProvider.h 를 사용하면 TraceLoggingRegisterEx를 통해 알림 콜백을 지정할 수 있습니다.

중요

공급자의 EnableCallback 함수는 가능한 한 간단해야 합니다. 필요한 정보를 기록하고 신속하게 반환해야 합니다. 장기 실행 콜백 함수는 EnableTraceEx2 또는 ControlTrace와 같은 ETW 세션 제어 API에서 지연을 일으킬 수 있습니다. 콜백 함수는 프로세스의 로더 잠금이 필요한 작업을 수행해서는 안 됩니다. 즉, LoadLibrary 또는 FreeLibrary를 직접 또는 간접적으로 호출해서는 안 됩니다. 콜백 함수는 잠금을 차단해서는 안 됩니다. 콜백 함수는 잠금을 차단하거나 StartTrace,ControlTrace 또는 EnableTrace와 같은 ETW 세션 제어 API를 호출하는 경우 교착 상태가 발생할 수 있습니다.

알림 콜백을 사용하면 공급자가 수준, 키워드 및 기타 필터를 자체적으로 추적할 수 있으므로 이벤트 공급자를 보다 효율적으로 실행할 수 있습니다. 필터를 추적하여 공급자는 사용하도록 설정되지 않은 이벤트를 효율적으로 건너뛸 수 있습니다(즉, 공급자가 이벤트 데이터를 준비하거나 추적 세션에 필요하지 않은 이벤트에 대해 EventWrite 를 호출할 필요가 없음).

공급자의 올바른 작업에는 필터 추적이 필요하지 않습니다. ETW는 공급자가 사용할 수 있는 EventEnabled 및 EventProviderEnabled 함수를 제공하며 ETW EventWrite API는 비활성화된 이벤트를 자동으로 무시합니다. 그러나 공급자 구현 필터 추적은 EventEnabled 또는 EventProviderEnabled에 대한 호출보다 더 효율적일 수 있습니다.

또한 알림 콜백을 사용하면 공급자가 추적 세션의 "캡처 상태" 요청을 처리할 수 있습니다. 캡처 상태 요청은 일반적으로 공급자의 이벤트 기록을 시작할 때 추적 세션에서 전송됩니다. 공급자가 캡처 상태를 지원하는 경우 상태 정보(예: 구성 정보 또는 요청 전 구성 요소 작업에 대한 요약 통계)를 로깅하여 캡처 상태 요청에 응답할 수 있습니다.

ETW가 콜백에 전달하는 수준 값은 실행 중인 추적 세션에 의해 이 이벤트 공급자에 대해 지정된 가장 높은(가장 자세한) 수준 값입니다. 예를 들어 세션 A가 경고(수준 3) 이벤트에 대해 이 공급자를 사용하도록 설정한 다음 세션 B가 중요한(수준 1) 이벤트에 대해 공급자를 사용하도록 설정한 경우 콜백의 수준 값은 1이 아닌 3이 됩니다.

마찬가지로 MatchAnyKeyword 및 MatchAllKeyword 값은 이벤트 공급자를 사용하도록 설정한 모든 세션의 구성에서 계산된 복합 값입니다. MatchAnyKeyword 는 세션의 EnableFlags/MatchAnyKeyword 설정의 OR입니다. MatchAllKeyword 는 세션의 MatchAllKeyword 설정의 AND입니다.

공급자의 EnableCallback 함수가 공급자의 Enabled, Level, MatchAnyKeyword 및 MatchAllKeyword 상태를 캡처한 경우 공급자는 다음과 같은 함수를 사용하여 이벤트를 작성해야 하는지 여부를 결정할 수 있습니다.

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	evntprov.h

추가 정보

EventRegister

EnableTrace

EnableTraceEx2

다음을 통해 공유

PENABLECALLBACK 콜백 함수(evntprov.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

추가 리소스