|
|
WebLogic 診断フレームワーク (WebLogic Diagnostic Framework : WLDF) のインスツルメンテーション コンポーネントは、BEA WebLogic Server® インスタンスおよびそのサーバ インスタンスで実行中のアプリケーションに診断コードを追加するためのメカニズムを提供します。WLDF のインスツルメンテーションで主要な機能は次のとおりです。
WLDF には、あらかじめ定義された診断モニタと診断アクションのライブラリが用意されています。また、アプリケーション スコープのカスタム モニタを作成し、診断コードが挿入されるアプリケーション内の位置をユーザが決めることもできます。
この節では、インスツルメンテーションの概念と用語について説明します。
実行可能なインスツルメンテーション サービスには、システム レベル (サーバおよびクラスタ) のものとアプリケーション レベルのものがあります。概念、サービス、コンフィグレーション オプション、および実装機能の多くは両者とも同じです。ただし、相違点もいくつかあります。それらについて、このマニュアルで説明します。「サーバ スコープ インスツルメンテーション」は、WebLogic Server インスタンスおよびクラスタ固有のインスツルメンテーションのコンフィグレーションと機能を指し、「アプリケーション スコープ インスツルメンテーション」は、WebLogic サーバにデプロイされているアプリケーション固有のコンフィグレーションと機能を指します。スコープは各モニタに組み込まれており、ユーザがモニタのスコープを変更することはできません。
サーバまたはクラスタ向けのサーバ スコープ インスツルメンテーションは、診断モジュールの一部として、DOMAIN_NAME/config/diagnostics ディレクトリにある XML コンフィグレーション ファイルでコンフィグレーションおよびデプロイされ、config.xml からリンクされています。
アプリケーション スコープ インスツルメンテーションも、診断モジュールとしてコンフィグレーションおよびデプロイされます。ただし、アプリケーション スコープの場合は、デプロイされるアプリケーションの ARCHIVE_PATH/META-INF ディレクトリ内のアプリケーション アーカイブと共にパッケージ化された weblogic-diagnostics.xml という XML コンフィグレーション ファイルを使用します。
インスツルメンテーション コードは、サーバおよびアプリケーションのコード内の特定の場所に挿入 (または「ウィービング」) されます。この特定の場所を表すために、以下の用語が使用されています。
<pointcut> です。ポイントカットについては、「カスタム モニタのポイントカットの定義」を参照してください。<location-type> です。| 注意 : |
診断モニタは、そのスコープと種類によって分類されます。スコープは、サーバ スコープかアプリケーション スコープのどちらかです。種類は、モニタのポイントカット、診断場所、およびアクションによって決まります。たとえば、Servlet_Around_Service はアプリケーション スコープの代理モニタです。このモニタを使用すると、特定のサーブレット メソッドや JSP メソッドの入り口と出口で診断アクションをトリガできます。
インスツルメンテーション診断モニタには、以下に示す 3 種類があります。
標準のサーバ スコープ モニタは DyeInjection モニタのみです。このモニタは、サーバ レベルで診断コンテキストを作成して仕分けの注入をコンフィグレーションするために使用します。詳細については、「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」を参照してください。
標準のアプリケーション スコープ モニタは HttpSessionDebug のみです。このモニタは、HTTP Session オブジェクトを検査するために使用します。
代理モニタは、それ自体では完成していません。代理モニタが何らかの意味のある処理を行うには、少なくとも 1 つのアクションをモニタに割り当てる必要があります。
すべてのアクションがどのモニタにも割り当て可能なわけではありません。Administration Console で代理モニタをコンフィグレーションする場合、選択したモニタで対応可能なアクションのみを指定できます。WLST を使用する場合、または記述子ファイルを手動で編集する場合は、アクションがそのモニタで対応可能かどうかを確認する必要があります。XML ファイルがデプロイメント時にロードされたときに、検証が実行されます。
WLDF インスツルメンテーション ライブラリで利用可能な代理モニタとアクションについては、「WLDF インスツルメンテーション ライブラリ」を参照してください。
ユーザはカスタム モニタに名前を付け、モニタで使用するポイントカットと診断ロケーションを定義し、あらかじめ決められている診断アクションのセットからアクションを割り当てます。<pointcut> 要素と <location type> 要素はカスタム モニタでは必須です。
表 10-1 に、各種類のモニタの違いを簡単に示します。
モニタに対して「仕分けマスク」を設定すると、診断アクションがトリガされるタイミングを制限できます。このマスクによって、診断コンテキストのどの仕分けフラグがアクションをトリガするかが決まります。モニタの仕分けマスクの設定については、「<wldf-instrumentation-monitor> XML 要素」を参照してください。
| 注意 : | 診断コンテキスト、仕分けの注入、および仕分けフィルタについては、「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」で説明します。 |
診断アクションは、関連する代理モニタまたはカスタム モニタに対応する診断コードを実行します (標準モニタの場合、アクションはあらかじめ定義されています)。代理モニタまたはカスタム モニタが何らかの意味のある処理を行うには、モニタに対して少なくとも 1 つのアクションをコンフィグレーションする必要があります。
WLDF 診断ライブラリでは、以下のアクションを利用できます。アクションをモニタにアタッチするには、DIAG_MODULE.xml コンフィグレーション ファイルの <action> 要素でアクション名を指定します。
アクションは、モニタに正しく対応している必要があります。たとえば、TraceElapsedTime アクションは、診断ロケーションの種類が around のカスタム モニタ、または代理モニタで使用できます。詳細については、「WLDF インスツルメンテーション ライブラリ」を参照してください。
インスツルメンテーションは、診断記述子の一部として XML コンフィグレーション ファイルでコンフィグレーションされます。このファイルの名前と格納場所は、システムレベル (サーバ スコープ) のインスツルメンテーションを実装しているか、アプリケーション レベル (アプリケーション スコープ) のインスツルメンテーションを実装しているかによって異なります。
DOMAIN_NAME/config/diagnostics
このディレクトリには、複数のシステムレベルの診断記述子ファイルを格納できます。ファイル名は任意ですが、.xml で終わる必要があります (myDiag.xml は有効なファイル名です)。各ファイルには、ハーベスタ、インスツルメンテーション、または監視と通知のうち、1 つまたは複数のデプロイ可能な診断コンポーネントのコンフィグレーション情報を格納できます。記述子ファイルの <instrumentation> セクションでは、1 つまたは複数の診断モニタをコンフィグレーションできます。サーバ スコープのインスツルメンテーションは、サーバを再起動しなくても有効化および無効化でき、再コンフィグレーションも可能です。
サーバ (またはクラスタ) では、一度に 1 つの WLDF システム リソース (つまり、1 つのシステムレベルの診断記述子ファイル) のみをアクティブにできます。アクティブな記述子は、以下のコンフィグレーション ファイルからリンクおよび対象指定されます。
DOMAIN_NAME/config/config.xml
診断システム モジュールのコンフィグレーションの詳細については、「診断システム モジュールのコンフィグレーション」を参照してください。WebLogic Server のコンフィグレーション ファイルの作成、内容、および解析の概要については、『ドメインのコンフィグレーションについて』を参照してください。
META-INF/weblogic-diagnostics.xml
アプリケーションにデプロイ可能な診断コンポーネントはインスツルメンテーションだけです。したがって、この記述子には、インスツルメンテーションのコンフィグレーション情報のみを格納できます。
| 注意 : | インスツルメンテーションをアプリケーションで使用できるようにするには、アプリケーションがデプロイされるサーバでインスツルメンテーションを有効にする必要があります (サーバ スコープ インスツルメンテーションは、サーバの診断記述子の <instrumentation> 要素で有効にしたり無効にしたりできます)。 |
アプリケーションを再デプロイせずに診断モニタを有効にしたり無効にしたりできます。ただし、ポイントカットの定義やモニタの削除など、他のインスツルメンテーション機能を変更した後には、アプリケーションを再デプロイする必要があります。再デプロイする必要があるかどうかは、インスツルメンテーションのコンフィグレーション方法とアプリケーションのデプロイ方法によって異なります。3 つの選択肢があります。
これらの選択肢の詳細については、「インスツルメンテーション コンフィグレーションを動的に制御するためのデプロイメント プランの使用」を参照してください。
診断アプリケーション モジュールのデプロイと変更の詳細については、「WLDF アプリケーション モジュールのデプロイメント」を参照してください。
http://www.bea.com/ns/weblogic/90/diagnostics.xsd
詳細については、『WebLogic Server Diagnostics Schema Reference』を参照してください。
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
WLDF リソースのコンフィグレーションの概要については、「WLDF コンフィグレーションについて」を参照してください。
この節では、記述子のコード フラグメント、インスツルメンテーションのコンフィグレーションに使用する XML 要素をまとめた表、および各インスツルメンテーション診断モニタについて簡単に説明した表を示します。
<instrumentation> 要素内で使用する最上位の各要素について説明します。<wldf-instrumentation-monitor> 要素内で使用する各要素について説明します。
表 10-2 では、DIAG_MODULE.xml ファイルの <instrumentation> 要素について説明します。以下のコンフィグレーション フラグメントでは、この要素の使用方法を示します。
<wldf-resource>
<name>MyDiagnosticModule</name>
<instrumentation>
<enabled>true</enabled>
<!-- 次の <include> 要素は、1 つのアプリケーション スコープ
インスツルメンテーション要素にのみ適用される -->
<include>foo.bar.com.*</include>
<!-- この診断モジュールに対する診断モニタを定義する
<wldf-instrumentation-monitor> 要素 -->
</instrumentation>
<!-- この診断モニタをコンフィグレーションする他の要素 -->
</wldf-resource>
*) を使用可能。複数の <include> 要素を指定できる。指定した場合、インスツルメンテーションの対象となるには、クラスは <include> パターンに一致する必要がある。
|
|||||
診断モニタは <wldf-instrumentation-monitor> 要素で定義されます。<wldf-instrumentation-monitor> 要素は、サーバ スコープのインスツルメンテーションの DIAG_MODULE.xml 記述子またはアプリケーション スコープのインスツルメンテーションの META-INF/weblogic-diagnostics.xml 記述子における <instrumentation> 要素の子要素です。
次のフラグメントは、アプリケーションの代理モニタおよびカスタム モニタのコンフィグレーションを示しています (サーバ スコープのインスツルメンテーションの場合は、アプリケーション スコープのモニタをサーバ スコープのモニタに置き換えれば、このフラグメントを変更できます)。
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>Servlet_Before_Service</name>
<enabled>true</enabled>
<dye-mask>USER1</dye-mask>
<dye-filtering-enabled>true</dye-filtering-enabled>
<action>TraceAction</action>
</wldf-instrumentation-monitor>
<wldf-instrumentation-monitor>
<name>MyCustomMonitor</name>
<enabled>true</enabled>
<action>TraceAction</action>
<location-type>before</location-type>
<pointcut>call( * com.foo.bar.* get*(...));</pointcut>
</wldf-instrumentation-monitor>
</instrumentation>
ここでは、Servlet_Before_Service モニタは仕分けマスクを設定しており、仕分けフィルタが有効になっています。これは、インスツルメンテーションがサーバ レベルで有効になっており、DyeInjection モニタが有効化されて適切にコンフィグレーションされている場合にのみ役に立ちます。DyeInjection モニタのコンフィグレーションについては、「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」を参照してください。
表 10-3 に、<wldf-instrumentation-monitor> 要素の説明を示します。
<action> 要素を指定できる。アクションは、モニタのタイプに対応している必要がある。代理モニタとカスタム モニタ用にあらかじめ定義されているアクションのリストについては、「WLDF インスツルメンテーション ライブラリ」を参照。
|
|||||
|
|
|||||
*) を使用可能。複数の <include> 要素を指定できる。指定した場合、インスツルメンテーションの対象となるには、クラスは <include> パターンに一致する必要がある。
<include> または <exclude> パターンを指定すると、親 <wldf-instrumentation-monitor> 要素で定義されるモニタにのみ適用される。
|
|||||
<dye-filtering-enabled> と <dye-mask> については、さらに以下の情報があります。
DyeInjection モニタが有効になっており、サーバまたはクラスタ用にコンフィグレーションされている場合、下流にある代理モニタおよびカスタム モニタに対して仕分けフィルタを使用し、要求の診断コンテキストに対してその DyeInjection モニタが実行した仕分けを確認できます。DyeInjection モニタのコンフィグレーションによって、診断コンテキストに関連付けられた 64 ビット仕分けベクトルでどのビットが設定されるかが決まります。<dye-filtering-enabled> 属性がモニタに対して有効になっていても、要求の診断コンテキストの仕分けベクトルが、モニタでコンフィグレーションされた仕分けマスクと一致していない場合、診断アクティビティは実行されません。仕分けベクトルが仕分けマスクと一致している場合 (ビット単位の AND の場合)、アプリケーションは診断アクションを実行できます。(dye_vector & dye_mask == dye_mask)
したがって、仕分けフィルタのメカニズムを使用すると、モニタは特定の要求に対してのみ診断アクションを実行でき、それによって他の要求の処理が遅くなることはありません。診断コンテキストおよび仕分けベクトルの詳細については、「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」を参照してください。
表 10-4 に、どの <wldf-instrumentation-monitor> 要素がどのモニタに対応しているかを示します。
|
サーバ レベルでインスツルメンテーションを有効にし、サーバ スコープのモニタをコンフィグレーションするには、以下の手順を実行します。
1 つのドメインで複数の DIAG_MODULE.xml 診断記述子ファイルを使用できますが、サーバ (またはクラスタ) ごとにデプロイできる診断記述子ファイルは一度に 1 つだけです。複数のファイルを作成する理由は、柔軟性です。たとえば、DOMAIN_NAME/config/diagnostics ディレクトリに 5 つの診断記述子ファイルを保存し、ファイルごとに異なるインスツルメンテーション (に加え、おそらくハーベスタおよび監視と通知) のコンフィグレーションを格納できます。次に、特定の状況でどのモニタをアクティブにするかに基づいて、サーバにファイルをデプロイします。
DIAG_MODULE.xml ファイルを作成する場合 (推奨手順)、コンソールには、そのモニタに対応するアクションのみが表示されます。エディタまたは WebLogic Scripting Tool (WLST) でコンフィグレーション ファイルを作成する場合は、アクションとモニタを正しく関連付ける必要があります。
コード リスト 10-1 に、サーバ スコープ インスツルメンテーションのコンフィグレーション ファイルのサンプルを示します。このサンプルでは、インスツルメンテーションを有効にし、DyeInjection 標準モニタおよび Connector_Before_Work 代理モニタをコンフィグレーションします。1 つの <instrumentation> 要素に、モジュールのすべてのインスツルメンテーションのコンフィグレーションが格納されます。各診断モニタは、個別の <wldf-instrumentation-monitor> 要素で定義されます。
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>DyeInjection</name>
<description>Inject USER1 and ADDR1 dyes</description>
<enabled>true</enabled>
<properties>USER1=weblogic
ADDR1=127.0.0.1</properties>
</wldf-instrumentation-monitor>
<wldf-instrumentation-monitor>
<name>Connector_Before_Work</name>
<enabled>true</enabled>
<action>TraceAction</action>
<dye-filtering-enabled>true</dye-filtering-enabled>
<dye-mask>USER1</dye-mask>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
アプリケーション レベルでは、WLDF のインスツルメンテーションは、デプロイ可能なモジュールとしてコンフィグレーションされます。このモジュールは、アプリケーションの一部としてデプロイされます。
以下の節では、アプリケーション スコープのインスツルメンテーションのコンフィグレーションで必要な情報について説明します。
アプリケーションのインスツルメントは、システム レベルでのインスツルメントと似ていますが、以下の点が違います。
DyeInjection のみです。アプリケーション スコープの標準モニタは HttpSessionDebug のみです。詳細については、「診断モニタ ライブラリ」の HttpSessionDebug の項目を参照してください。weblogic-diagnostics.xml 記述子ファイルでコンフィグレーションされます。ユーザは META-INF/weblogic-diagnostics.xml ファイルを作成し、インスツルメンテーションをコンフィグレーションして、アプリケーションのアーカイブにファイルを格納します。アーカイブがデプロイされると、インスツルメンテーションは、アプリケーションがロードされたときに自動的に挿入されます。
アプリケーション スコープ インスツルメンテーションの XML 記述子は、サーバ スコープ インスツルメンテーションの場合と同じ方法で定義されます。WLDF インスツルメンテーション ライブラリで使用可能な代理モニタと診断アクションを使用すると、アプリケーション専用のインスツルメンテーションをコンフィグレーションできます。また、ユーザ独自のカスタム モニタも作成できますが、カスタム モニタにアタッチする診断アクションは、WLDF インスツルメンテーション ライブラリから指定する必要があります。
表 10-5 では、システム モジュールとアプリケーション モジュールの機能とスコープを比較します。
アプリケーションの診断モニタを実装するには、以下の手順を実行します。
META-INF/weblogic-diagnostics.xml 記述子ファイルをアプリケーション用に作成します。<instrumentation> 要素を有効 (<enabled>true</enabled>) にします。
各モニタのタイプ用に整形された記述子ファイルのサンプルについては、「代理モニタの記述子ファイルの作成」および「カスタム モニタの記述子ファイルの作成」を参照してください。
ポイントカット式の作成については、「カスタム モニタのポイントカットの定義」を参照してください。
次に、アプリケーション スコープの代理モニタ用に整形された META-INF/weblogic-diagnostics.xml ファイルの例を示します。
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>Servlet_Before_Service</name>
<enabled>true</enabled>
<dye-mask>USER1</dye-mask>
<dye-filtering-enabled>true</dye-filtering-enabled>
<action>TraceAction</action>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
Servlet_Before_Service モニタは、WLDF モニタ ライブラリから選択したアプリケーション スコープのモニタです。複数のサーブレット メソッドまたは JSP メソッドの入り口にジョインポイントを設定するポイントカットを使用してハードコード化されています。アプリケーションは仕分けフィルタを有効にし、仕分けマスクに USER1 フラグを設定しているので、TraceAction アクションは、アプリケーションに渡される診断コンテキスト内の仕分けベクトルに USER1 フラグ セットがある場合にのみ呼び出されます (仕分けベクトルは、DyeInjection モニタを介してシステム レベルで設定されます)。したがって、このアプリケーションの Servlet_Before_Service モニタは、仕分けベクトルを確認し、USER1 フラグ セットを見つけるまで、基本的に何も行いません。このフィルタ処理を実行すれば、生成される診断データの量を減らし、その時点で管理者にとって意味のあるデータのみを生成することができます。
次に、カスタム モニタの整形式 META-INF/weblogic-diagnostics.xml ファイルの例を示します。
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>MyCustomMonitor</name>
<enabled>true</enabled>
<action>TraceAction</action>
<location-type>before</location-type>
<pointcut>call( * com.foo.bar.* get* (...));</pointcut>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
カスタム モニタの場合、<name> は、開発者が指定した任意の文字列です。このモニタはカスタムなので、アクションの呼び出し用にあらかじめ定義された診断ロケーションはありません。記述子ファイルでは、診断ロケーションの種類とポイントカット式を定義する必要があります。この例では、TraceAction アクションは、ポイントカット式で定義されたメソッドが呼び出される前 (<location-type>before</location-type>) に呼び出されます。表 10-6 では、コード リスト 10-2 のポイントカット式の解析方法を示しています (ワイルドカードの使用に注意してください)。
このポイントカット式は、パッケージ com.foo.bar とそのサブパッケージ内にあるすべてのクラスの get*() を一致対象にします。メソッドは、void を含む任意の型の値を返すことができます。また、任意の型の引数を、数に制限なく持つことができます。インスツルメンテーション コードは、これらのメソッドの前に挿入され、そのメソッドが呼び出される直前に、TraceAction アクションが呼び出されます。
ポイントカットの定義に使用する文法の詳細については、「カスタム モニタのポイントカットの定義」を参照してください。
カスタム モニタでは、診断アクションの呼び出し場所を指定するポイントカット式をユーザが作成するので、代理モニタよりも柔軟な操作が可能です。代理モニタの場合は、アクション ライブラリからアクションを選択する必要があります。
ジョインポイントは、精密に定義された、プログラム内の固有の位置です。ポイントカットは、ジョインポイントのセットを指定する式です。この節では、以下のポイントカット構文を使用して、ポイントカットの式を定義する方法について説明します。
カスタム モニタでは 2 種類のポイントカットを指定できます。
<pointcut> ::= [(] <joinpoint> [ <conditional> <joinpoint> ] [)]
<joinpoint> ::= [(] <execution-joinpoint> | <call-joinpoint>
<execution-pointcut> ::= execution ( <access-type> <joinpoint-signature> )
<callsite-pointcut> ::= call ( <joinpoint-signature> )
<joinpoint-signature> ::= <method-signature>
<method-signature> ::= <return-type> <class-type>.<method-name>
( <parameter-list> )
<return-type> ::= <class-type> | <primitive-type>
<parameter-list> ::= <parameter-type> [, <parameter-type>] *
<parameter-type> ::= <class-type> | <primitive-type> | <elipsis>
<class-type> ::= [<use-class-hierarchy>] ? <class-or-interface-name-pattern>
<conditional> ::= AND [NOT] | OR [NOT] | NOT
<use-class-hierarchy> ::= '+'
<elipsis> ::= '...'
*) は、クラスの型やメソッド名に使用できます。 ...) は、その引数以外に任意の型の引数がいくつか (数は可変) あることを示します。 + (プラス記号) プレフィックスは、指定したクラス/インタフェース パターンを実装しているすべてのサブクラス、サブインタフェース、または具象クラスを示します。
たとえば、以下のポイントカットは、パッケージ com.foo.bar とそのサブパッケージ内にあるすべてのクラスの、初期化された全パブリック メソッドのメソッド実行を一致対象にします。初期化されたメソッドは、void を含む任意の型の値を返すことができます。また、任意の型の引数を、数に制限なく持つことができます。
execution(public * com.foo.bar.* initialize(...))
以下のポイントカットは、com.foo.bar.MyInterface インタフェース (または、たまたまクラスだった場合はサブクラス) を直接または間接的に実装するすべてのクラスにあるメソッド呼び出し (呼び出しサイト) を一致対象にします。名前が get で始まり、int 値を返すパブリック メソッドが対象になります。また、メソッドは、java.lang.String 型の引数 1 つを受け付けるものでなければなりません。
call(int +com.foo.bar.MyInterface get*(java.lang.String))
以下の例では、ブール演算子を使用してポイントカット式ツリーを構築する方法を示します。
call(void com.foo.bar.* set*(java.lang.String)) OR
call( * com.foo.bar.* get*())
以下の例では、前の式ツリーが、コンフィグレーション ファイルでどのように <pointcut> 要素として変換されるかを示します。
<pointcut>call(void com.foo.bar.* set*(java.lang.String)) OR
call( * com.foo.bar.* get*())</pointcut>
  
|
