23 カスタム・レポートの作成方法

Coherenceのレポート機能には、Coherence JMXデータソースに存在する任意の情報をテキスト・ファイルに記録できる高度な問合せ定義が用意されています。カスタム・レポートを作成した後、それをレポート・バッチに組み込み、ReportControl MBeanで指定された時間間隔で実行します。レポート・コンフィギュレーションXMLファイルの詳細は、coherence.jarファイルにパッケージ化されているreport-config.dtdを参照してください。

レポート・ファイルの構成

レポート・ファイルを正しく生成するには、いくつかの要素を構成する必要があります。それらの要素について表23-1で説明します。

表23-1 出力ファイルを構成する要素

要素	オプション/必須	説明
<file-name>	必須	レポート実行時に作成または更新するファイル名。詳細は、「file-name要素」を参照してください。
<delim>	オプション	レポートの列デリミタ。有効な値は、{tab}、{space}または印刷可能な文字です。デフォルト値は{tab}です。複数文字の文字列を指定すると、その文字列の最初の文字が使用されます。
<hide-headers>	オプション	ヘッダーをレポートに含めるかどうかを決定するブール要素。trueを指定すると、列ヘッダーとレポートの説明はファイルに含まれません。デフォルト値はfalseです。

file-name要素

この要素の値は、その前に配置される<report-path>要素の出力パスを持ち、その場所にレポートが生成されます。Coherenceノードからこのパスにアクセスできない場合、ファイルは作成されません。

file-nameマクロ

file-name要素で使用できる事前定義マクロがあります。これらのマクロを使用すると、生成されるファイル名に、ノード名、バッチ番号または日付を追加できます。

表23-2 file-name要素で使用できるマクロ

マクロ	説明
batch	バッチ識別子をレポートのファイル名に含めます。情報の保持期間が短い場合、またはRDBMSに頻繁にアップロードされる場合に使用します。
date	日付（YYYYMMDD形式）をレポートのファイル名に含めます。データを一定期間保持した後で破棄する場合によく使用されます。
node	ノードIDをファイル名に含めます。このコンフィギュレーション設定は、多くのノードで同じレポートを実行し、その出力ファイルを分析用に統合する場合に便利です。

file-nameマクロの例

次の例では、2009年1月1日にレポートを実行すると、ファイル20090101_network_status.txtが作成されます。ファイル名はレポートを実行するノードのシステム時間によって異なります。

<file-name>{{date}}_network_status.txt</file-name>

次の例では、ノード12でレポートを実行すると、ファイル00012_network_status.txtが作成されます。ノードIDは変わりやすいため、この方法でレポートを長期間保存することはお薦めしません。

<file-name>{node}_network_status.txt</file-name>

次の例では、21番目にレポートを実行すると、ファイル0000000021_network_status.txtが作成されます。バッチは一時的なものであるため、この方法でレポートを長期間保存することはお薦めしません。

<file-name>{batch}_network_status.txt</file-name>

データ列の指定

データ列のソースには、JMX属性、ObjectNameのキー部分、JMX複合属性、JMX結合属性、レポート・マクロおよびレポート定数を指定できます。

属性の組込み方法

問合せパターンで返されたMBeanのデータを組み込むには、レポートに属性ソースを含む列を設定する必要があります。これは、レポートに組み込む最も一般的なアイテムです。

例23-1は、問合せパターンCoherence:type=Node,*で取得されたRoleName属性を組み込む方法を示しています。

例23-1 問合せパターンで取得された属性の組込み

<column id = "RoleName">
  <type>attribute</type>
  <name>RoleName</name>
  <header>Role Name</header>
</column>

キー部分の組込み方法

ObjectNameのキーの値は、問合せパターンで返されたObjectNamesから取得できます。その後、この値をレポートに組み込むことができます。

例23-2は、問合せパターンCoherence:type=Node,*で取得されたnodeIdキー部分を組み込む方法を示しています。

例23-2 ObjectNameのキー部分のレポートへの組込み

<column id ="NodeId">
  <type>key</type>
  <name>nodeId</name>
  <header>Node Id</header>
</column>

複合属性情報の組込み方法

JMXの複合値を使用して、複合データ属性の一部をレポートに組み込むことができます。

例23-9は、問合せパターンjava.lang:type=GarbageCollector,*で取得されたLastGCInfo属性のstartTimeを組み込む方法を示しています。

