이벤트 데이터 템플릿 정의
공급자는 데이터 템플릿을 사용하여 이벤트와 함께 포함하는 이벤트별 데이터를 정의하고 ETW 추적 세션이 공급자를 사용하도록 설정할 때 공급자에게 전달할 수 있는 필터 데이터를 정의합니다. 이벤트에 이벤트별 데이터가 포함되지 않은 경우 템플릿을 정의하지 않습니다. 템플릿을 정의하려면 템플릿 요소를 사용합니다. 템플릿에는 공급자가 이벤트와 함께 포함하는 데이터의 각 부분에 대한 데이터 항목이 포함됩니다. 정수 형식, 문자열, 배열 및 구조를 지정할 수 있습니다. 데이터 항목이 템플릿에 정의된 순서대로 이벤트 데이터를 작성해야 합니다.
소비자가 이벤트 데이터를 렌더링하는 방법을 결정하는 데 사용해야 하는 XML 조각인 템플릿에도 포함할 수 있습니다. 조각을 포함하지 않으면 소비자는 데이터 항목이 템플릿에 정의된 순서대로 이벤트 데이터를 렌더링해야 합니다.
템플릿을 정의할 때 이벤트 정의에서 템플릿을 참조하는 데 사용하는 템플릿 식별자를 제공해야 합니다. 템플릿의 각 데이터 항목은 이름과 입력 데이터 형식을 지정해야 합니다(입력 형식 목록은 InputType 복합 형식의 주의 섹션 참조). 입력 데이터 형식을 여러 형식으로 렌더링할 수 있는 경우 소비자에게 데이터 항목을 렌더링하는 방법을 알려주는 출력 데이터 형식을 지정해야 합니다. 예를 들어 UInt32 입력 데이터 형식을 부호 없는 정수, 스레드 식별자, IPv4 주소 및 Win32 오류 코드로 렌더링할 수 있습니다. 출력 데이터 형식을 지정하지 않으면 소비자는 입력 형식의 기본 출력 형식을 사용하여 데이터 항목을 렌더링해야 합니다.
배열을 지정하려면 데이터 항목에 count 특성을 포함하고 배열의 요소 수로 설정합니다. 배열은 가변 크기 배열 또는 고정 크기 배열일 수 있습니다. 배열이 고정 크기 배열인 경우 개수를 배열 크기로 설정합니다. 예를 들어 정수 배열의 고정 크기가 10인 경우 개수를 10으로 설정합니다. 배열을 작성할 때는 40바이트의 데이터를 작성해야 합니다.
배열이 가변 크기 배열인 경우 개수를 배열의 크기를 포함하는 데이터 항목의 이름으로 설정합니다. 배열에 포인터가 포함된 경우 포인터의 주소는 포인터가 가리키는 데이터가 아니라 이벤트 데이터로 작성됩니다.
데이터 항목이 이진 Blob인 경우 길이 특성을 지정해야 합니다. 고정 길이 문자열의 길이 특성을 지정할 수도 있습니다.
데이터 항목이 열거형 값을 나타내고 소비자가 값 자체 대신 값에 대한 문자열을 인쇄하도록 하려면 map 특성을 지정합니다.
템플릿에 구조체를 포함하는 경우 8 바이트 경계 맞춤을 보장할 수 없는 한 구조를 작성하는 대신 구조체의 멤버를 개별적으로 작성해야 합니다.
특히 이벤트가 전역 채널에 기록되는 경우 이벤트에 포함된 정보를 신중하게 고려해야 합니다. 일반적으로 이벤트에 개인 정보를 포함해서는 안 됩니다. 여기에는 일반 텍스트 암호 및 개인 사용자 정보가 포함됩니다. 또한 사용자가 실행하는 프로그램, 사용자가 방문한 URL 및 컴퓨터의 사용자 활동과 관련된 기타 정보는 비공개로 간주되어야 합니다.
이벤트에 URL 및 사용자 이름을 기록해야 하는 경우 인증된 모든 사용자가 이러한 채널을 읽을 수 있으므로 Windows 채널(시스템 및 애플리케이션)에 URL 및 사용자 이름을 기록하지 마세요. 대신 사용자 고유의 운영 또는 분석 채널에 씁니다. 관리자만 이벤트를 읽을 수 있도록 이러한 채널에 대한 액세스 권한을 설정합니다. 관리자가 개인 정보를 사용할 수 있다는 사실을 사용자에게 알리기 위해 적절한 공개를 제공해야 할 수 있습니다.
다음 예제에서는 템플릿을 정의하는 방법을 보여줍니다. 이벤트 정의 또는 필터 정의에서 참조하는 템플릿의 tid 특성을 지정해야 합니다.
<instrumentationManifest
xmlns="http://schemas.microsoft.com/win/2004/08/events"
xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
>
<instrumentation>
<events>
<provider name="Microsoft-Windows-SampleProvider"
guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
symbol="PROVIDER_GUID"
resourceFileName="<path to the exe or dll that contains the metadata resources>"
messageFileName="<path to the exe or dll that contains the string resources>"
message="$(string.Provider.Name)">
. . .
<maps>
<valueMap name="TransferType">
<map value="1" message="$(string.TransferType.Download)"/>
<map value="2" message="$(string.TransferType.Upload)"/>
<map value="3" message="$(string.TransferType.UploadReply)"/>
</valueMap>
<bitMap name="DaysOfTheWeek">
<map value="0x1" message="$(string.DaysOfTheWeek.Sunday)"/>
<map value="0x2" message="$(string.DaysOfTheWeek.Monday)"/>
<map value="0x4" message="$(string.DaysOfTheWeek.Tuesday)"/>
<map value="0x8" message="$(string.DaysOfTheWeek.Wednesday)"/>
<map value="0x10" message="$(string.DaysOfTheWeek.Thursday)"/>
<map value="0x20" message="$(string.DaysOfTheWeek.Friday)"/>
<map value="0x40" message="$(string.DaysOfTheWeek.Saturday)"/>
</bitMap>
</maps>
<templates>
<template tid="t2">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="Day" inType="win:UInt32" map="DaysOfTheWeek"/>
<data name="Transfer" inType="win:UInt32" map="TransferType"/>
</template>
<template tid="t3">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="ErrorCode" inType="win:Int32" outType="win:HResult"/>
<data name="FilesCount" inType="win:UInt16" />
<data name="Files" inType="win:UnicodeString" count="FilesCount"/>
<data name="BufferSize" inType="win:UInt32" />
<data name="Buffer" inType="win:Binary" length="BufferSize"/>
<data name="Certificate" inType="win:Binary" length="11" />
<data name="IsLocal" inType="win:Boolean" />
<data name="Path" inType="win:UnicodeString" />
<data name="ValuesCount" inType="win:UInt16" />
<struct name="Values" count="ValuesCount" >
<data name="Value" inType="win:UInt16" />
<data name="Name" inType="win:UnicodeString" />
</struct>
</template>
</templates>
. . .
</provider>
</events>
</instrumentation>
<localization>
<resources culture="en-US">
<stringTable>
<string id="Provider.Name" value="Sample Provider"/>
<string id="TransferType.Download" value="Download"/>
<string id="TransferType.Upload" value="Upload"/>
<string id="TransferType.UploadReply" value="Upload-reply"/>
<string id="DaysOfTheWeek.Sunday" value="Sunday"/>
<string id="DaysOfTheWeek.Monday" value="Monday"/>
<string id="DaysOfTheWeek.Tuesday" value="Tuesday"/>
<string id="DaysOfTheWeek.Wednesday" value="Wednesday"/>
<string id="DaysOfTheWeek.Thursday" value="Thursday"/>
<string id="DaysOfTheWeek.Friday" value="Friday"/>
<string id="DaysOfTheWeek.Saturday" value="Saturday"/>
</stringTable>
</resources>
</localization>
</instrumentationManifest>