계측 매니페스트 작성

아티클
06/13/2023

애플리케이션 및 DLL은 계측 매니페스트를 사용하여 계측 공급자와 공급자가 작성하는 이벤트를 식별합니다. 매니페스트는 공급자를 식별하는 요소가 포함된 XML 파일입니다. 규칙은 .man을 매니페스트의 확장으로 사용하는 것입니다. 매니페스트는 이벤트 매니페스트 XSD를 준수해야 합니다. 스키마에 대한 자세한 내용은 EventManifest 스키마를 참조하세요.

계측 공급자는 EventWriteEx, EventWriteString 또는 EventWriteTransfer 함수를 호출하여 ETW( 이벤트 추적 ) 추적 세션 또는 이벤트 로그 채널에 이벤트를 쓰는 모든 애플리케이션 또는 DLL입니다. 애플리케이션은 작성하는 모든 이벤트를 포함하는 단일 계측 공급자를 정의하거나 애플리케이션에 대한 공급자와 각 DLL에 대한 공급자를 정의할 수 있습니다. 애플리케이션이 매니페스트에서 정의하는 공급자 수는 애플리케이션이 작성하는 이벤트를 구성하는 방법에만 따라 달라집니다.

각 DLL에 대해 공급자를 지정하면 개별 공급자와 해당 공급자가 생성하는 이벤트를 사용하거나 사용하지 않도록 설정할 수 있다는 장점이 있습니다. 이 장점은 공급자가 ETW 추적 세션에서 사용하도록 설정된 경우에만 적용됩니다. 이벤트 로그 채널을 지정하는 모든 이벤트는 항상 해당 채널에 기록됩니다.

매니페스트는 공급자와 공급자가 작성하는 이벤트를 식별해야 하지만 채널, 수준 및 키워드와 같은 다른 메타데이터는 선택 사항입니다. 선택적 메타데이터를 정의할지 여부는 이벤트를 사용할 사람에 따라 달라집니다. 예를 들어 관리자 또는 지원 담당자가 이벤트 로그 채널에서 이벤트를 읽는 Windows 이벤트 뷰어 같은 도구를 사용하여 이벤트를 사용하는 경우 이벤트가 기록되는 채널을 정의해야 합니다. 그러나 공급자가 ETW 추적 세션에서만 사용하도록 설정되는 경우 채널을 정의할 필요가 없습니다.

수준, 작업, opcodes 및 키워드 메타데이터는 선택 사항이지만 이벤트를 논리적으로 그룹화하거나 버킷하는 데 사용해야 합니다. 이벤트를 그룹화하면 소비자가 관심 있는 이벤트만 사용하는 데 도움이 됩니다. 예를 들어 소비자는 수준이 "중요"하고 키워드(keyword) "쓰기"인 모든 이벤트를 쿼리하거나 특정 태스크에서 작성한 모든 이벤트를 쿼리할 수 있습니다.

수준 및 키워드를 사용하여 특정 유형의 이벤트를 사용하는 소비자 외에도 ETW 추적 세션은 수준 및 키워드(keyword) 메타데이터를 사용하여 ETW에 이벤트 추적 로그에 기록된 이벤트를 제한하도록 지시할 수 있습니다. 예를 들어 세션은 수준이 "오류" 또는 "위험"이고 키워드(keyword) "읽기"인 이벤트로만 이벤트를 제한할 수 있습니다.

공급자는 세션이 이벤트 데이터를 기반으로 이벤트를 필터링하는 데 사용하는 필터를 정의할 수 있습니다. 수준 및 키워드를 사용하여 ETW는 이벤트가 로그에 기록되는지 여부를 결정하지만 필터를 사용하여 공급자는 필터 데이터 조건을 사용하여 이벤트를 해당 세션에 쓸지 여부를 결정합니다. 필터는 ETW 추적 세션에서 공급자를 사용하도록 설정하는 경우에만 적용됩니다.

다음 섹션에서는 매니페스트의 구성 요소를 정의하는 방법을 보여 줍니다.

계측 매니페스트를 수동으로 작성할 수 있지만 Windows SDK의 \Bin 폴더에 포함된 ECManGen.exe 도구를 사용하는 것이 좋습니다. ECManGen.exe 도구는 XML 태그를 사용하지 않고도 처음부터 매니페스트를 만드는 방법을 안내하는 GUI를 사용합니다. 이 섹션 및 EventManifest 스키마 섹션의 정보에 대한 지식이 있으면 도구를 사용할 때 도움이 됩니다.

Visual Studio를 XML 편집기로 사용하는 경우 EventManifest 스키마를 프로젝트에 추가하여(XML 메뉴 참조) Intellisense, 인라인 스키마 유효성 검사 및 기타 기능을 활용하여 매니페스트를 쉽고 정확하게 작성할 수 있습니다.

매니페스트를 작성한 후 메시지 컴파일러를 사용하여 매니페스트의 유효성을 검사하고 공급자에 포함하는 리소스 및 헤더 파일을 생성합니다. 자세한 내용은 계측 매니페스트 컴파일을 참조하세요.

다음 예제에서는 완전히 정의된 이벤트 매니페스트의 골격을 보여줍니다.

<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 ...>
                <channels>
                    <importChannel .../>
                    <channel .../>
                </channels>
                <levels>
                    <level .../>
                </levels>
                <tasks>
                    <task .../>
                </tasks>
                <opcodes>
                    <opcode .../>
                </opcodes>
                <keywords>
                    <keyword .../>
                </keywords>
                <filters>
                    <filter .../>
                </filters>
                <maps>
                    <valueMap ...>
                        <map .../>
                    </valueMap>
                    <bitMap ...>
                        <map .../>
                    </bitMap>
                </maps>
                <templates>
                    <template ...>
                        <data .../>
                        <UserData>
                            <!-- valid XML fragment -->
                        </UserData>
                    </template>
                </templates>
                <events>
                    <event .../>
                </events>
            </provider>
        </events>
    </instrumentation>

    <localization>
        <resources ...>
            <stringTable>
                <string .../>
            </stringTable>
        </resources>
    </localization>

</instrumentationManifest>

계측 매니페스트 작성

피드백

피드백

추가 리소스