レポートテンプレートの作成

レポートの作成と修正には、インタラクティブなレポートエディタ レポート（Report）>編集（Edit）を使用します。一般に、カスタムレポートを作成する場合、既存のレポートセクションを選択しパラメータを設定して新しいレポートを構築するというのが最も簡単な方法です（Traffic Sentinelのレポートのチュートリアルを参照してください）。

Traffic Sentinelのレポート機能では、XML（eXtensible Markup Language）で記述されたテンプレート文書を利用します。 XML文書によりレポートの構造（タイトル、見出し、セクションおよび本文）が定義されます。レポートテンプレートに含まれているスクリプトにより、クエリの作成、結果の処理、およびテーブルやチャートのレポートへの追加が行われます。

このチュートリアルでは、Traffic Sentinelに新しい機能を追加するレポートテンプレートを作成しインストールする方法について説明します。このチュートリアルの学習に入る前に、Traffic Sentinelのスクリプティング機能について紹介しているクエリのスクリプト化のチュートリアルを学習することをお勧めします。

XML

下の例はテンプレートの基本的要素を示しています。まず、以下の内容のexample.xmlという新規テンプレートファイルを作成します。

<template name="Tutorial" category="miscellaneous">
  <description>This report contains tutorial examples.</description>
  <section name="Echo">
    <description>Print the value of the input.</description>
    <usage>Enter a string and see it in a report section.</usage>
    <input name="echostr" type="string" label="String" />
    <script>
var r = new Report();
r.paragraph(echostr);
    </script>
  </section>
</template>

この簡単な例では、テンプレートの基本コンポーネントについて説明しています。各テンプレート（template）にはカテゴリー（category）が割り当てられ、名前（name）が付けられます。また、テンプレートについての説明（description）も設定されます。このテンプレートには1つのセクション（section）が含まれていて、このセクションの名前（name）と説明（description）が定義されます。また、このセクションには1つの入力（input）を使用するスクリプト（script）も含まれています。

レポート（Reports）>インストール（Install） ページを使用して、新規テンプレートファイルをインストールします。インストールすると、レポート（Report）>クエリ（Query） ページに表示されます。（ Miscellaneous カテゴリ配下のEcho クエリ）。

Echoセクションを選択すると、以下のフォームが表示されます。

Stringフィールドに任意の文字列を入力し、実行（Submit）ボタンをクリックするとテンプレートが実行されます。

スクリプティング

クエリのスクリプト化では、Traffic Sentinelの基本的なスクリプティングテクニックについて説明しています。一般に、新規スクリプトを作成する時には、レポート（Report）>スクリプト（Script）インターフェースを用いてスクリプトを実際に試してみるのが最良の方法です。基本的なクエリが正常に動作するようになったら、それをレポートテンプレートに組み込みます。

スクリプトをレポートテンプレートに追加する場合は、XML構文に含まれる一部の文字をXMLトークンと置き換ることにより、テンプレートをパースできるようにする必要があります。

">" を ">"にします。
"<" を "<"にします。
"&" を "&"にします。

たとえば、下のスクリプトをレポートテンプレートに組み込むためには、

for(var i = 0; i < 10; i++);

下のように書き換える必要があります。

for(var i = 0; i < 10; i++);

Traffic Sentinelは、レポートテンプレート用の追加のJavascriptファンクションを実装しています。

Report（レポート）

Report（レポート）クラスは、情報をレポートに追加するファンクションを提供します。

<section name="Heading and Paragaraph" >
  <description>Script demonstrating text output from script.</description>
  <script>
var r = new Report();
var date = r.getTime();
r.heading("Report Time");
r.paragraph("This report ran at " + date);
  </script>
</section>

この例では、getTimeメソッドを使用してスケジュールに基づくレポート実行予定時刻を取得し、headingおよびparagraphというファンクションを使用してレポートに本文と見出しを追加しています。レポートには、さらにテーブルやチャートも追加できます（以下のTable（テーブル）およびChart（チャート）の項の例を参照してください）。

Table（テーブル）

