TraceLoggingChannel 매크로(traceloggingprovider.h)

아티클
08/26/2023

이벤트의 채널을 설정하는 TraceLogging 래퍼 매크로입니다.

대부분의 TraceLogging 이벤트는 이벤트의 기본 채널을 변경할 필요가 없으며 TraceLoggingChannel을 사용하면 안 됩니다.

구문

void TraceLoggingChannel(
  [in]  eventChannel
);

매개 변수

[in] eventChannel

이벤트를 기록해야 하는 채널입니다. 0에서 255까지의 정수 값입니다.

이벤트 채널에 대한 자세한 내용은 EVENT_DESCRIPTOR 참조하세요.

반환 값

없음

설명

TraceLoggingChannel(eventChannel)는 TraceLoggingWrite 매크로 호출에 대한 매개 변수로 사용할 수 있습니다. 대부분의 TraceLogging 이벤트는 이벤트의 기본 채널을 변경할 필요가 없으며 TraceLoggingChannel을 사용하면 안 됩니다.

eventChannel 매개 변수는 컴파일 시간 상수 0~255여야 합니다. 인수가 제공되지 않으면 TraceLoggingChannel(n) 기본 채널은 11(WINEVENT_CHANNEL_TRACELOGGING)이며 이는 일반적인 TraceLogging 이벤트임을 나타냅니다. 여러 TraceLoggingChannel(n) 인수가 제공되면 마지막 TraceLoggingChannel(n) 매개 변수의 값이 사용됩니다.

채널은 ETW(Windows용 고급 이벤트 추적) 시나리오에서 사용됩니다. 여기에는 Windows 이벤트 로그와 같은 시스템 정의 이벤트 소비자에게 쓰는 것이 포함 됩니다.

경고

공급자가 Windows 10 이전 Windows에서 실행되는 경우 TraceLoggingChannel을 사용하지 마세요. 이벤트 디코더에서 TraceLogging 호환으로 인식되려면 채널이 기본값(11)으로 설정되었거나 EventWrite 중에 ETW 런타임에 의해 TraceLogging 이벤트로 표시되어 있어야 합니다. 이 이벤트 표시는 EventSetInformation을 호출하여 공급자를 TraceLogging 공급자로 구성하여 사용하도록 설정됩니다. Windows 10 이상의 EventSetInformation을 사용하면 채널에 관계없이 TraceLogging 이벤트를 지원할 수 있지만 이전 버전의 Windows에서는 TraceLogging 이벤트 표시를 지원하기 전에 Windows 업데이트가 필요합니다. 업데이트된 EventSetInformation 없이 시스템에서 캡처된 이벤트의 경우 채널 11은 TraceLogging 이벤트를 인식하는 유일한 방법이므로 다른 채널이 있는 이벤트는 올바르게 디코딩되지 않을 수 있습니다.

TraceLogging 및 이벤트 로그

대부분의 경우 개발자는 이벤트 로그에서 기록해야 하는 이벤트에 매니페스트 기반 ETW를 사용합니다. 이벤트 로그는 주로 시스템 관리자에게 유용할 수 있는 볼륨이 낮은 이벤트를 수집하기 위한 것입니다. 매니페스트 기반 ETW는 신중하게 큐레이팅된 이벤트(구성 요소에 대한 모든 이벤트는 하나의 매니페스트 파일에 설명되어 있음)를 지원하고 관리자가 이벤트에 대응하는 방법을 알 수 있도록 하는 지역화 가능한 메시지 문자열을 지원하기 때문에 이 작업에 적합합니다.

TraceLogging 이벤트에는 메시지 문자열이 없으며 일반적으로 중앙에서 큐레이팅되지 않지만 TraceLogging은 일부 이벤트 로그 시나리오에 적합할 수 있습니다. 예를 들어 Windows 로그(애플리케이션, 보안, 설치 및 시스템)로 이동하는 이벤트에는 항상 지역화된 메시지 문자열이 있어야 하며 시스템 관리자에게 항상 유용해야 하지만 애플리케이션 및 서비스 로그에 기록된 이벤트는 더 기술적일 수 있으며 진단 정보를 기록할 수 있습니다. 애플리케이션 및 서비스 로그에 쓸 때 TraceLogging을 사용하여 기록된 이벤트의 관리를 간소화할 수 있습니다.

Windows 이벤트 로그와 함께 TraceLogging 이벤트를 사용하는 것은 이벤트 로그와 함께 일반 매니페스트 기반 이벤트를 사용하는 것과 비슷합니다. 공급자와 채널을 정의하기 위해 매니페스트를 만들고 등록해야 하지만 매니페스트에서 개별 이벤트를 정의할 필요는 없습니다.