例23-3 複合属性情報のレポートへの組込み

<column id="LastGCStart">
   <type>attribute</type>
   <name>LastGcInfo/startTime</name>
   <header>Last GC Start Time</header>
</column>

複数のMBean情報の組込み

JMX結合属性は、レポートで複数のMBean情報が要求される場合に必要になります。結合の作成時に考慮すべき重要な点は、主問合せ、結合問合せおよび外部キーを決定することです。主問合せには、レポートの適切な行数を返す問合せを指定する必要があります。結合問合せパターンでは、単一のMBeanを参照する必要があります。これにワイルド・カード（*）を含めることはできません。外部キーは、結合問合せ文字列の作成に必要な主問合せの属性によって決定されます。

MBean間の結合を可能にするReporterの機能が列置換マクロです。列置換により、列の結果の値を文字列の一部として組み込むことができます。列置換マクロは、中カッコ{}で囲まれた列ID属性です。Reporterでは循環参照をチェックしないため、循環が構成されていると実行時に失敗します。

複数のMBean情報を組み込む例

1つ以上のMBeanから情報を引き出してレポートに組み込むことができます。これには、MBean間にjoinが必要です。

注意: join属性の主な制限は、結合の結果は1つの値のみを持つ必要があるということです。

たとえば、レポートでCache MBean（Coherence:type=cache,*）のTotalGetsおよびNode MBean（Coherence:type=Node,*）のRoleNameが要求される場合は、join属性を使用する必要があります。

ほとんどのMBeanはCache MBeanから取得されるため、Coherence:type=Cache,*が主問合せとなり、RoleNameがjoin属性となります。この結合の外部キーは、Cache MBeanのnodeIdキー部分であり、これをレポートに含める必要があります。このシナリオの構成を例23-4に示します。

例23-4 複数のMBean情報のレポートへの組込み

<column id="RoleName">
   <type>attribute</type>
   <name>RoleName</name>
   <header>Role Name</header>
    <query>
       <pattern>Coherence:type=Node,nodeId={NodeFK}</pattern>
    </query>
</column>

<column id ="NodeFK">
  <type>key</type>
  <name>nodeId</name>
  <header>Node Id</header>
</column>

レポート・マクロの使用方法

レポートに組み込むことができるレポート・マクロは3つあります。

• レポート時刻（report-time）: レポートが実行された日付と時刻です。この情報は時系列分析に有用です。

• レポート・バッチ/カウント（report-count）: 同時実行された様々なレポートの情報を相互に関連付ける場合に使用される、long型の識別子です。

• レポート・ノード（report-node）: 異なるノードで実行された同じレポートの情報を統合する場合、またはレポートから実行ノード情報を排除する場合に使用されます。

レポートに実行時刻を組み込むには:

例23-5 実行時刻のレポートへの組込み

<column id ="ReportTime">
   <type>global</type>
   <name>{report-time}</name>
   <header>Report Time</header>
</column>

レポート・バッチ/カウントを組み込むには:

例23-6 レポート・バッチ/カウントのレポートへの組込み

<column id="ReportBatch">
  <type>global</type>
  <name>{report-count}</name>
  <header>batch</header>
</column>

実行ノードを組み込むには:

例23-7 実行ノードの組込み

<column id="ReportNode">
  <type>global</type>
  <name>{report-node}</name>
  <header>ExecNode</header>
  <hidden>true</hidden>
</column>

定数値の組込み方法

レポート定数は、静的値またはレポート・パラメータに使用できます。これらの定数にはdouble型またはstring型の値を指定できます。これらは多くの場合、結果を特定のデータ・セットに制限するフィルタや計算で使用されます。

例23-8は、レポートにdouble型の定数1.0を含める方法を示しています。

例23-8 数値定数のレポートへの組込み

<column id ="One">
  <type>constant</type>
  <header>Constant1</header>
  <data-type>double</data-type>
  <value>1.0</value>
  <hidden>true</hidden>
</column>

例23-9は、レポートにstring型の定数dist-Employeeを含める方法を示しています。

例23-9 文字列定数のレポートへの組込み

<column id ="EmployeeCacheName">
  <type>constant</type>
  <header>Employee Cache Name</header>
  <data-type>string</data-type>
  <value>dist-Employee</value>
  <hidden>true</hidden>
</column>

問合せのレポートへの組込み