クエリのスクリプト化のチュートリアルでは、クエリの結果としてテーブルを取得する方法を紹介しています。下のスクリプトは、クエリの結果をレポートに追加する方法を示しています。

<section name="Top Byte Sources" >
  <description>Top sources of bytes.</description>
  <input name="category" type="historytrmx.key" value="ipsource" />
  <input name="interval" type="interval.history" value="today" />
  <script>
var r = new Report();
var q = Query.topN("historytrmx",category + ",bytes",null,interval,"bytes",5);
var t = q.run();
r.table(t);
  </script>
</section>

注記: このスクリプトはcategoryおよびintervalという2つのデータを入力します。これらの入力データのデフォルト値は、それぞれ"ipsource"および"today"です。

Tableクラスは、他のタイプの表形式データをレポートに追加するのにも役立ちます。

スイッチインターフェースに管理のためにつけられる名前は、スイッチの相互接続の様子を示すようになっているとします。下の例には、インターフェース名とトポロジー情報を比較するテーブルを作成し、不適切な名前がついているインターフェースを特定して表示する処理が含まれています。

<section name="Neighbor Table" >
  <description>Compare interface names with discovered topology.</description>
  <script>
var r = new Report();
var n = new Network();
var interfaces = n.interfaces();
var neighbors = n.neighborMap(interfaces);
var t = Table.create(
          ["sysName","ifName","neighbor sysName","neighbor ifName"],
          ["string" ,"string","string","string"]);
for(var i = 0; i &lt; interfaces.length; i++) {
   if(neighbors[i]) {
     var row = new Array();
     n.path = interfaces[i];
     row[0] = n.sysName();
     row[1] = n.ifName();
     n.path = neighbors[i];
     row[2] = n.sysName();
     row[3] = n.ifName();
     t.addRow(row);
   }
}
r.table(t);
  </script>
</section>

注記: このスクリプトは、隣接（Neighbor）エントリが存在するかどうかを調べてから、Networkオブジェクトを用いてインターフェースおよび隣接（Neighbor）のsysNameおよびifNameを検索し、新規の行を1行作ってテーブルに追加します。このスクリプトをさらに改良することにより、命名規則に基づいて正規表現を使用してインターフェース名から情報を抽出し、矛盾があれば自動的にそれを通知するようにできます。

Chart（チャート）

Chartクラスは、レポートに組み込むチャートを作成するために使用されます。

下の例は、クエリから得られる表形式の結果を用いてチャートを作成する方法を示しています。

<section name="Top IP Sources" >
  <description>Chart showing top IP sources by number of bytes.</description>
  <input name="includetable" label="Table" type="string" value="no">
    <option value="yes">Include</option>
    <option value="no" >Exclude</option>
  </input>
  <script>
var r = new Report();
var q = Query.topN("historytrmx","ipsource,bytes",null,"today","bytes",5);
var t = q.run();
var chart = Chart.singleSeries(
              "bar", "Top IP Sources",
              t, "IP Source", 0, "Bytes", 1);
r.chart(t);
if(includetable == "yes") r.table(t);
  </script>
</section>

次の例は、トレンド・チャートの構成を説明しています。

<section name="Total Traffic Trend" >
  <description>Chart showing total traffic over time.</description>
  <input name="interval" type="interval.history" value="today" />
  <input name="group" type="group" value="hour" />
  <script>
var r = Report.current();
var q = Query.trend("historytrmx","time,bytes",null,interval,group);
var t = q.run();
var chart = Chart.singleSeries(
              "trend", "Traffic Trend",
              t, null, 0, null, 1);
chart.stack = true;
r.chart(chart);
  </script>
</section>

Inputs(インプット)

<input /> タグは、レポートテンプレートの重要なパートです。Inputs は、スクリプトをインタラクティブ・クエリで使用することや、スケジュールレポートで使用できるよう調整することを可能にします。

input は、以下の属性を持ちます。：