공급자 및 이벤트 로그 채널을 정의하는 ETW 매니페스트를 작성합니다. 매니페스트의 공급자는 TRACELOGGING_DEFINE_PROVIDER 매크로에서 사용한 것과 동일한 공급자 이름 및 공급자 GUID(공급자 ID)를 사용해야 합니다. TraceLogging 이벤트가 자체 설명이므로 매니페스트에 또는 <template> 정의를 포함 <event> 할 필요가 없습니다.
구성 요소의 빌드 프로세스에서 Windows SDK 10.0.22621 이상의 메시지 컴파일러(MC.exe)를 사용하여 매니페스트를 컴파일합니다. 그러면 다음 파일이 생성됩니다.
- ManifestName.h: 상수 정의를 포함하는 C/C++ 헤더입니다. 그러면 TraceLogging 이벤트에서 사용해야 하는 ChannelSymbol 및 ChannelSymbol_KEYWORD 상수가 정의됩니다. (상수의 실제 이름은 채널마다 다릅니다.)
- ManifestName.rc: 매니페스트 BIN 데이터를 이진 파일(EXE, DLL 또는 SYS) 파일에 추가하는 리소스 컴파일러(RC.exe) 스크립트입니다. 구성 요소에 있는 이진 파일 중 하나의 리소스에 이 리소스 스크립트를 포함해야 합니다.
- ManifestNameTEMP.BIN, MSG00001.bin: 에서 참조하는 ManifestName.rc매니페스트 BIN 데이터입니다.
#include TraceLogging 이벤트를 생성해야 하는 코드에 생성된 ManifestName.h 파일입니다. 그러면 ChannelSymbol 및 ChannelSymbol_KEYWORD 상수가 정의됩니다.
- 매니페스트의 또는 <importChannel> 정의에서 <channel>기호 특성을 지정한 경우 ChannelSymbol의 이름은 기호 특성의 값이 됩니다. 그렇지 않으면 ChannelSymbol이 ProviderSymbol_CHANNEL_ChannelName 됩니다(즉, 요소의 기호 <provider> 와 또는 <importChannel> 요소의 이름을 <channel> 사용합니다).
- ChannelSymbol_KEYWORD 이름은 ChannelSymbol의 이름 뒤에 가 잇_KEYWORD는 이름입니다.
- ChannelSymbol_KEYWORD 상수는 10.0.22621 이상에서만 생성 MC.exe 됩니다.
이벤트 로그로 이동하는 각 TraceLogging 이벤트는 를 사용해야 합니다.TraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)을 선택하여 이벤트에 대한 채널 및 키워드(keyword) 설정합니다. 예를 들어 내 채널의 기호가 MY_CHANNEL인 경우 이벤트에 대한 매크로에 TraceLoggingWrite 매개 변수로 를 추가 TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) 합니다.
이벤트 로그가 공급자를 인식하려면 매니페스트의 정보가 대상 시스템에 설치될 모듈(DLL, EXE 또는 SYS 파일)의 리소스에 포함되어야 합니다 .
이벤트 로그가 공급자로부터 이벤트를 수신하려면 구성 요소 설치 중에 를 사용하여 대상 시스템에 매니페스트 를 wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll 등록해야 합니다. 또한 구성 요소를 제거하는 동안 을 사용하여 wevtutil um ManifestFile.man 매니페스트의 등록을 취소해야 합니다.

중요

공급자가 이벤트 로그에 등록된 경우 이벤트가 이벤트 로그용이 아니더라도 공급자가 생성한 모든 이벤트에는 TraceLoggingKeyword로 지정된 0이 아닌 키워드(keyword) 있어야 합니다. 키워드(keyword) 0이 있는 이벤트는 효율적으로 필터링할 수 없으며 이벤트 로그에만 전달되어 삭제됩니다. 이벤트 로그가 공급자의 이벤트를 수신 대기하는 경우 키워드 0이 있는 이벤트는 이벤트 로그 오버헤드를 불필요하게 증가합니다.

이벤트 로그에 대한 TraceLogging 이벤트의 예:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

여러 TraceLoggingKeyword 인수를 사용하거나 단일 TraceLoggingKeyword 인수(예: )에 여러 키워드를 지정하여 적절한 경우 추가 사용자 지정 키워드를 이벤트에 추가할 수 있습니다. TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD)

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 10 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 R2
대상 플랫폼	Windows
헤더	traceloggingprovider.h

추가 정보

EVENT_DESCRIPTOR

TraceLoggingWrite

TraceLogging 래퍼 매크로