問合せは、レポートに組み込まれる情報の基礎になるものです。各問合せには、問合せパターン、列参照およびオプションのフィルタ参照が含まれます。問合せパターンは、JMXのObjectName問合せ文字列となる文字列です。この文字列では1つ以上のMBeanを返すことができます。列参照は、レポート定義ファイルの<columns>セクションで定義する必要があります。フィルタ参照は、レポート・セクションの<filters>セクションで定義する必要があります。

例23-10は、RoleNameとCoherenceServerが等しいクラスタ内のすべてのNodeIDとRoleNamesのリストを含める方法を示しています。

例23-10 クラスタのNodeIDとRoleNameのリストのレポートへの組込み

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>
</filters>

<query>
   <pattern>Coherence:type=Node,*</pattern>
   <filter-ref>equalsRef</filter-ref>
</query>

<row>
  <column id ="NodeRef">
    <type>key</type>
    <name>nodeId</name>
    <header>Node Id</header>
  </column>

  <column id ="RoleRef">
    <name>RoleName</name>
    <header>Role</header>
  </column>

  <column id = "StringRef">
    <type>constant</type>
    <name>ConstString</name>
    <data-type>string</data-type>
    <value>CoherenceServer</value>
    <hidden>true</hidden>
  </column>

</row>

フィルタを使用したレポートの作成

フィルタを使用して、レポートに返されるデータを制限します。フィルタには、比較フィルタと複合フィルタがあります。比較フィルタは2つの列の結果を評価し、複合フィルタは1つまたは2つのフィルタのブール値の結果を評価します。比較フィルタには、equals、greaterおよびlessがあります。

複合フィルタのタイプには、and、orおよびnotがあります。各複合フィルタは、フィルタ・パラメータを最初から最後まで評価してから、標準的なブール論理を適用します。複合フィルタの評価では、標準的な短絡論理が使用されます。評価の実行時、循環参照のチェックは行われません。循環参照が発生すると、実行時エラーとなります。

例23-11は、equalsフィルタの定義方法を示しています（RoleRefおよびStringRefは定義済の列です）。

例23-11 レポートでのequalsフィルタの使用方法

<filters>
   <filter id="equals">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>
</filters>

例23-12は、PacketsResentの数がPacketsSentより大きいものを判別するフィルタの定義方法を示しています（PacketsResentおよびPacketsSentは有効な列参照であると仮定します）。

例23-12 レポートでのgreaterフィルタの定義方法

<filters>
   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>
</filters>

例23-13は、PacketsResentの数がPacketsSentより小さいものを判別するフィルタの定義方法を示しています（PacketsResentおよびPacketsSentは有効な列参照であると仮定します）。

例23-13 レポートでのlessフィルタの定義方法

<filters>
   <filter id="greaterRef">
     <type>less</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>
</filters>

例23-14は、andフィルタの定義方法を示しています（すべてのcolumn-ref値は有効であると仮定します）。

例23-14 レポートでのandフィルタの定義方法

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>

   <filter>
     <type>and</type>
     <params>
        <filter-ref>greaterRef</filter-ref>
        <filter-ref>equalsRef</filter-ref>
     <params>
   </filter>
</filters>

例23-15は、orフィルタの定義方法を示しています（すべてのcolumn-ref値は有効であると仮定します）。

例23-15 レポートでのorフィルタの定義方法

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>

   <filter>
     <type>or</type>
     <params>
        <filter-ref>greaterRef</filter-ref>
        <filter-ref>equalsRef</filter-ref>
     <params>
   </filter>
</filters>

例23-16は、not equalsフィルタの定義方法を示しています（RoleRefおよびStringRefは定義済の列です）。

例23-16 レポートでのnot equalsフィルタの定義方法

<filters>
   <filter id="equals">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id = "Not">
     <type>not</type>
     <params>
        <filter-ref>equals</filter-ref>
     </params>
   </filter>
</filters>

関数を使用したレポートの作成

Reporterの関数を使用して、レポートの同じ行内のデータ要素について数値計算を実行できます。サポートされる関数は、Add、Subtract、MultiplyおよびDivideです。関数列は、他の関数列へのパラメータとして組み込むこともできます。

関数の例

例23-17は、2つの列（Attribute1およびAttribute2）を加算して、その結果を3番目の列（Addition）に入力する方法を示しています。

例23-17 加算した列値の他列への組込み

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Addition">
  <type>function</type>
  <name>Add2Columns</name>
  <header>Adding Columns</header>
  <function-name>add</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

