イベントの構成要素

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

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

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

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

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

次回予告

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

鷲ノ巣

C# とか PowerShell とか。当ブログの記事は（特に公開直後は）頻繁に改定される場合があることをご了承ください。