EnableTraceEx 함수(evntrace.h)

아티클
06/12/2024

추적 세션 컨트롤러는 EnableTraceEx 를 호출하여 ETW 이벤트 공급자가 추적 세션에 이벤트를 기록하는 방법을 구성합니다.

이 함수는 사용되지 않습니다. EnableTraceEx2 함수는 이 함수를 대체합니다.

구문

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

매개 변수

[in] ProviderId

구성하려는 이벤트 공급자의 공급자 ID(컨트롤 GUID)입니다.

[in, optional] SourceId

이 구성 요청의 원본을 고유하게 식별할 수 있는 GUID이거나 원본 ID가 필요하지 않은 경우 NULL 입니다( SourceId 를 로 설정하는 것과 &GUID_NULL동일). 지정된 경우 이 값은 공급자의 EnableCallback을 호출할 때 SourceId 매개 변수로 사용됩니다.

참고

EnableTrace 호출과 공급자의 EnableCallback에 대한 해당 호출 간에 항상 직접 매핑이 있는 것은 아닙니다. 예를 들어 아직 등록되지 않은 공급자에 대해 EnableTrace를 호출하는 경우 등록이 발생할 때까지 EnableCallback에 대한 호출이 지연되고 추적 소비자 세션이 중지되면 ETW는 EnableTrace에 대한 해당 호출이 없더라도 EnableCallback을 호출합니다. 이러한 경우 SourceId가 GUID_NULL 설정된 상태에서 EnableTrace가 호출됩니다.

TraceId

[in] IsEnabled

공급자로부터 이벤트를 받도록 설정하거나 공급자로부터 이벤트를 수신할 때 사용되는 설정을 조정하려면 1로 설정합니다(예: 수준 및 키워드 변경). 공급자로부터 이벤트 수신을 사용하지 않도록 설정하려면 0으로 설정합니다.

[in] Level

공급자가 작성하려는 이벤트의 최대 수준을 나타내는 값입니다. 일반적으로 공급자는 MatchAnyKeyword 및 MatchAllKeyword 조건을 충족하는 것 외에도 이벤트의 수준이 이 값보다 작거나 같은 경우 이벤트를 작성합니다.

Microsoft는 아래와 같이 수준 1-5의 의미 체계를 정의합니다. 값이 낮을수록 더 심각한 이벤트가 표시됩니다. EnableLevel의 각 값은 지정된 수준과 더욱 심각한 수준을 사용하도록 설정합니다. 예를 들어 를 지정 TRACE_LEVEL_WARNING하면 소비자는 경고, 오류 및 중요한 이벤트를 받게 됩니다.

값	의미
TRACE_LEVEL_CRITICAL (1)	비정상적인 종료 또는 종료 이벤트
TRACE_LEVEL_ERROR (2)	심각한 오류 이벤트
TRACE_LEVEL_WARNING (3)	할당 오류와 같은 경고 이벤트
TRACE_LEVEL_INFORMATION (4)	오류 없는 정보 이벤트
TRACE_LEVEL_VERBOSE (5)	자세한 진단 이벤트

상수는 TRACE_LEVELevntrace.h에 정의됩니다. 동등한 WINMETA_LEVEL 상수는 winmeta.h에 정의됩니다.

[in] MatchAnyKeyword

공급자가 작성하려는 이벤트의 범주를 결정하는 키워드의 64비트 비트 마스크입니다. 일반적으로 공급자는 이벤트의 키워드 비트가 이 값에 설정된 비트 와 일치하거나이벤트에 Level 및 MatchAllKeyword 조건을 충족하는 것 외에 키워드 비트가 설정되지 않은 경우 이벤트를 작성합니다.

[in] MatchAllKeyword

공급자가 작성하려는 이벤트를 제한하는 키워드의 64비트 비트 마스크입니다. 일반적으로 공급자는 이벤트의 키워드 비트가 이 값에 설정된 모든 비트와 일치하거나 이벤트에 Level 및 MatchAnyKeyword 조건을 충족하는 것 외에 키워드 비트가 설정되지 않은 경우 이벤트를 작성합니다.