例23-18は、ある列値（Attribute1）から別の列値（Attribute2）を減算して、その結果を3番目の列（Subtraction）に入力する方法を示しています。

例23-18 減算した列値の他列への組込み

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Subtraction">
  <type>function</type>
  <name>Subtract2Columns</name>
  <header>Difference</header>
  <function-name>subtract</function-name>
  <params>

    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

例23-19は、2つの列値（Attribute1およびAttribute2）を乗算して、その結果を3番目の列（Multiplication）に入力する方法を示しています。

例23-19 乗算した列値の他列への組込み

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Multiplication">
  <type>function</type>
  <name>Multiply2Columns</name>
  <header>Multiply Columns</header>
  <function-name>multiply</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

例23-20は、ある列値（Attribute1）を別の列値（Attribute2）で除算して、その結果を3番目の列（Division）に入力する方法を示しています。すべての除算結果はDouble型のデータになります。

例23-20 除算した列値の他列への組込み

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Division">
  <type>function</type>
  <name>Dividing2Columns</name>
  <header>Division</header>
  <function-name>Divide</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

集計を使用したレポートの作成

Reporterの集計機能を使用して、複数行を単一の値または行に集計することができます。表23-3は、使用可能な集計のタイプについて説明しています。

表23-3 Reporterの集計タイプ

タイプ	説明
avg	列内のすべての値の平均値を計算します。
max	列内のすべての値の最大値を返します。
min	列内のすべての値の最小値を返します。
sum	列内のすべての値を加算します。

集計の例

size列の値を合計します。

例23-21 列内の値の加算方法

<column id ="SumRef">
   <type>function</type>
   <function-name>sum</function-name>
   <column-ref>size</column-ref>>
   <header>Sum</header>
</column>

size列の値を平均します。

例23-22 列内の平均値の計算方法

<column id ="AverageRef">
   <type>function</type>
   <header>Average</header>
   <function-name>avg</function-name>
   <column-ref>size</column-ref>>
</column>

size列の最大値を求めます。

例23-23 列内の最大値を求める方法

<column id ="MaximumRef">
   <type>function</type>
   <header>Maximum</header>
   <function-name>max</function-name>
   <column-ref>size</column-ref>>
</column>

size列の最小値を求めます。

例23-24 列内の最小値を求める方法

<column id ="MinimumRef">
   <type>function</type>
   <header>Minimum</header>
   <function-name>min</function-name>
   <column-ref>size</column-ref>>
</column>

デルタ関数の作成

Coherenceレポートの多くの数値属性は累積的に変化します。これらの値はMBeanでresetStatistics操作を実行した場合のみリセットされます。統計をリセットせずにシステムの状態を確認するには、Reporterでデルタ関数を使用します。デルタ関数は、列の現在値から前の値を減算し、その差異を返します。

レポートの前の値は、Reporterクライアントのマップ内に保存されています。このマップは、デルタ・キーによってキー設定されています。デフォルトでは、デルタ・キーは属性のMBean名になります。ただし、MBeanとレポート内の行に1対1の関係が存在しない場合、またはMBean名がレポートの実行間で変更される可能性がある場合は、<params>セクションにある列を使用してデルタ・キーが計算されます。

注意: デルタ関数の精度: デルタ関数は、レポートがレポート・バッチの一部として実行されている場合のみ正しく計算されます。

デルタ関数の例

例23-25は、属性のデルタ計算を含める方法を示しています（PacketsSentは定義済列であると仮定します）。

例23-25 属性のデルタ計算

<column id="DeltaPacketsSent">
  <type>function</type>
  <name>PacketsSent</name>
  <header>Delta Sent</header>
  <function-name>delta</function-name>
  <column-ref>PacketsSent</column-ref>
</column>

例23-26は、別のdeltaキーを使用して属性のデルタ計算を含める方法を示しています（PacketsSent、NodeIDおよびTimeStampは定義済列であると仮定します）。

例23-26 別のdeltaキーを使用した属性のデルタ計算

<column id="DeltaPacketsSent">
  <type>function</type>
  <name>PacketsSent</name>
  <header>Delta Sent</header>
  <function-name>delta</function-name>
  <column-ref>PacketsSent</column-ref>
  <params>
     <column-ref>NodeID</column-ref>
     <column-ref>TimeStamp</column-ref>
  </params>
</column>