Oracle® Fusion Middleware Oracle WebLogic Server 診断フレームワークのコンフィグレーションと使い方 11g リリース 1 (10.3.1) B55523-01 |
|
戻る |
次へ |
WebLogic 診断フレームワーク (WebLogic Diagnostic Framework WLDF) のインスツルメンテーション コンポーネントは、WebLogic Server インスタンスおよびそのサーバ インスタンスで実行中のアプリケーションに診断コードを追加するためのメカニズムを提供します。WLDF のインスツルメンテーションで主要な機能は次のとおりです。
診断モニタ。サーバまたはアプリケーション コードの特定の場所に挿入され、動的に管理できるひとまとまりの診断コードです。モニタは、スコープ (システム、アプリケーション) および種類 (標準、代理、カスタム) を基に定義します。
診断アクション。プログラムの実行中にトリガされたモニタが行うアクション。
診断コンテキスト。診断コンテキストは、送信元の IP アドレスやユーザ ID など、特定の要求プロパティの存在を示すフラグやユニークな要求識別子などのコンテキスト情報です。診断コンテキストでは、プログラムの実行を追跡したり、モニタが診断アクションをトリガするタイミングを制御したりすることができます。「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」を参照してください。
WLDF には、あらかじめ定義された診断モニタと診断アクションのライブラリが用意されています。また、アプリケーション スコープのカスタム モニタを作成し、診断コードが挿入されるアプリケーション内の位置をユーザが決めることもできます。
インスツルメンテーションについては、以下の節で説明します。
この節では、インスツルメンテーションの概念と用語について説明します。
実行可能なインスツルメンテーション サービスには、システム レベル (サーバおよびクラスタ) のものとアプリケーション レベルのものがあります。概念、サービス、コンフィグレーション オプション、および実装機能の多くは両者とも同じです。ただし、相違点もいくつかあります。それらについて、このマニュアルで説明します。「サーバ スコープ インスツルメンテーション」は、WebLogic Server インスタンスおよびクラスタ固有のインスツルメンテーションのコンフィグレーションと機能を指し、「アプリケーション スコープ インスツルメンテーション」は、WebLogic サーバにデプロイされているアプリケーション固有のコンフィグレーションと機能を指します。スコープは各診断モニタに組み込まれており、ユーザがモニタのスコープを変更することはできません。
サーバまたはクラスタ向けのサーバ スコープ インスツルメンテーションは、診断モジュールの一部として、DOMAIN_NAME/config/diagnostics ディレクトリにある XML コンフィグレーション ファイルでコンフィグレーションおよびデプロイされ、config.xml からリンクされています。
アプリケーション スコープ インスツルメンテーションも、診断モジュールとしてコンフィグレーションおよびデプロイされます。ただし、アプリケーション スコープの場合は、デプロイされるアプリケーションの ARCHIVE_PATH/META-INF ディレクトリ内のアプリケーション アーカイブと共にパッケージ化された weblogic-diagnostics.xml という XML コンフィグレーション ファイルを使用します。
インスツルメンテーション コードは、サーバおよびアプリケーションのコード内の特定の場所に挿入 (または「ウィービング」) されます。この特定の場所を表すために、以下の用語が使用されています。
「ジョインポイント」は、クラス内の特定の場所です。たとえば、メソッドの入り口や出口のポイント、メソッド内の呼び出しサイトなどを指します。
「ポイントカット」は、一連のジョインポイントを示す用語で、作業項目のスケジューリング、開始、および実行に関わるすべてのメソッドなどを指します。ポイントカットを定義する XML 要素は <pointcut> です。ポイントカットについては、「カスタム モニタのポイントカットの定義」を参照してください。
「診断ロケーション」は、ジョインポイントを基準にした、診断アクティビティが実行される位置です。診断ロケーションには、before (ジョインポイントの前)、after (ジョインポイントの後)、around (ジョインポイントの前後) のいずれかを指定できます。診断ロケーションを定義する XML 要素は <location-type> です。
診断モニタは、そのスコープと種類によって分類されます。スコープは、サーバ スコープかアプリケーション スコープのどちらかです。種類は、モニタのポイントカット、診断場所、およびアクションによって決まります。たとえば、Servlet_Around_Service はアプリケーション スコープの代理モニタです。このモニタを使用すると、特定のサーブレット メソッドや JSP メソッドの入り口と出口で診断アクションをトリガできます。
インスツルメンテーション診断モニタには、以下に示す 3 種類があります。
「標準モニタ」は、あらかじめ定義されている特定のポイントカットおよび診断ロケーションで、あらかじめ定義されている特定の診断アクションを実行します。標準モニタでは、これらのアクション、ポイントカット、診断ロケーションはハードコード化されています。モニタを有効または無効にできますが、モニタの動作を変更することはできません。
標準モニタは DyeInjection モニタのみです。このモニタはサーバ スコープ モニタであり、サーバ レベルで診断コンテキストを作成して仕分けの注入をコンフィグレーションするために使用します。「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」を参照してください。
標準のアプリケーション スコープ モニタは HttpSessionDebug のみです。このモニタは、HTTP Session オブジェクトを検査するために使用します。
「代理モニタ」では、スコープ、ポイントカット、および診断ロケーションがハードコード化されていますが、モニタで実行するアクションは、ユーザが選択します。「代理」という名前のとおり、このモニタでは、あらかじめ定義されているアクションに代わって、ユーザが選択したアクションが実行されます。代理モニタは、サーバ スコープかアプリケーション スコープのどちらかです。
代理モニタは、それ自体では完成していません。代理モニタが何らかの意味のある処理を行うには、少なくとも 1 つのアクションをモニタに割り当てる必要があります。
すべてのアクションがどのモニタにも割り当て可能なわけではありません。Administration Console で代理モニタをコンフィグレーションする場合、選択したモニタで対応可能なアクションのみを指定できます。WLST を使用する場合、または記述子ファイルを手動で編集する場合は、アクションがそのモニタで対応可能かどうかを確認する必要があります。XML ファイルがデプロイメント時にロードされたときに、検証が実行されます。
WLDF インスツルメンテーション ライブラリで利用可能な代理モニタとアクションについては「WLDF インスツルメンテーション ライブラリ」を参照してください。
「カスタム モニタ」は、特殊なケースで使用する代理モニタで、アプリケーション スコープのインスツルメンテーションでのみ利用可能です。ポイントカットや診断ロケーションはあらかじめ定義されていません。
ユーザはカスタム モニタに名前を付け、モニタで使用するポイントカットと診断ロケーションを定義し、あらかじめ決められている診断アクションのセットからアクションを割り当てます。<pointcut> 要素と <location type> 要素はカスタム モニタでは必須です。
表 10-1 に、各種類のモニタの違いを簡単に示します。
表 10-1 診断モニタのタイプ
モニタ タイプ | スコープ (有効範囲) | ポイントカット | 診断ロケーション | アクション |
---|---|---|---|---|
標準モニタ |
サーバ |
固定 |
固定 |
固定 |
代理モニタ |
サーバまたはアプリケーション |
固定 |
固定 |
コンフィグレーション可能 |
カスタム モニタ |
アプリケーション |
コンフィグレーション可能 |
コンフィグレーション可能 |
コンフィグレーション可能 |
モニタに対して「仕分けマスク」を設定すると、診断アクションがトリガされるタイミングを制限できます。このマスクによって、診断コンテキストのどの仕分けフラグがアクションをトリガするかが決まります。モニタの仕分けマスクの設定については、「<wldf-instrumentation-monitor> XML 要素」を参照してください。
診断アクションは、関連する代理モニタまたはカスタム モニタに対応する診断コードを実行します (標準モニタの場合、アクションはあらかじめ定義されています)。代理モニタまたはカスタム モニタが何らかの意味のある処理を行うには、モニタに対して少なくとも 1 つのアクションをコンフィグレーションする必要があります。
WLDF 診断ライブラリでは、以下のアクションを利用できます。アクションをモニタにアタッチするには、DIAG_MODULE.xml コンフィグレーション ファイルの <action> 要素でアクション名を指定します。
DisplayArgumentsAction
StackDumpAction
ThreadDumpAction
TraceAction
TraceElapsedTimeAction
MethodInvocationStatisticsAction
アクションは、モニタに正しく対応している必要があります。たとえば、TraceElapsedTime アクションは、診断ロケーションの種類が around のカスタム モニタ、または代理モニタで使用できます。詳細については、「WLDF インスツルメンテーション ライブラリ」を参照してください。
インスツルメンテーションは、診断記述子の一部として XML コンフィグレーション ファイルでコンフィグレーションされます。このファイルの名前と格納場所は、システムレベル (サーバ スコープ) のインスツルメンテーションを実装しているか、アプリケーション レベル (アプリケーション スコープ) のインスツルメンテーションを実装しているかによって異なります。
システム レベルのインスツルメンテーション コンフィグレーションは、以下のディレクトリの診断記述子に格納されます。
DOMAIN_NAME/config/diagnostics
このディレクトリには、複数のシステムレベルの診断記述子ファイルを格納できます。ファイル名は任意ですが、.xml で終わる必要があります (myDiag.xml は有効なファイル名です)。各ファイルには、ハーベスタ、インスツルメンテーション、または監視と通知のうち、1 つまたは複数のデプロイ可能な診断コンポーネントのコンフィグレーション情報を格納できます。記述子ファイルの <instrumentation> セクションでは、1 つまたは複数の診断モニタをコンフィグレーションできます。サーバ スコープのインスツルメンテーションは、サーバを再起動しなくても有効化および無効化でき、再コンフィグレーションも可能です。
サーバ (またはクラスタ) では、一度に 1 つの WLDF システム リソース (つまり、1 つのシステムレベルの診断記述子ファイル) のみをアクティブにできます。アクティブな記述子は、以下のコンフィグレーション ファイルからリンクおよび対象指定されます。
DOMAIN_NAME/config/config.xml
診断システム モジュールのコンフィグレーションの詳細については、「診断システム モジュールのコンフィグレーション」を参照してください。WebLogic Server のコンフィグレーション ファイルの作成、内容、および解析の概要については、『Oracle Fusion Middleware Oracle WebLogic Server ドメインのコンフィグレーションについて』を参照してください。
アプリケーション レベルのインスツルメンテーション コンフィグレーションは、以下の場所にあるアプリケーションのアーカイブ内にパッケージ化されます。
META-INF/weblogic-diagnostics.xml
アプリケーションにデプロイ可能な診断コンポーネントはインスツルメンテーションだけです。したがって、この記述子には、インスツルメンテーションのコンフィグレーション情報のみを格納できます。
注意 : インスツルメンテーションをアプリケーションで使用できるようにするには、アプリケーションがデプロイされるサーバでインスツルメンテーションを有効にする必要があります。(サーバ スコープ インスツルメンテーションは、サーバの診断記述子の <instrumentation> 要素で有効にしたり無効にしたりできます)。 |
アプリケーションを再デプロイせずに診断モニタを有効にしたり無効にしたりできます。ただし、ポイントカットの定義やモニタの削除など、他のインスツルメンテーション機能を変更した後には、アプリケーションを再デプロイする必要があります。再デプロイする必要があるかどうかは、インスツルメンテーションのコンフィグレーション方法とアプリケーションのデプロイ方法によって異なります。3 つの選択肢があります。
JSR-88 デプロイメント プランを使用しないで、アプリケーションのインスツルメンテーション コンフィグレーションを直接定義および変更する。
インスツルメンテーション設定のプレースホルダを含むデプロイメント プランを使用して、アプリケーションをコンフィグレーションおよびデプロイする。
サーバの起動時にホットスワップ機能を有効にし、インスツルメンテーション設定のプレースホルダを含むデプロイメント プランを使用してデプロイする。
これらの選択肢の詳細については、「インスツルメンテーション コンフィグレーションを動的に制御するためのデプロイメント プランの使用」を参照してください。
診断アプリケーション モジュールのデプロイと変更の詳細については、「WLDF アプリケーション モジュールのデプロイメント」を参照してください。
診断 XML スキーマは以下の場所にあります。
http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd
各診断記述子ファイルは、以下の行で始まる必要があります。
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
WLDF リソースのコンフィグレーションの概要については、「WLDF コンフィグレーションについて」を参照してください。
この節では、記述子のコード フラグメント、インスツルメンテーションのコンフィグレーションに使用する XML 要素をまとめた表、および各インスツルメンテーション診断モニタについて簡単に説明した表を示します。
「<Instrumentation> XML 要素」では、<instrumentation> 要素内で使用する最上位の各要素について説明します。
「<wldf-instrumentation-monitor> XML 要素」では、<wldf-instrumentation-monitor> 要素内で使用する各要素について説明します。
「各モニタ タイプへの <wldf-instrumentation-monitor> の XML 要素のマッピング」では、どのインスツルメンテーション要素をどのモニタに適用するかについて説明します。
表 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>
表 10-2 DIAG_MODULE.xml コンフィグレーション ファイル内の <instrumentation> XML 要素
要素 | 説明 |
---|---|
<instrumentation> |
インスツルメンテーション コンフィグレーションを開始する要素。 |
<enabled> |
true の場合、インスツルメンテーションは有効。false の場合、インスツルメントされたコードは、このインスツルメンテーション スコープのクラスに挿入されておらず、このスコープ内のすべての診断モニタは無効。デフォルト値は false。 サーバとそこにデプロイされているアプリケーションに対するインスツルメンテーションを有効にするには、サーバ レベルでインスツルメンテーションを有効にする必要がある。さらに、(サーバ スコープのインスツルメンテーションの有効化に加えて) アプリケーションに対するインスツルメンテーションを有効にするには、アプリケーション レベルでインスツルメンテーションを有効にする必要がある。 |
<include> |
インスツルメントされたコードを挿入できるクラスのリストを指定する要素 (省略可能)。ワイルドカード (*) を使用可能。複数の <include> 要素を指定できる。指定した場合、インスツルメンテーションの対象となるには、クラスは <include> パターンに一致する必要がある。 アプリケーション スコープのインスツルメンテーションの場合にのみ有効。<include> または <exclude> パターンを指定すると、アプリケーション スコープ全体に適用される。 注意 : また、特定の診断モニタに対して <include> パターンおよび <exclude> パターンを指定することもできる。表 10-1 の <include> と <exclude> の項目を参照。 クラスがロードされると、インスツルメンテーション コードを挿入する前に、<include> または <exclude> のパターン チェックに成功する必要がある。クラスが <include> または <exclude> のパターン チェックに成功した場合でも、インスツルメントされるかどうかは、コンフィグレーション記述子で定義されている診断モニタによって決まる。ライブラリ内にあるアプリケーション スコープの代理モニタには、あらかじめ定義されている独自のクラスおよびポイントカットがある。カスタム モニタでは、独自のポイントカット式を指定する。そのため、<include> または <exclude> のパターン チェックに成功しても、クラスはインスツルメントされない場合がある。 注意 : インスツルメンテーションは、クラスのロード時にアプリケーションに挿入される。サイズの大きなアプリケーションを頻繁にロードする環境では、<include> または <exclude> 要素をうまく使えば、利便性の向上を期待できる。小さなアプリケーションや、中規模または大規模のアプリケーションでも頻繁にロードしない場合は、この要素を無視しても構わない。 |
<exclude> |
インスツルメントされたコードを挿入できないクラスのリストを指定する要素 (省略可能)。ワイルドカード (*) を使用可能。複数の <exclude> 要素を指定できる。指定した場合、<exclude> パターンに一致するクラスはインスツルメントされない。 アプリケーション スコープのインスツルメンテーションの場合にのみ有効。上の <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> 要素について説明します。
表 10-3 DIAG_MODULE.xml ファイルまたは weblogic-diagnostics.xml ファイル内の <wldf-instrumentation-monitor> XML 要素
要素 | 説明 |
---|---|
<wldf-instrumentation-monitor> |
診断モニタのコンフィグレーションを開始する要素。 |
<enabled> |
true の場合、モニタは有効。false の場合、モニタは無効。各モニタを個別に有効または無効にできる。デフォルト値は true です。 |
<name> |
モニタの名前。標準モニタと代理モニタの場合は、「WLDF インスツルメンテーション ライブラリ」であらかじめ定義されているモニタの名前を使用する。カスタム モニタの場合は、モニタを識別する任意の文字列を使用可能。カスタム モニタの名前はユニークでなければならない。つまり、ライブラリ内の他のモニタと名前が重複することはできない。 |
<description> |
モニタを説明する要素 (省略可能)。 |
<action> |
代理モニタとカスタム モニタに適用される要素 (省略可能)。アクションを 1 つ以上指定しない場合、モニタは情報を生成しない。複数の <action> 要素を指定できる。アクションは、モニタのタイプに対応している必要がある。代理モニタとカスタム モニタ用にあらかじめ定義されているアクションのリストについては、「WLDF インスツルメンテーション ライブラリ」を参照。 |
<dye-filtering-enabled> |
省略可能な要素。true の場合、そのモニタで仕分けフィルタが有効になる。false の場合、仕分けフィルタは無効。デフォルト値は false。 仕分けフィルタを使用するには、DyeInjection モニタをサーバ レベルで適切にコンフィグレーションする必要がある。 |
<dye-mask> |
省略可能な要素。仕分けフィルタが有効になっている場合、仕分けマスクは、診断コンテキスト内の値と比較して、アクションを起こすかどうかを決定する。仕分けおよび仕分けフィルタの詳細については、「診断コンテキストを管理するための DyeInjection モニタのコンフィグレーション」」を参照。 |
<properties> |
省略可能な要素。仕分けフラグ用に name=value のペアを設定する。 現在は DyeInjection モニタにのみ適用される。 |
<location-type> |
before、after、around のいずれかの値を持つ要素 (省略可能)。この要素によって、ポイントカットを基準にアクションがトリガされるタイミング (ポイントカットの前でトリガされるか、ポイントカットの後でトリガされるか、ポイントカットの前後でトリガされるか) が決まる。 カスタム モニタの場合にのみ有効。標準モニタおよび代理モニタでは、この値はあらかじめ定義されている。カスタム モニタでは、診断ロケーションの種類とポイントカットを定義する必要がある。 |
<pointcut> |
省略可能な要素。ポイントカット要素には、診断コードが挿入されるジョインポイントを定義する式が格納される。 カスタム モニタの場合にのみ有効。標準モニタおよび代理モニタでは、この値はあらかじめ定義されている。カスタム モニタでは、診断ロケーションの種類とポイントカットを定義する必要がある。 ポイントカットの構文については、「カスタム モニタのポイントカットの定義」を参照。 |
<include> |
インスツルメントされたコードを挿入できるクラスのリストを指定する要素 (省略可能)。ワイルドカード (*) を使用可能。複数の <include> 要素を指定できる。指定した場合、インスツルメンテーションの対象となるには、クラスは <include> パターンに一致する必要がある。 アプリケーション スコープのインスツルメンテーションの場合にのみ有効。<include> または <exclude> パターンを指定すると、親 <wldf-instrumentation-monitor> 要素で定義されるモニタにのみ適用される。 注意 : インスツルメントされたアプリケーション スコープ全体に対して <include> パターンおよび <exclude> パターンを指定することもできる。表 10-1 の <include> と <exclude> の項目を参照。 クラスがロードされると、インスツルメンテーション コードを挿入する前に、<include> または <exclude> のパターン チェックに成功する必要がある。クラスが <include> または <exclude> のパターン チェックに成功した場合でも、インスツルメントされるかどうかは、コンフィグレーション記述子で定義されている診断モニタによって決まる。ライブラリ内にあるアプリケーション スコープの代理モニタには、あらかじめ定義されている独自のクラスおよびポイントカットがある。カスタム モニタでは、独自のポイントカット式を指定する。そのため、<include> または <exclude> のパターン チェックに成功しても、クラスはインスツルメントされない場合がある。 注意 : インスツルメンテーションは、クラスのロード時にアプリケーションに挿入される。サイズの大きなアプリケーションを頻繁にロードする環境では、<include> または <exclude> 要素をうまく使えば、利便性の向上を期待できる。小さなアプリケーションや、中規模または大規模のアプリケーションでも頻繁にはロードしない場合は、この要素を無視しても構わない。 |
<exclude> |
インスツルメントされたコードを挿入できないクラスのリストを指定する要素 (省略可能)。ワイルドカード (*) を使用可能。複数の <exclude> 要素を指定できる。指定した場合、<exclude> パターンに一致するクラスはインスツルメントされない。 アプリケーション スコープのインスツルメンテーションの診断モニタにのみ有効。上記の <include> の説明を参照。 |
<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> 要素がどのモニタに対応しているかを示します。
表 10-4 各モニタ タイプへのインスツルメンテーション XML 要素のマッピング
要素 | 標準 | 代理 | カスタム |
---|---|---|---|
<wldf-instrumentation-monitor> |
X |
X |
X |
<name> |
X |
X |
X |
<description> |
X |
X |
X |
<enabled> |
X |
X |
X |
<action> |
X |
X |
|
<dye-filtering-enabled> |
X |
X |
|
<dye-mask> |
X |
X |
|
<properties> |
X脚注 1 |
||
<location-type> |
X |
||
<pointcut> |
X |
脚注 1 現在は、DyeInjection モニタで、仕分けフラグに name=value ペアを設定する場合にのみ使用されます。
サーバ レベルでインスツルメンテーションを有効にし、サーバ スコープのモニタをコンフィグレーションするには、以下の手順を実行します。
作成する WLDF システム リソースの数を決定します。
1 つのドメインで複数の DIAG_MODULE.xml 診断記述子ファイルを使用できますが、サーバ (またはクラスタ) ごとにデプロイできる診断記述子ファイルは一度に 1 つだけです。複数のファイルを作成する理由は、柔軟性です。たとえば、DOMAIN_NAME/config/diagnostics ディレクトリに 5 つの診断記述子ファイルを保存します。ファイルごとに異なるインスツルメンテーション (に加え、おそらくハーベスタおよび監視と通知) のコンフィグレーションを格納できます。次に、特定の状況でどのモニタをアクティブにするかに基づいて、サーバにファイルをデプロイします。
どのサーバ スコープ モニタをコンフィグレーションに含めるかを決めます。
サーバまたはそのサーバにデプロイされているものに対して仕分けフィルタを使用する場合は、DyeInjection モニタをコンフィグレーションします。
1 つまたは複数のサーバ スコープ代理モニタを使用する場合は、どのモニタを使用し、各モニタにどのアクションを関連付けるかを決めます。
コンフィグレーション ファイル (複数可) を作成してコンフィグレーションします。
Administration Console を使用して代理モニタ用の DIAG_MODULE.xml ファイルを作成する場合 (推奨手順)、コンソールには、そのモニタに対応するアクションのみが表示されます。エディタまたは WebLogic Scripting Tool (WLST) でコンフィグレーション ファイルを作成する場合は、アクションとモニタを正しく関連付ける必要があります。
config.xml ファイルのコンフィグレーションの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server ドメインのコンフィグレーションについて』の「ドメイン コンフィグレーション ファイル」を参照してください。
デプロイメント記述子ファイルを検証してデプロイします。サーバ スコープのインスツルメンテーションの場合は、サーバの実行中にモニタを追加および削除したり、モニタを有効または無効にしたりできます。
コード リスト 10-1 に、サーバ スコープ インスツルメンテーションのコンフィグレーション ファイルのサンプルを示します。このサンプルでは、インスツルメンテーションを有効にし、DyeInjection 標準モニタおよび Connector_Before_Work 代理モニタをコンフィグレーションします。1 つの <instrumentation> 要素に、モジュールのすべてのインスツルメンテーションのコンフィグレーションが格納されます。各診断モニタは、個別の <wldf-instrumentation-monitor> 要素で定義されます。
コード リスト 10-1 サーバ スコープのインスツルメンテーションのサンプル (DIAG_MODULE.xml 内)
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-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 のみです。アプリケーション スコープの標準モニタは HttpSessionDebugMonitor のみです。詳細については、「診断モニタ ライブラリ」の HttpSessionDebugMonitor の項目を参照してください。
代理モニタは、サーバ スコープかアプリケーション スコープのどちらかです。アプリケーションは、アプリケーション スコープの代理モニタを使用する必要があります。
カスタム モニタはすべてアプリケーション スコープです。
サーバのインスツルメンテーション設定は、アプリケーションに影響します。インスツルメンテーションをアプリケーションに対して有効にするには、アプリケーションがデプロイされるサーバでインスツルメンテーションを有効にする必要があります。デプロイメント時にサーバのインスツルメンテーションが有効である場合、アプリケーションでインスツルメンテーションを利用できます。デプロイメント時にサーバでインスツルメンテーションが有効になっていない場合、アプリケーションでインスツルメンテーションを有効にしても無視されます。
アプリケーションのインスツルメンテーションが、weblogic-diagnostics.xml 記述子でコンフィグレーションする必要がある。ユーザは META-INF/weblogic-diagnostics.xml ファイルを作成し、インスツルメンテーションをコンフィグレーションして、アプリケーションのアーカイブにファイルを格納します。アーカイブがデプロイされると、インスツルメンテーションは、アプリケーションがロードされたときに自動的に挿入されます。
「デプロイメント プラン」を使用すると、アプリケーションを再デプロイしなくても、コンフィグレーション要素を動的に更新できます。「インスツルメンテーション コンフィグレーションを動的に制御するためのデプロイメント プランの使用」を参照してください。
アプリケーション スコープ インスツルメンテーションの XML 記述子は、サーバ スコープ インスツルメンテーションの場合と同じ方法で定義されます。WLDF インスツルメンテーション ライブラリで使用可能な代理モニタと診断アクションを使用すると、アプリケーション専用のインスツルメンテーションをコンフィグレーションできます。また、ユーザ独自のカスタム モニタも作成できますが、カスタム モニタにアタッチする診断アクションは、WLDF インスツルメンテーション ライブラリから指定する必要があります。
表 10-5 では、システム モジュールとアプリケーション モジュールの機能とスコープを比較します。
注意 : WLS10.3 では、前の WLS リリースにおけるケースのように、アプリケーションの META-INF ディレクトリの weblogic-diagnostics.xml ファイルを作成する必要はありません。ただし、この方法でアプリケーションの診断モニタを最初にコンフィグレーションすることもできます。 |
アプリケーションの診断モニタを実装するには、以下の手順を実行します。
サーバでインスツルメンテーションが有効になっていることを確認します。「サーバ スコープのインスツルメンテーションのコンフィグレーション」を参照してください。
適切な形式の META-INF/weblogic-diagnostics.xml 記述子ファイルをアプリケーション用に作成します。アプリケーションがデプロイされるたびに自動的に有効化されるモニタを追加する場合、以下のようにします。
<instrumentation> 要素を有効 (<enabled>true</enabled>) にします。
対応可能なアクションがアタッチされた診断モニタを少なくとも 1 つ追加して有効にします(モニタが有効になっており、イベントを生成するアクションがそのモニタにアタッチされている場合にのみ、モニタは診断イベントを生成します)。
各モニタのタイプ用に整形された記述子ファイルのサンプルについては、「代理モニタの記述子ファイルの作成」および「カスタム モニタの記述子ファイルの作成」を参照してください。
ポイントカット式の作成については、「カスタム モニタのポイントカットの定義」を参照してください。
アプリケーション アーカイブに記述子ファイルを格納します。
アプリケーションをデプロイします。「WLDF アプリケーション モジュールのデプロイメント」を参照してください。
以下の点に注意します。
weblogic-diagnostics.xml で定義された診断モニターは、Administration Console の [デプロイメント|<サーバ名>|コンフィグレーション|インスツルメンテーション] ページに表示される。
アプリケーションアーカイブの META-INF/weblogic-diagnostics.xml記述子がモニターを定義する場合、Administration Console を使用することでそれを取り除くことができない。ただし、無効化や有効化は Administration Console でも可能です。
Administration Console から別のモニタを追加できる。Administration Console から追加するモニタは weblogic-diagnostics.xml には保持されず、アプリケーションのデプロイメント プランに保存されます。この方法で追加したモニタは、Administration Console で削除できます。
次に、アプリケーション スコープの代理モニタ用に整形された META-INF/weblogic-diagnostics.xml ファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。この例で定義されているモニタは 1 つ (Servlet_Before_Service) のみですが、記述子ファイルには複数のモニタを定義することができます。
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-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 モニタコンフィグレーションに従って、リクエストがサーバを入れるときには DyeInjection モニタを介してシステム レベルで設定されます。たとえば、DyeInjection モニタが USER1=weblogic 特性によってコンフィグレーションされて、リクエストがユーザ weblogic によって溯源された場合、仕分けベクトルにおける USER1 仕分けフラグは設定されます。
したがって、このアプリケーションの Servlet_Before_Service モニタは、仕分けベクトルを確認し、USER1 フラグ セットを見つけるまで、基本的に何も行いません。このフィルタ処理を実行すれば、生成される診断データの量を減らし、その時点で管理者にとって意味のあるデータのみを生成することができます。
次に、カスタム モニタの整形式 META-INF/weblogic-diagnostics.xml ファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。
コード リスト 10-2 カスタム モニタのコンフィグレーションのサンプル (DIAG_MODULE.xml 内)
<?xml version="1.0" encoding="UTF-8"?> <wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-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-1 では、コード リスト 10-2 のポイントカット式の解析方法を示しています (ワイルドカードの使用に注意してください)。
表 10-6 ポイントカット式のサンプルの説明
ポイントカット式 | 説明 |
---|---|
call( * com.foo.bar.* get* (...)) |
call( ): ジョインポイントがこのポイントカット式の残りで定義されているメソッドが呼び出されたときに、定義されたアクションをトリガする。 |
call( * com.foo.bar.* get* (...)) |
*: 戻り値。ワイルドカードは、メソッドの戻り値の型を問わないことを示す。 |
call( * com.foo.bar.* get* (...)) |
com.foo.bar.*: com.foo.bar クラスとそのサブパッケージのメソッドが当てはまる。 |
call( * com.foo.bar.* get* (...)) |
get* : get という文字列で始まる任意のメソッドが当てはまる。 |
call( * com.foo.bar.* get* (...)) |
(...) : 省略符号は、メソッドで指定できる引数の数に制限がないことを示す。 |
このポイントカット式は、パッケージ com.foo.bar とそのサブパッケージ内にあるすべてのクラスの get*() を一致対象にします。メソッドは、void を含む任意の型の値を返すことができます。また、任意の型の引数を、数に制限なく持つことができます。インスツルメンテーション コードは、これらのメソッドの前に挿入され、そのメソッドが呼び出される直前に、TraceAction アクションが呼び出されます。
ポイントカットの定義に使用する文法の詳細については、「カスタム モニタのポイントカットの定義」を参照してください。
カスタム モニタでは、診断アクションの呼び出し場所を指定するポイントカット式をユーザが作成するので、代理モニタよりも柔軟な操作が可能です。代理モニタの場合は、アクション ライブラリからアクションを選択する必要があります。
ジョインポイントは、精密に定義された、プログラム内の固有の位置です。ポイントカットは、ジョインポイントのセットを指定する式です。この節では、以下のポイントカット構文を使用して、ポイントカットの式を定義する方法について説明します。
カスタム モニタでは 2 種類のポイントカットを指定できます。
call : メソッドが呼び出されると、アクションを実行します。
execution : メソッドが実行されると、アクションを実行します。
ポイントカット式を定義する構文は次のとおりです。
pointcutExpr := orExpr ( 'OR' orExpr ) * orExpr := andExpr ( 'AND' andExpr ) * andExpr := 'NOT' ? termExpr termExpr := exec_pointcut | call_pointcut | '(' pointcutExpr ')' exec_pointcut := 'execution' '(' modifiers? returnSpec classSpecWithAnnotations methodSpec '(' parameterList ')' ')' call_pointcut := 'call' '(' returnSpec classSpec methodSpec '(' parameterList ')' ')' modifiers := modifier ( 'OR' modifier ) * modifier := 'public' | 'protected' | 'private' | 'static' returnSpec := '*' | typeSpec classSpecWithAnnotations := '@' IDENTIFIER ( 'OR' IDENTIFIER ) * | classSpec classSpec := '+' ? classOrMethodPattern | '*' typeSpec := ( primitiveType | classSpec ) ( '[]' )* methodSpec := classOrMethodPattern parameterList := param ( ',' param ) * param := typeSpec | '...' primitiveType := 'byte' | 'char' | 'boolean' | 'short' | 'int' | 'float' | 'long' | 'double' | 'void' classOrMethodPattern := '*' ? IDENTIFIER '*'? | '*'
以下のルールが適用されます。
ワイルドカード (*) は、クラスの型やメソッド名に使用できます。
引数リストの省略符号 (...) は、その引数以外に任意の型の引数がいくつか (数は可変) あることを示します。
クラスの型に付けられた + (プラス記号) プレフィックスは、指定したクラス/インタフェース パターンを実装しているすべてのサブクラス、サブインタフェース、または具象クラスを示します。
ポイントカット式は、適合するジョインポイントを識別するパターンを指定します。パターンに対してジョインポイントを適合させると、有効な適合かどうかを示すブール型の値が返されます。
ポイントカット式は、AND、OR、または NOT ブール演算子と組み合わせて、複雑なポイントカット式ツリーを構築できます。
たとえば、以下のポイントカットは、パッケージ 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>
実行ポイントのクラス指定子やメソッド指定子で JDK スタイルのアノテーションを使用することができます。「@」で始まるクラス指定子またはメソッド指定子はアノテーション名として解釈されます。
クラス指定子として使用したアノテーションは、@ が付けられたすべてのクラスに一致します。このマッチを行う際は、アノテーション名のみが考慮され、アノテーション属性は無視されます。
たとえば、次のポイントカットを考えます。
execution(public void @Service @Invocation (...)
これは以下のメソッドに一致します。
パブリック メソッド
void を返すメソッド
@Service のアノテーションが付けられたクラスに含まれるメソッド
@Invocation のアノテーションが付けられたメソッドを持つメソッド
任意の数の引数を持つメソッド
注意 : アノテーションベースの指定子は、実行ポイントカットでのみ使用できます。呼び出しポイントカットでは使用できません。 |
アノテーションベースのクラス指定子およびメソッド指定子では、以下のワイルドカードを使用できます。
* : あらゆるものに一致します。
先頭の * : 指定した文字列で終わるクラス/インタフェースまたはメソッドの名前に一致します。たとえば、「*Bean」は、weblogic.management.configuration.ServerMBean に一致します。
最後の * : 指定した文字列で始まるクラス/インタフェースまたはメソッドの名前に一致します。たとえば、「weblogic.*」は、weblogic およびそのサブパッケージ内のすべてのクラスおよびインタフェースに一致します。
ポイントカットは、内部クラスの名前に基づいて指定できます。次に例を示します。
public class Foo { class Bar { public int getValue() {...} } }
内部クラス Bar の getValue メソッドをカバーするポイントカットは、次の指定で定義できます。
execution (public int Foo$Bar getValue(...));
ワイルドカードを使うこともできます。次に例を示します。
execution ( * Foo$Bar get*(...));
これは、クラス Foo の内部クラス Bar のゲッター メソッドにのみ一致します。
以下のように先頭と末尾にワイルドカードを使用することもできます。
execution ( * Foo$Ba* get*(...)); execution ( * *oo$Bar get*(...)); execution ( * *oo$Ba* get*(...));
これも、クラス Foo$Bar のゲッター メソッドに一致します。