이 값은 자주 0으로 설정됩니다.

[in] EnableProperty

이 공급자에서 이벤트를 수집할 때 ETW 런타임에서 사용하도록 설정해야 하는 특수 동작을 지정하는 플래그입니다. 특수 동작을 사용하도록 설정하려면 다음 플래그 중 하나 이상을 지정합니다. 그렇지 않으면 EnableProperty 를 0으로 설정합니다.

참고

이러한 플래그 중 일부는 ETW가 각 이벤트에 추가 정보를 포함해야 함을 나타냅니다. 데이터는 이벤트의 확장된 데이터 항목 섹션에 기록됩니다.

값	의미
EVENT_ENABLE_PROPERTY_SID	확장 데이터에 사용자의 SID(보안 식별자)를 포함합니다.
EVENT_ENABLE_PROPERTY_TS_ID	확장 데이터에 터미널 세션 식별자를 포함합니다.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	추적 세션은 키워드가 0인 이벤트를 기록해서는 안 됩니다.

[in, optional] EnableFilterDesc

필터 데이터를 가리키는 EVENT_FILTER_DESCRIPTOR 구조체입니다. 공급자는 이를 사용하여 데이터를 필터링하여 필터 조건과 일치하지 않는 이벤트가 세션에 기록되지 않도록 합니다. 공급자는 데이터의 레이아웃과 필터를 이벤트 데이터에 적용하는 방법을 결정합니다. 세션은 공급자에게 필터를 하나만 전달할 수 있습니다.

세션은 TdhEnumerateProviderFilters 함수를 호출하여 공급자가 지원을 등록한 필터를 조회할 수 있습니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.

ERROR_INVALID_PARAMETER

다음 중 하나에 해당합니다.
- ProviderId 가 NULL입니다.
- TraceHandle 은 NULL입니다.
ERROR_INVALID_FUNCTION

공급자가 등록되지 않은 경우 수준을 업데이트할 수 없습니다.
ERROR_NO_SYSTEM_RESOURCES

공급자를 사용하도록 설정할 수 있는 추적 세션 수를 초과했습니다.
ERROR_ACCESS_DENIED

관리 권한이 있는 사용자, 그룹의 사용자 Performance Log Users 및 , LocalService또는 NetworkService 로 LocalSystem실행되는 서비스만 이벤트 공급자를 프로세스 간 세션에 사용하도록 설정할 수 있습니다. 제한된 사용자에게 이벤트 공급자를 사용하도록 설정할 수 있는 기능을 부여하려면 그룹에 추가 Performance Log Users 하거나 EventAccessControl을 참조하세요.

Windows XP 및 Windows 2000: 누구나 이벤트 공급자를 사용하도록 설정할 수 있습니다.

설명

이벤트 추적 컨트롤러는 이 함수를 호출하여 세션에 이벤트를 쓰는 이벤트 공급자를 구성합니다. 예를 들어 컨트롤러는 공급자로부터 이벤트 수집을 시작하거나, 공급자로부터 수집되는 이벤트의 수준 또는 키워드를 조정하거나, 공급자로부터 이벤트 수집을 중지하기 위해 이 함수를 호출할 수 있습니다.

이 함수는 사용되지 않습니다. 추가 기능을 위해 새 코드는 EnableTraceEx2를 사용해야 합니다.

대부분의 경우 다음과 같이 EnableTraceEx 에 대한 호출을 EnableTraceEx2 로 변환할 수 있습니다.

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

더 복잡한 시나리오에서는 다음과 같이 EnableTraceEx 에 대한 호출을 EnableTraceEx2 로 변환할 수 있습니다.

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

세션에 대한 공급자 구성의 의미 체계에 대한 자세한 내용은 EnableTraceEx2에 대한 설명서를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	evntrace.h
라이브러리	Advapi32.lib
DLL	Advapi32.dll

추가 정보

StartTrace

EnableTraceEx2

다음을 통해 공유

EnableTraceEx 함수(evntrace.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

피드백

추가 리소스