다음을 통해 공유

TraceLoggingWriteActivity 매크로(traceloggingprovider.h)

  • 아티클

지정된 활동 ID를 사용하여 TraceLogging 이벤트를 내보낸다.

구문

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [in, optional]  __VA_ARGS__
);

매개 변수

[in] hProvider

이벤트를 작성하는 데 사용할 TraceLogging 공급자 의 핸들입니다.

[in] eventName

이벤트를 식별하는 데 사용할 짧고 고유한 이름입니다. 변수가 아닌 문자열 리터럴이어야 합니다. 포함된 '\0' 문자는 사용할 수 없습니다.

[in, optional] pActivityId

이벤트의 활동 ID 또는 기본값을 사용할 NULL입니다.

[in, optional] pRelatedActivityId

이벤트의 관련 활동 ID이거나 관련 활동 ID가 없는 경우 NULL입니다.

[in, optional] __VA_ARGS__

이벤트를 구성하거나 필드에 추가할 최대 99개 추가 매개 변수입니다. 각 매개 변수는 TraceLoggingLevel, TraceLoggingKeyword 또는 TraceLoggingValue와 같은 TraceLogging래퍼 매크로 중 하나여야 합니다.

중요

ProviderId, Level 및 Keyword는 이벤트를 필터링하는 기본 수단입니다. 다른 종류의 필터링이 가능하지만 오버헤드가 훨씬 더 높습니다. 항상 0이 아닌 수준을 할당하고 모든 이벤트에 키워드(keyword).

반환 값

없음

설명

TraceLoggingWriteActivity 매크로의 각 호출은 지정된 공급자 핸들을 통해 ETW에 이벤트를 작성하는 데 필요한 코드로 확장됩니다.

  • TraceLoggingWriteActivity 는 지정된 공급자가 등록되었는지 여부를 확인합니다. 공급자가 등록되지 않은 경우 TraceLoggingWriteActivity 는 아무 작업도 수행하지 않습니다.
  • TraceLoggingWriteActivity 는 TraceLoggingProviderEnabled를 호출하는 것처럼 소비자가 이벤트를 수신 대기하는지 여부를 확인합니다. 이벤트를 수신 대기하는 소비자가 없는 경우 TraceLoggingWriteActivity 는 아무 작업도 수행하지 않습니다.
  • 그렇지 않으면 TraceLoggingWriteActivity 는 인수에 지정된 런타임 식을 평가하고, 결과를 저장하고, 필요한 데이터를 이벤트에 압축하고, EventWriteTransfer 를 호출하여 이벤트를 ETW로 보냅니다.

생성된 이벤트는 다음과 같이 생성됩니다.

  • 이벤트의 공급자 ID, 공급자 이름 및 공급자 그룹은 hProvider 매개 변수에서 가져옵니다.
  • 이벤트의 이름은 eventName 매개 변수에서 가져옵니다.
  • 이벤트의 활동 ID는 pActivityId 매개 변수에서 가져옵니다. pActivityId가 NULL인 경우 사용자 모드 이벤트는 스레드의 암시적 작업 ID를 사용하고 커널 모드 이벤트는 GUID_NULL 사용합니다.
  • 이벤트의 관련 활동 ID는 pRelatedActivityId 매개 변수에서 가져옵니다. pRelatedActivityId가 NULL이면 이벤트에 관련 활동 ID가 없습니다.
  • 이벤트의 수준은 TraceLoggingLevel 인수에서 가져옵니다. TraceLoggingLevel 인수가 없으면 이벤트의 수준은 5(WINEVENT_LEVEL_VERBOSE)가 됩니다. 둘 이상의 TraceLoggingLevel 인수가 있는 경우 마지막 인수가 사용됩니다. 효과적인 이벤트 필터링을 사용하도록 설정하려면 항상 모든 이벤트에 의미 있는 0이 아닌 수준을 할당합니다.
  • 이벤트의 키워드(keyword) TraceLoggingKeyword 인수에서 가져옵니다. TraceLoggingKeyword 인수가 없으면 이벤트의 키워드(keyword) 0(NONE)이 됩니다. 둘 이상의 TraceLoggingKeyword 인수가 있는 경우 값은 함께 OR가 됩니다. 효과적인 이벤트 필터링을 사용하도록 설정하려면 항상 모든 이벤트에 의미 있는 0이 아닌 키워드(keyword) 할당합니다.
  • 다른 이벤트 특성은 TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag 또는 TraceLoggingChannel과 같은 인수에 의해 설정될 수 있습니다.
  • 이벤트 필드는 TraceLoggingStruct를 사용하여 그룹화할 수 있습니다.
  • 이벤트 필드는 TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString 등의 필드 인수에 의해 추가됩니다. 자세한 내용은 추적 로깅 래퍼 매크로를 참조하세요.

