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