読者です 読者をやめる 読者になる 読者になる

イベントの構成要素

ETW Win32

なかなかコードが書き始まりませんが、もう少しお付き合いください。

マニフェストをもう少し俯瞰する

前回は、プロバイダー マニフェストについて紹介し、スキーマを俯瞰する方法を示しました。
今回は、もう少しマニフェストの中身を見て行きましょう。
画像は見切れてしまいましたが、マニフェストの主だった要素の階層を大まかに表すと、こんな感じになります。

  • instrumentationManifest
    • instrumentation
      • events
        • provider
          • channels
            • channel
          • levels
            • level
          • tasks
            • task
              • opcodes
                • opcode
          • opcodes
            • opcode
          • keywords
            • keyword
          • maps
            • valueMap
              • map
            • bitMap
              • map
          • templates
            • template
              • data
              • struct
                • data
              • UserData
          • events
            • event
          • filters
            • filter
    • localization
      • resources
        • stringTable
          • string

主役の要素が provider だというのはお分かりだと思います。
その下に、channel、level、task、opcode、keyword、template、event といった要素があります。

とりわけ重要なのは event 要素です。これが、プロバイダーが発行するイベントのメタデータを表します。
provider 配下の event と filter 以外の要素は、event 要素から参照され、イベント定義の一部を成します。
filter に関しては現時点で調査不足ですが、イベントをフィルタリングするのに利用できるフィルターを、あらかじめプロバイダーが定義しておくことができるものかと思われます。

localization 要素以下は、イベントの多言語対応に使用します。

イベントの詳細

では、event 要素の属性を見てみましょう。event 要素はスキーマでは EventDefinitionType という型で表現されます。

以下のような属性がありますね。

  • channel
  • keyword
  • level
  • message
  • opcode
  • task
  • template
  • symbol
  • value
  • version
  • notLogged

大部分の属性が provider 要素の子要素と対応しているのがわかります。
こうした属性が、イベントのメタデータを表します。

channel

channel は、イベントのまとまりを表します。
イベント ビューアーで言うと、左側のツリーの末端の要素、つまり、フォルダーでないものがチャンネルに相当します。

チャンネルには 4 つのタイプがあります。

  • Admin
  • Operational
  • Analytic
  • Debug

大雑把に言うと、上の方が万人向けで、下の方が情報が細かくなります。
Analytic と Debug は情報量が膨大になるため、デフォルトでは記録されません。

value と version

value はイベントの識別子、ID です。
それぞれのイベントに一意な識別子を振ります。

version は、イベントの表す事象は同じだけれど、その属性が変わったなどの場合にインクリメントします。
value と version の組み合わせで、時間が経ってもイベントが一意に識別されます。

symbol

symbol はイベントにつける名前です。
これは表には出ませんが、プロバイダーを作る時にソースコード上で使用する名前になります。

level

イベントにはレベルがあります。大体どのロギング フレームワークにもレベルという概念はありますね。
Windows であらかじめ定義されているものの他に、level 要素を使って自分で定義することができます。

あらかじめ定義されているレベルは以下の通りです。
これは winmeta.xml に書かれています。

内容
1 Critical
2 Error
3 Warning
4 Informational
5 Verbose

task と opcode

task はイベントの大分類、opcode は小分類だと思っておけばよいと思います。それぞれ、task 要素、opcode 要素で定義します。

opcode には task に属するものと、属さないものがあります。

Defining Tasks and Opcodes というページでは、task は(ネットワークとかデータベースというような)コンポーネントを表し、opcode は(コンポーネントがネットワークならば、send とか receive というような)オペレーションを表すとされています。

しかしながら、そのすぐ下にあるサンプル コードでは、task として Connect と Disconnect というのが挙げられています。これはコンポーネントと言うよりはオペレーションに見えます。
まぁそういうわけで、これらの使い方については、あまりカッチリとした指針は無いのかなと思います。

keyword

ブログで言うところのタグみたいなものです。
これまで見てきた level や task や opcode は 1 つのイベントにつき 1 つしか設定できませんが、keyword は 1 つのイベントに複数設定することができます。

message

イベントの内容を説明するローカライズされたメッセージです。

template

イベントのデータの形式を表します。template 要素で定義します。

イベント ビューアーでイベントを見るときに、「詳細」タブを開くと、「System」と「EventData」とか「UserData」とかいうグループに分かれていると思います。
f:id:aetos382:20140925182743p:plain

これまで見てきた level とか task とか opcode とか keyword とかは System の方に入るメタデータです。
一方で、EventData とか UserData といった要素に格納されるのが、イベントのデータになります。
template は、そのイベントデータの形式を決めます。
たとえばこの画像であれば、2 つの Data 要素がありますが、これが template が決めたデータ構造というわけです。

notLogged

このイベントがもはや使用されないということを表します。

次回予告

今度こそ、マニフェストを書いて、プロバイダーを作りはじめます。