Coherenceのレポート機能には、Coherence JMXデータソースに存在する任意の情報をテキスト・ファイルに記録できる高度な問合せ定義が用意されています。カスタム・レポートを作成した後、それをレポート・バッチに組み込み、ReportControl
MBeanで指定された時間間隔で実行します。レポート構成XMLファイルの詳細は、coherence.jar
ファイルにパッケージ化されているreport-config.dtd
を参照してください。
レポート・ファイルを正しく生成するには、いくつかの要素を構成する必要があります。これらの要素の詳細は、表36-1を参照してください。
表36-1 出力ファイルを構成する要素
要素 | オプション/必須 | 説明 |
---|---|---|
<file-name> |
必須 |
レポート実行時に作成または更新するファイル名。詳細は、「file-name要素」を参照してください。 |
<delim> |
オプション |
レポートの列デリミタ。有効な値は、 |
<hide-headers> |
オプション |
ヘッダーをレポートに含めるかどうかを決定するブール要素。 |
この要素の値は、その前に配置される<report-path>
要素の出力パスを持ち、その場所にレポートが生成されます。Coherenceノードからこのパスにアクセスできない場合、ファイルは作成されません。
次の例では、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のデータを組み込むには、レポートに属性ソースを含む列を設定する必要があります。これは、レポートに組み込む最も一般的なアイテムです。
例36-1は、問合せパターンCoherence:type=Node,*
で取得されたRoleName
属性を組み込む方法を示しています。
ObjectName
のキーの値は、問合せパターンで返されたObjectNames
から取得できます。その後、この値をレポートに組み込むことができます。
例36-2は、問合せパターンCoherence:type=Node,*
で取得されたnodeId
キー部分を組み込む方法を示しています。
JMXの複合値を使用して、複合データ属性の一部をレポートに組み込むことができます。
例36-9は、問合せパターンjava.lang:type=GarbageCollector,*
で取得されたLastGCInfo
属性のstartTime
を組み込む方法を示しています。
JMX結合属性は、レポートで複数のMBean情報が要求される場合に必要になります。結合の作成時に考慮すべき重要な点は、主問合せ、結合問合せおよび外部キーを決定することです。主問合せには、レポートの適切な行数を返す問合せを指定する必要があります。結合問合せパターンでは、単一のMBeanを参照する必要があります。これにワイルド・カード(*
)を含めることはできません。外部キーは、結合問合せ文字列の作成に必要な主問合せの属性によって決定されます。
MBean間の結合を可能にするReporterの機能が列置換マクロです。列置換により、列の結果の値を文字列の一部として組み込むことができます。列置換マクロは、中カッコ{}
で囲まれた列ID属性です。Reporterでは循環参照をチェックしないため、循環が構成されていると実行時に失敗します。
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
キー部分であり、これをレポートに含める必要があります。このシナリオの構成を例36-4に示します。
レポートに組み込むことができるレポート・マクロは3つあります。
レポート時刻(report-time
): レポートが実行された日付と時刻です。この情報は時系列分析に有用です。
レポート・バッチ/カウント(report-count
): 同時実行された様々なレポートの情報を相互に関連付ける場合に使用される、long型の識別子です。
レポート・ノード(report-node
): 異なるノードで実行された同じレポートの情報を統合する場合、またはレポートから実行ノード情報を排除する場合に使用されます。
レポートに実行時刻を組み込むには:
例36-5 実行時刻のレポートへの組込み
<column id ="ReportTime"> <type>global</type> <name>{report-time}</name> <header>Report Time</header> </column>
レポート・バッチ/カウントを組み込むには:
例36-6 レポート・バッチ/カウントのレポートへの組込み
<column id="ReportBatch"> <type>global</type> <name>{report-count}</name> <header>batch</header> </column>
実行ノードを組み込むには:
レポート定数は、静的値またはレポート・パラメータに使用できます。これらの定数にはdouble型またはstring型の値を指定できます。これらは多くの場合、結果を特定のデータ・セットに制限するフィルタや計算で使用されます。
例36-8は、レポートにdouble型の定数1.0を含める方法を示しています。
例36-8 数値定数のレポートへの組込み
<column id ="One"> <type>constant</type> <header>Constant1</header> <data-type>double</data-type> <value>1.0</value> <hidden>true</hidden> </column>
例36-9は、レポートにstring型の定数dist-Employee
を含める方法を示しています。
問合せは、レポートに組み込まれる情報の基礎になるものです。各問合せには、問合せパターン、列参照およびオプションのフィルタ参照が含まれます。問合せパターンは、JMXのObjectName
問合せ文字列となる文字列です。この文字列では1つ以上のMBeanを返すことができます。列参照は、レポート定義ファイルの<columns>
セクションで定義する必要があります。フィルタ参照は、レポート・セクションの<filters>
セクションで定義する必要があります。
例36-10は、RoleName
とCoherenceServer
が等しいクラスタ内のすべてのNodeIDとRoleName
のリストを含める方法を示しています。
例36-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
があります。各複合フィルタは、フィルタ・パラメータを最初から最後まで評価してから、標準的なブール論理を適用します。複合フィルタの評価では、標準的な短絡論理が使用されます。評価の実行時、循環参照のチェックは行われません。循環参照が発生すると、実行時エラーとなります。
例36-11は、equals
フィルタの定義方法を示しています(RoleRef
およびStringRef
は定義済の列です)。
例36-11 レポートでのequalsフィルタの使用方法
<filters> <filter id="equals"> <type>equals</type> <params> <column-ref>RoleRef</column-ref> <column-ref>StringRef</column-ref> </params> </filter> </filters>
例36-12は、PacketsResent
の数がPacketsSent
より大きいものを判別するフィルタの定義方法を示しています(PacketsResent
およびPacketsSent
は有効な列参照であることを前提としています)。
例36-12 レポートでのgreaterフィルタの定義方法
<filters> <filter id="greaterRef"> <type>greater</type> <params> <column-ref>PacketsResent</column-ref> <column-ref>PacketsSent</column-ref> </params> </filter> </filters>
例36-13は、PacketsResent
の数がPacketsSent
より小さいものを判別するフィルタの定義方法を示しています(PacketsResent
およびPacketsSent
は有効な列参照であることを前提としています)。
例36-13 レポートでのlessフィルタの定義方法
<filters> <filter id="greaterRef"> <type>less</type> <params> <column-ref>PacketsResent</column-ref> <column-ref>PacketsSent</column-ref> </params> </filter> </filters>
例36-14は、and
フィルタの定義方法を示しています(すべてのcolumn-ref
値は有効であることを前提としています)。
例36-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>
例36-15は、or
フィルタの定義方法を示しています(すべてのcolumn-ref
値は有効であることを前提としています)。
例36-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>
例36-16は、not
equals
フィルタの定義方法を示しています(RoleRef
およびStringRef
は定義済の列です)。
Reporterの関数を使用して、レポートの同じ行内のデータ要素について数値計算を実行できます。サポートされる関数は、Add
、Subtract
、Multiply
およびDivide
です。関数列は、他の関数列へのパラメータとして組み込むこともできます。
例36-17は、2つの列(Attribute1
およびAttribute2
)を加算して、その結果を3番目の列(Addition
)に入力する方法を示しています。
例36-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>
例36-18は、ある列値(Attribute1
)から別の列値(Attribute2
)を減算して、その結果を3番目の列(Subtraction
)に入力する方法を示しています。
例36-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>
例36-19は、2つの列値(Attribute1
およびAttribute2
)を乗算して、その結果を3番目の列(Multiplication
)に入力する方法を示しています。
例36-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>
例36-20は、ある列値(Attribute1
)を別の列値(Attribute2
)で除算して、その結果を3番目の列(Division
)に入力する方法を示しています。すべての除算結果はDouble型のデータになります。
例36-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の集計機能を使用して、複数行を単一の値または行に集計することができます。表36-3は、使用可能な集計のタイプを示しています。
表36-3 Reporterの集計タイプ
タイプ | 説明 |
---|---|
avg |
列内のすべての値の平均値を計算します。 |
max |
列内のすべての値の最大値を返します。 |
min |
列内のすべての値の最小値を返します。 |
sum |
列内のすべての値を加算します。 |
size
列の値を合計します。
例36-21 列内の値の加算方法
<column id ="SumRef"> <type>function</type> <function-name>sum</function-name> <column-ref>size</column-ref>> <header>Sum</header> </column>
size
列の値を平均します。
例36-22 列内の平均値の計算方法
<column id ="AverageRef"> <type>function</type> <header>Average</header> <function-name>avg</function-name> <column-ref>size</column-ref>> </column>
size
列の最大値を求めます。
例36-23 列内の最大値を求める方法
<column id ="MaximumRef"> <type>function</type> <header>Maximum</header> <function-name>max</function-name> <column-ref>size</column-ref>> </column>
size
列の最小値を求めます。
Coherenceレポートの多くの数値属性は累積的に変化します。これらの値はMBeanでresetStatistics
操作を実行した場合のみリセットされます。統計をリセットせずにシステムの状態を確認するには、Reporterでデルタ関数を使用します。デルタ関数は、列の現在値から前の値を減算し、その差異を返します。
レポートの前の値は、Reporterクライアントのマップ内に保存されています。このマップは、デルタ・キーによってキー設定されています。デフォルトでは、デルタ・キーは属性のMBean名になります。ただし、MBeanとレポート内の行に1対1の関係が存在しない場合、またはMBean名がレポートの実行間で変更される可能性がある場合は、<params>
セクションにある列を使用してデルタ・キーが計算されます。
注意: デルタ関数の精度: デルタ関数は、レポートがレポート・バッチの一部として実行されている場合のみ正しく計算されます。 |
例36-25は、属性のデルタ計算を含める方法を示しています (PacketsSent
は定義済列であると仮定します)。
例36-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>
例36-26は、別のdelta
キーを使用して属性のデルタ計算を含める方法を示しています (PacketsSent
、NodeID
およびTimeStamp
は定義済列であると仮定します)。
例36-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>