TraceLoggingWriteActivity 매크로(traceloggingprovider.h)

아티클
08/26/2023

지정된 활동 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