Share via

TraceLoggingWrite 매크로(traceloggingprovider.h)

  • 아티클

TraceLogging 이벤트를 내보낸다.

구문

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

매개 변수

[in] hProvider

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

[in] eventName

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

[in, optional] __VA_ARGS__

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

중요

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

반환 값

없음

설명

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

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

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

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

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

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

의 호출 TraceLoggingWrite(hProvider, "EventName", args...) 은 다음과 같이 코드로 확장하는 것으로 간주될 수 있습니다.

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

참고

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

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

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

중요

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

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

예제

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

요구 사항

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

추가 정보

EventWriteTransfer

TraceLoggingWriteActivity

추적 로깅 래퍼 매크로