name javascript内で生成される変数の名称。
type 変数のタイプ (下を参照).
label 入力フィールドのラベルとして形式上使われるユーザ・フレンドリーな名称。
value 変数のデフォルト値。
required デフォルトでは、全ての inputs は、スクリプトが実行される前に、用意する必要があります。required に、"false"を設定することで、その入力をオプショナル（選択）形式にします。

全ての input には、少なくとも、name と type は必要です。

もし、input で、一覧の形式を示す場合は(例；規定の値のセットのひとつのみを持つ)、<option> 句を使うことができます。(まず、 chart の例を参照して下さい。).

もし、input がオプショナル(例： request&eq;"false")の場合、スクリプトは、変数が存在すると仮定してはいけません。以下の一節は、どのようにして、オプショナル・インプットの存在をテストするかを示しています。

<input name="height" type="integer" />
<script>
var h = 100;
if(typeof(height) != 'undefined') h = height;

Inputのtypeは、変数のチェックに使用され、それらが正しいかを確認します。input 値がフォーム内に入力された時、それらはチェックされ、もし入力に不正値があればユーザに通知されます。さらに、inputのtypeは、入力フィールドに入力された値が、提供されている共通のオプションとして適切かをﾕｰｻﾞに支援するのに使用されます。

以下の types が定義されています。：

string ストリング(string）を許可。
integer 正の整数(positive integer)あるいは、ゼロを許可。
address アドレスを許可。Addressは、さらに、付加されたアドレス・タイプにより制限を受けます(例： address.ip は、IPアドレスのみを許可)。
subnet サブネット(CIDR表記で指定) を、許可。
protocol プロトコル(例：TCP:80)を許可。もし、特定のプロトコルタイプの入力を制限したいのであれば、付加されたtypeによって、さらに制限することができます(例： protocol.TCP は、TCP プロトコルのみを許可)。
agent エージェントアドレス（agent address）を許可。
interface スイッチ／ルーター・ポート（switch/router port）を許可。
path ネットワークの部分を特定するための、allows site>zone>group>agent 形式のパス（path）を許可。
view view input は、database viewから、属性名を取得するのに使用されます。view input は、常に view name (例：view.historytrmx or view.rttraffic)で修飾される必要があります。オプションとして、key や value (例：view.historytrmx.key)で修飾することもできます。
filter filter inputは、クエリ内で適用される演算子によるフィルター表現を取得するのに使用されます。filter input は、常に view name (例：filter.historytrmx)で修飾される必要があります。
interval クエリ内で期間（interval）として指定できる、経過した時間(例："today")。
group トレンド・クエリ内で使用される時間のグループ（grouping）(例："hour").

typeの末尾が [] で終了する場合、指定されたタイプの値のコンマ区切りのリストを許可します。(例： view.rttraffic.key[])。

レポートスクリプトの開発

レポート(Report)>スクリプト(Script) ツールは、レポート用の新しいスクリプトを作成するために便利な方法です。もし、スクリプト内のレポート・オブジェクトを作成し、それに見出し(headings)、段落(paragraph)、テーブル（table)、チャート（chart)を追加すれば、結果をプレビューすることが可能です。

以下のサンプル・スクリプトをカット＆ペーストして、レポート（Report）>スクリプト（Script） フォーム内で、実行してください。：

var r = new Report();
var q = Query.topN("historytrmx","ipsource,bytes",null,"today","bytes",5);
var t = q.run();
var chart = Chart.singleSeries(
              "bar", "Top IP Sources",
              t, "IP Source", 0, "Bytes", 1);
r.chart(chart);
println("done");

スクリプトを実行すると、結果として"done"の表示を見ることができるはずです。追加のボタンとして、PDFやHTMLでは、その形式のレポート出力を表示します。XMLボタンは、スクリプトを含むXMLレポート・テンプレートを生成します。単純に、レポート内に含まれているスクリプトをカット＆ペーストして、新たなクエリの開発に役立てることもできます。

スクリプト内のprint()やprintln()ステートメントを使用することは、デバックするのに有効で、かつ、レポートの結果に悪影響を及ぼすようなことはありません。

レポート テンプレートの作成