예를 들면 다음과 같습니다.

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) 호출을 다음과 같이 코드로 확장하는 것으로 간주할 수 있습니다.

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}

참고

각 TraceLoggingWriteActivity 매크로는 TraceLoggingProviderEnabled 를 자동으로 확인하므로 소비자가 공급자의 이벤트를 수신 대기하는 경우에만 이벤트가 기록됩니다. 따라서 일반적으로 TraceLoggingProviderEnabled를 직접 호출할 필요가 없습니다. 의 args... 모든 런타임 식은 이벤트가 활성화된 경우에만 평가됩니다. 런타임 식은 두 번 이상 평가되지 않습니다.

복잡한 이벤트를 생성하는 경우 줄이 너무 길거나 컴파일러가 힙 공간이 부족함을 나타내는 컴파일러 오류가 발생할 수 있습니다. 이는 TraceLoggingWriteActivity 매크로가 컴파일러에서 지원될 수 있는 것보다 긴 줄로 확장될 때 발생합니다. 이 경우 이벤트를 간소화해야 합니다.

TraceLoggingWriteActivity 매크로는 EVENT_DATA_DESCRIPTOR 배열을 사용하여 데이터를 ETW로 전송합니다. ETW에서 허용하는 최대 설명자 수는 128개입니다. 각 매개 변수는 0, 1 또는 2 설명자를 사용해야 할 수 있으므로 인수 제한(99)에 도달하기 전에 데이터 설명자 제한(128)에 도달할 수 있습니다.

중요

큰 이벤트를 방지합니다. ETW는 주로 작은 이벤트를 처리하도록 설계되었습니다. TraceLoggingWriteActivity 는 너무 큰 이벤트를 자동으로 삭제합니다. 이벤트의 크기는 이벤트의 헤더(ETW 런타임에서 추가됨), 메타데이터(예: 공급자 이름, 이벤트 이름, 필드 이름, 필드 형식) 및 데이터(필드 값)의 합계를 기반으로 합니다. 이벤트의 총 크기가 65535보다 크거나 소비자 세션에서 이벤트 크기보다 작은 버퍼 크기를 사용하는 경우 이벤트가 기록되지 않습니다.

TraceLoggingWrite 호출은 pActivityId 및 pRelatedActivityId 매개 변수에 대해 NULL을 사용하여 TraceLoggingWriteActivity를 호출하는 것과 동일합니다. 이벤트에 대한 활동 ID를 지정해야 하는 경우 TraceLoggingWriteActivity 를 사용합니다.

ActivityId 및 RelatedActivityId 매개 변수의 의미 체계에 대한 자세한 내용은 EventWriteTransfer를 참조하세요.

ETW에서 활동을 작성하는 방법에 대한 자세한 내용은 EventActivityIdControl 을 참조하세요.

TraceLogging ETW 작업을 관리하는 데 도움이 되는 C++ 클래스에 대한 TraceLoggingActivity 를 참조하세요.

요구 사항

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

추가 정보

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

추적 로깅 래퍼 매크로