My friends, my life, my style - James S.F. Hsieh

10/27/2009

How to integrate ETW

要建立一個 Manifest-based ETW Provider 需要數個動作:
  1. 定義 Instrumentation Manifest 來描述 ETW Provider
  2. 根據 Manifest 的定義實作對應的 ETW Provider 於 AP 中
使用 ETW Provider 需要數個動作:
  1. 註冊 ETW Provider 對應的 Instrumentation Manifest 
  2. 利用 ETW Controller 啟動  ETW Provider
以下是定義一個 ETW Provider 的模型, 該結構會被定義在 Instrumentation Manifest 的 XML 中, 簡單來說一個 Instrumentation Manifest 可以記錄多個 ETW Provider, 每個 ETW Provider 都會有獨自的 GUID 做為識別, 每個 Provider 可以有多種 Event 並且利用 Event ID 識別, 每個 Event 可以參考一種 Template 來描述該 Event 想要收集的資料格式, 所以 Template 是用來說明這些資料是怎麼被 "解釋", 這就是 data-driven 的一種架構. 要如何撰寫 Instrumentation Manifest 詳細可以參考 "Writing an Instrumentation Manifest", 一個比較簡單的方法是使用 Manifest Generator (ecmangen.exe: A GUI that guides you through creating a manifest from scratch without ever having to use XML tags.) 這個 tool 來產生對應的 XML 與 GUID, 你可以在 Platform SDK 的 Bin 目錄中找到這個好用的 tool. 





產生這些 XML 其實並不一定是必要的, 因為 ETW  Controller 只需要 GUID 就可以開啟對應的 ETW  Provider, 而  ETW Provider 在寫入資料時會傳入對應的 data length, 所以 logging data 的 serialization 就不是什麼問題, 但是如果 ETW Consumer 如果希望能夠 "解釋" logging data 的內容, 那這個 XML 就是必要的, 因為, "解釋" 這些內容必須要反查 Template 並且利用 Trace Data Helper (TDH) API 來 Unserialization 記錄的資料.


在來, 我們可以利用剛剛撰寫的 XML 與 Message Compiler (mc.exe: A command line utility used to compile instrumentation manifests and message text files.) 產生相對應的 Metadata,  該 tool 可以在 Platform SDK 的 Bin 目錄中找到, 並且可以輕易的整合進 Pre-build 的 script 中, MC會產生三個檔案:
  1. H File:  C/C++ 對應的 GUID 與 EVENT_DESCRIPTOR 宣告
  2. RC File: 用於指定內嵌 ETW template metadata 的 resource 宣告
  3. BIN File: ETW template metadata 做為 TDH API 反查之用
BIN File 必須在 link 的時候跟著內嵌進 binary file 當中.





如何產生 Event 呢? 這個部分我就不在這裡描述, 詳細可以參考 "Writing Manifest-based Events", 我在 DOL 函式庫中, 輕巧了使用 functor template 包裝了 ETW Provider, 讓產生 event 可簡單的像呼叫一個函數一樣容易, 宣告的時候只需要描述對應的函數型態就會自動推倒出對應的 template function, 有機會在跟大家分享.
DETWEventPublisher<DOL_TYPELIST_2(INT, const WCHAR*)> event(guid); // define
event(1, L"event message"); // Fire event

值得注意的是, 在 XML 當中 Decoding file locations 這個欄位是用來描述一個 binary file 的路徑, 該 binary file 內嵌的 resource 包含了 ETW template metadata, 目的是做為 TDH 反查之用, 由於 TDH API 在網路上的資訊相當的少, 所以詳細的運作方式就不清楚了. 麻煩的是這個路徑跟 AP 佈署的路徑有關, 為了彈性, 該路徑必須在佈署之後才能確定, 所以我們必須在佈署之後才產生出修正路徑的 XML, 在利用 wevtutil.exe (A command line utility used primarily to register your provider on the computer. You can also use it to get metadata information about the provider, its events, and the channels to which it logs events, and to query events from a channel or log file.) 來註冊 Instrumentation Manifest XML.


最後, 由於已經註冊了該 XML, 所以 ETW Controller:  logman.exe 或是 xperf.exe 都可以查詢到這些 ETW Provider 並且可以直接啟動.