この章では、カスタム・レポート定義ファイルとカスタム・レポート・グループ構成ファイルを作成する方法について説明します。
この章には次の項が含まれます:
カスタム・レポートは、Coherence MBeanサーバー・ドメイン(カスタムMBeanを含む)にあるすべてのMBeanに基づいて作成できます。これにより、クラスタ実装に固有の有効な方法で異なる管理データを組み合せることができます。カスタム・レポートは、本番用のトラブルシューティングと計画を行う際に傾向を監視するデータを関連付けるため、通常はテスト中に作成されます。
カスタム・レポートの作成前に、coherence.jar
ライブラリの/reports
ディレクトリにある、事前定義されたレポーティング構成ファイルを抽出します。カスタム・レポートの作成の学習時にはこのファイルが参照されます。また、このファイルは開始ポイントとして使用し、必要に応じて変更できます。
レポート構成ファイル
JMXレポーティングでは、レポート構成ファイルおよびレポート・グループ構成ファイルという、2種類の構成ファイルを利用します。
レポート構成ファイル: レポート構成ファイルを使用して実行時にレポートを作成します。これには、レポート名のほか、抽出が必要なMBeanデータやデータの編成方法が含まれています。各レポートには、対応するレポート構成ファイルが存在します。レポート構成ファイルは、coherence.jar
ライブラリのルート・ディレクトリにパッケージ化されているcoherence-report-config.xsd
スキーマ・ファイルで定義されるXMLドキュメントです。
レポート・グループ構成ファイル: レポート・グループ構成ファイルを使用して実行時に生成されるレポートを構成します。これには、各レポート構成ファイルの名前と場所、レポートを保存する出力ディレクトリ、さらにはレポートのリフレッシュ頻度が含まれています。レポート・グループ構成ファイルは必要に応じて作成できます。レポート・グループ構成ファイルは、coherence.jar
ライブラリのルート・ディレクトリにパッケージ化されているcoherence-report-group-config.xsd
スキーマ・ファイルで定義されているXMLドキュメントです。
この項の各トピックでは、coherence-report-config.xsd
ファイルに基づいてレポート構成ファイルを作成する方法について説明します。レポート・ファイル構成要素の詳細は、付録B「レポート・ファイル構成リファレンス」を参照してください。
この項には、次のトピックが含まれます:
レポート・ファイルを正しく生成するには、いくつかの要素を構成する必要があります。これらの要素の詳細は、表5-1を参照してください。
表5-1 出力ファイルを構成する要素
要素 | オプション/ 必須 |
説明 |
---|---|---|
<file-name> |
必須 |
レポート実行時に作成または更新するファイル名。 |
<delim> |
オプション |
レポートの列デリミタ。有効な値は、 |
<hide-headers> |
オプション |
ヘッダーをレポートに含めるかどうかを決定するブール要素。 |
file-name
要素で使用できる事前定義マクロがあります。これらのマクロを使用すると、生成されるファイル名に、メンバー名、バッチ番号または日付を追加できます。
次の例では、2009年1月1日の12時に、ファイル200901012_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>{sequence}_network_status.txt</file-name>
データ列のソースには、JMX属性、ObjectName
のキー部分、JMX複合属性、JMX結合属性、レポート・マクロおよびレポート定数を指定できます。
問合せパターンで返されたMBeanのデータを組み込むには、レポートに属性ソースを含む列を設定する必要があります。これは、レポートに組み込む最も一般的なアイテムです。
例5-1は、問合せパターンCoherence:type=Node,*
で取得されたRoleName
属性を組み込む方法を示しています。
ObjectName
のキーの値は、問合せパターンで返されたObjectNames
から取得できます。その後、この値をレポートに組み込むことができます。
例5-2は、問合せパターンCoherence:type=Node,*
で取得されたnodeId
キー部分を組み込む方法を示しています。
JMXの複合値を使用して、複合データ属性の一部をレポートに組み込みます。
例5-9は、問合せパターンjava.lang:type=GarbageCollector,*
で取得されたLastGCInfo
属性のstartTime
を組み込む方法を示しています。
JMX結合属性は、レポートで複数のMBean情報が要求される場合に必要になります。結合の作成時に考慮すべき重要な点は、主問合せ、結合問合せおよび外部キーを決定することです。主問合せには、レポートの適切な行数を返す問合せを指定する必要があります。結合問合せパターンでは、単一のMBeanを参照する必要があります。これにワイルド・カード(*
)を含めることはできません。外部キーは、結合問合せ文字列の作成に必要な主問合せの属性によって決定されます。
MBean間の結合を可能にするレポータの機能が列置換マクロです。列置換により、列の結果の値を文字列の一部として組み込むことができます。列置換マクロは、中カッコ{}
で囲まれた列ID属性です。レポータでは循環参照をチェックしないため、循環が構成されていると実行時に失敗します。
複数の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
キー部分であり、これをレポートに含める必要があります。このシナリオの構成を例5-4に示します。
レポートに組み込むことができるレポート・マクロは3つあります。
レポート時刻(report-time
) - レポートが実行された日付と時刻です。この情報は時系列分析に有用です。
レポート・バッチ/カウント(report-count
) - 同時実行された様々なレポートの情報を相互に関連付ける場合に使用される、long型の識別子です。
レポーティング・メンバー(report-node
) - 異なるメンバーで実行された同じレポートの情報を統合する場合、またはレポートから実行メンバー情報を排除する場合に使用されます。
レポートに実行時刻を組み込むには:
例5-5 実行時刻のレポートへの組込み
<column id ="ReportTime"> <type>global</type> <name>{report-time}</name> <header>Report Time</header> </column>
レポート・バッチ/カウントを組み込むには:
例5-6 レポート・バッチ/カウントのレポートへの組込み
<column id="ReportBatch"> <type>global</type> <name>{report-count}</name> <header>batch</header> </column>
実行メンバーを組み込むには:
レポート定数は、静的値またはレポート・パラメータのいずれかに使用されます。これらの定数にはdouble型またはstring型の値を指定できます。これらは多くの場合、結果を特定のデータ・セットに制限するフィルタや計算で使用されます。
例5-8は、レポートにdouble型の定数1.0を含める方法を示しています。
例5-8 数値定数のレポートへの組込み
<column id ="One"> <type>constant</type> <header>Constant1</header> <hidden>true</hidden> <data-type>double</data-type> <value>1.0</value> </column>
例5-9は、レポートにstring型の定数dist-Employee
を含める方法を示しています。
問合せは、レポートに組み込まれる情報の基礎になるものです。各問合せには、問合せパターン、列参照およびオプションのフィルタ参照が含まれます。問合せパターンは、JMXのObjectName
問合せ文字列となる文字列です。この文字列では1つ以上のMBeanを返すことができます。列参照は、レポート定義ファイルの<columns>
セクションで定義する必要があります。フィルタ参照は、レポート・セクションの<filters>
セクションで定義する必要があります。
例5-10は、RoleName
とCoherenceServer
が等しいクラスタ内のすべてのノードIDとRoleName
のリストを含める方法を示しています。
例5-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> <hidden>true</hidden> <data-type>string</data-type> <value>CoherenceServer</value> </column> </row>
フィルタを使用して、レポートに返されるデータを制限します。フィルタには、比較フィルタと複合フィルタがあります。比較フィルタは2つの列の結果を評価し、複合フィルタは1つまたは2つのフィルタのブール値の結果を評価します。比較フィルタには、equals
、greater
およびless
があります。
複合フィルタのタイプには、and
、or
およびnot
があります。各複合フィルタは、フィルタ・パラメータを最初から最後まで評価してから、標準的なブール論理を適用します。複合フィルタの評価では、標準的な短絡論理が使用されます。評価の実行時、循環参照のチェックは行われません。循環参照が発生した場合は、ランタイム・エラーが作成されます。
例5-11は、equals
フィルタの定義方法を示しています(RoleRef
およびStringRef
は定義済の列です)。
例5-11 レポートでのequalsフィルタの使用方法
<filters> <filter id="equals"> <type>equals</type> <params> <column-ref>RoleRef</column-ref> <column-ref>StringRef</column-ref> </params> </filter> </filters>
例5-12は、PacketsResent
の数がPacketsSent
より大きいものを判別するフィルタの定義方法を示しています(PacketsResent
およびPacketsSent
は有効な列参照であることを前提としています)。
例5-12 レポートでのgreaterフィルタの定義方法
<filters> <filter id="greaterRef"> <type>greater</type> <params> <column-ref>PacketsResent</column-ref> <column-ref>PacketsSent</column-ref> </params> </filter> </filters>
例5-13は、PacketsResent
の数がPacketsSent
より小さいものを判別するフィルタの定義方法を示しています(PacketsResent
およびPacketsSent
は有効な列参照であることを前提としています)。
例5-13 レポートでのlessフィルタの定義方法
<filters> <filter id="greaterRef"> <type>less</type> <params> <column-ref>PacketsResent</column-ref> <column-ref>PacketsSent</column-ref> </params> </filter> </filters>
例5-14は、and
フィルタの定義方法を示しています(すべてのcolumn-ref
値は有効であることを前提としています)。
例5-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>
例5-15は、or
フィルタの定義方法を示しています(すべてのcolumn-ref
値は有効であることを前提としています)。
例5-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>
例5-16は、not
equals
フィルタの定義方法を示しています(RoleRef
およびStringRef
は定義済の列です)。
レポータの関数を使用して、レポートの同じ行内のデータ要素について数値計算を実行できます。サポートされる関数は、Add
、Subtract
、Multiply
およびDivide
です。関数列は、他の関数列へのパラメータとして組み込むこともできます。
例5-17は、2つの列(Attribute1
およびAttribute2
)を加算して、その結果を3番目の列(Addition
)に入力する方法を示しています。
例5-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>
例5-18は、ある列値(Attribute1
)から別の列値(Attribute2
)を減算して、その結果を3番目の列(Subtraction
)に入力する方法を示しています。
例5-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>
例5-19は、2つの列値(Attribute1
およびAttribute2
)を乗算して、その結果を3番目の列(Multiplication
)に入力する方法を示しています。
例5-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>
例5-20は、ある列値(Attribute1
)を別の列値(Attribute2
)で除算して、その結果を3番目の列(Division
)に入力する方法を示しています。すべての除算結果はDouble型のデータになります。
例5-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>
レポータの集計機能を使用して、複数行を単一の値または行に集計することができます。表5-3は、使用可能な集計のタイプを示しています。
表5-3 レポータの集計タイプ
型 | 説明 |
---|---|
avg |
列内のすべての値の平均値を計算します。 |
max |
列内のすべての値の最大値を返します。 |
min |
列内のすべての値の最小値を返します。 |
sum |
列内のすべての値を加算します。 |
size
列の値を合計します。
例5-21 列内の値の加算方法
<column id ="SumRef"> <type>function</type> <column-ref>size</column-ref>> <function-name>sum</function-name> <header>Sum</header> </column>
size
列の値を平均します。
例5-22 列内の平均値の計算方法
<column id ="AverageRef"> <type>function</type> <header>Average</header> <column-ref>size</column-ref> <function-name>avg</function-name> </column>
size
列の最大値を求めます。
例5-23 列内の最大値を求める方法
<column id ="MaximumRef"> <type>function</type> <header>Maximum</header> <column-ref>size</column-ref> <function-name>max</function-name> </column>
size
列の最小値を求めます。
Coherenceレポートの多くの数値属性は累積的に変化します。これらの値はMBeanでresetStatistics
操作を実行した場合のみリセットされます。統計をリセットせずにシステムの状態を確認するために、レポータはデルタ関数を使用します。デルタ関数は、列の現在値から前の値を減算し、その差異を返します。
レポートの前の値は、レポータ・クライアントのマップ内に保存されています。このマップは、デルタ・キーによってキー設定されています。デフォルトでは、デルタ・キーは属性のMBean名になります。ただし、MBeanとレポート内の行に1対1の関係が存在しない場合、またはMBean名がレポートの実行間で変更される可能性がある場合は、<params>
セクションにある列を使用してデルタ・キーが計算されます。
注意: デルタ関数の精度: デルタ関数は、レポートがレポート・バッチの一部として実行されている場合のみ正しく計算されます。 |
例5-25は、属性のデルタ計算を含める方法を示しています(PacketsSent
は定義済列であると仮定します)。
例5-25 属性のデルタ計算
<column id="DeltaPacketsSent"> <type>function</type> <name>PacketsSent</name> <header>Delta Sent</header> <column-ref>PacketsSent</column-ref> <function-name>delta</function-name> </column>
例5-26は、別のdelta
キーを使用して属性のデルタ計算を含める方法を示しています(PacketsSent
、NodeID
およびTimeStamp
は定義済列であると仮定します)。
例5-26 別のdeltaキーを使用した属性のデルタ計算
<column id="DeltaPacketsSent"> <type>function</type> <name>PacketsSent</name> <header>Delta Sent</header> <column-ref>PacketsSent</column-ref> <function-name>delta</function-name> <params> <column-ref>NodeID</column-ref> <column-ref>TimeStamp</column-ref> </params> </column>
この項の各トピックでは、coherence-report-config.xsd
ファイルに基づいてレポート・グループ構成ファイルを作成する方法について説明します。この構成ファイルを実行時に使用することで、生成されるレポートの種類、レポートのリフレッシュ回数、さらにはレポートの保存場所が決定されます。1つのレポートを異なるパラメータで使用する場合は、それらのパラメータも構成します。レポート・グループ構成要素の詳細は、付録C「レポート・グループ構成リファレンス」を参照してください。
この項には、次のトピックが含まれます:
<frequency>
要素でレポートのリフレッシュ頻度を指定します。実行間隔には適切な値を選択することが重要です。実行間隔が短かすぎると、レポータは膨大な量のデータを生成し、ディスク領域が著しく消費される可能性があります。実行間隔が長すぎると、十分な情報が生成されません。値は、秒(s
)または分(m
)単位のいずれかで入力します。次に例を示します。
<?xml version="1.0"?> <report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/ coherence-report-group-config coherence-report-group-config.xsd"> <frequency>5m</frequency> ...
<ouput-directory>
要素は、レポートの保存先のディレクトリ・パスを指定します。このディレクトリ・パスは、レポート構成ファイルで定義されている出力ファイル名の前に追加されます。「レポートの一般的な特性の指定」を参照してください。メンバーを実行するユーザー名には、このパスに対する読取り/書込みアクセスを付与する必要があります。このパスは、クラスタ・メンバーが開始されたディレクトリ(./
)に対して絶対または相対にできます。次の例では、レポートを/output
ディレクトリに保存します。
<?xml version="1.0"?> <report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/ coherence-report-group-config coherence-report-group-config.xsd"> <frequency>5m</frequency> <output-directory>/output</output-directory> ...
<report-list>
要素は、任意の数のレポート構成ファイルの名前と場所を指定します。パスには、ファイルまたはURLを含められます。レポート構成ファイルを入力するには、<report-config>
要素内に<location>
要素を追加します。次に例を示します。
<?xml version="1.0"?> <report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/ coherence-report-group-config coherence-report-group-config.xsd"> <frequency>5m</frequency> <output-directory>/output</output-directory> <report-list> <report-config> <location>/config/myReport.xml</location> </report-config> <report-config> <location>config/aSecondReport.xml</location> </report-config> </report-list> </report-group>
生成するカスタム・レポートを構成するには、JMXレポーティングを有効化し、レポータがカスタム・レポート・グループ構成ファイルを使用するよう構成する必要があります。JMXレポーティングの有効化の詳細は、「クラスタ・メンバーでのJMXレポーティングの有効化」を参照してください。
レポータがカスタム・レポート・グループ構成ファイルを使用するように構成するには、オペレーション・オーバーライド・ファイルを編集し、<レポータ>
要素内に、カスタム・レポート・グループ構成ファイルの場所に設定した<configuration>
要素を追加します。次の例では、JMXレポーティングを有効化して、カスタム・レポート・グループ構成ファイルを設定しています。
<?xml version='1.0'?> <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config" xsi:schemaLocation="http://xmlns.oracle.com/coherence/ coherence-operational-config coherence-operational-config.xsd"> <management-config> <reporter> <configuration system-property="tangosol.coherence.management.report.configuration"> my-report-group.xml</configuration> <autostart system-property="tangosol.coherence.management.report.autostart">true </autostart> </reporter> </management-config> </coherence>
tangosol.coherence.management.report.autostart
およびtangosol.coherence.management.report.configuration
のシステム・プロパティを使用してJMXレポーティングを有効化し、オペレーション・オーバーライド・ファイルを使用するかわりに、レポート・グループ構成ファイルを構成します。次に例を示します。
-Dtangosol.coherence.management.report.autostart=true -Dtangosol.coherence.management.report.configuration=my-report-group.xml