WebLogic 診断フレームワークのコンフィグレーションと使い方
![]() |
![]() |
![]() |
![]() |
WLDF インスツルメンテーション コンポーネントは、要求をユニークに識別し、システム内でのフローに従って要求を追跡する手段として利用できます。システムに届くすべての要求の一定の特性 (発信側ユーザやクライアント アドレスなど) をチェックして、その要求に「コンテキスト」をアタッチするように、WLDF をコンフィグレーションできます。コンテキストは、ユニークな ID と、その要求の特性を表すフラグによって定義されます。コンテキスト ID はログに記録して、以下のことに使用できます。
診断コンテキストは、システム レベルでもアプリケーション レベルでも利用できますが、コンフィグレーション方法と使用方法に若干の違いがあります。
以下の節では、診断コンテキストのコンフィグレーションと使用のプロセスについて説明します。
診断コンテキストには、ユニークなコンテキスト ID と、コンテキストの特性を識別する仕分けベクトルが含まれます。
要求の診断コンテキストはその要求がシステムに参加したとき (たとえばクライアントで HTTP 要求を発行したとき) に作成され、初期化されます。このコンテキストは、要求がスレッド境界や Java 仮想マシン (Java Virtual Machine : JVM) 境界を越えてもアタッチされ続けます。診断コンテキストは、要求のライフ サイクル全体を通して存続します。
すべての診断コンテキストは、ドメイン内でユニークな ID によって識別されます。この ID が要求に付随して移動するので、システム内でのフローに従って所定の要求を追跡できます。
コンテキスト情報は、64 ビットの仕分けベクトルとして要求と共に移動します。それぞれのビットは仕分けの存在を識別するフラグです。各仕分けが要求の 1 つの属性 (発信したユーザ、発信したクライアント IP アドレス、アクセス プロトコルなど) を表します。
特定の属性に対応する仕分けフラグが設定されている場合、その属性が存在することを示しています。フラグが設定されていない場合、その属性が存在しないことを示しています。
例として、要求の発信元が IP アドレス 127.0.0.1 であることを示すために仕分け ADDR1 がコンフィグレーションされているコンフィグレーションについて検討します。要求の発信元が IP アドレス 127.0.0.2 であることを示すために仕分けフラグ ADDR2
がコンフィグレーションされています。IP アドレス 127.0.0.1 からの要求がシステムに参加すると、その要求の仕分けベクトルの ADDR1
仕分けフラグが設定されます。ADDR2
仕分けフラグは設定されていないままの状態です。
診断コンテキストを利用する診断機能やモニタ機能では、属性が存在するかどうかを判断する目的で仕分けベクトルを調べられます。上記の例では、管理者は診断モニタをコンフィグレーションして、ADDR1
仕分けの設定されたすべての要求、つまり IP アドレス 127.0.0.1 から発信されたすべての要求を追跡できます。
また、仕分けベクトルには THROTTLE
仕分けもあります。この仕分けは、受信する要求に仕分けを設定する頻度を指定するために使用します。この特別な仕分けの詳細については、「THROTTLE 仕分けフラグ」を参照してください。
利用できる仕分けとそれによって表される属性のリストについては、「DyeInjection モニタでサポートされる仕分け」を参照してください。仕分けベクトルをコンフィグレーションおよび使用するプロセスについては、この章の以降の節で説明します。
診断コンテキストは、診断モジュールの一部としてコンフィグレーションされます。診断コンテキストをコンフィグレーションするための主なメカニズムは、標準の診断モニタである DyeInjection
モニタです。DyeInjection
モニタがコードにウィービングされるジョインポイントは、要求がシステムに参加する可能性のある場所です。診断アクションによって、各要求が DyeInjection
モニタのコンフィグレーションに照らしてチェックされてから、その要求にコンテキストが作成されてアタッチされ、必要に応じた仕分けフラグが設定されます。診断モニタのタイプ、(ジョインポイントを定義する) ポイントカット、および診断アクションについては、「インスツルメンテーションのコンフィグレーション」を参照してください。
ここでは、サーバ スコープの診断モジュールにおけるコンテキストのコンフィグレーションと使用について概説します。
DyeInjection
モニタをコンフィグレーションします。たとえば、USER1=
username1
、USER2=
username2
、ADDR1=
ip_address1
、ADDR2=
ip_address2
、などのように指定します。DyeInjection
モニタによってその要求が調べられ、仕分けベクトルの仕分けの値に一致する属性があるか、ある場合にはどの値と一致するかが確認されます。たとえば、要求の発信者が username1
か username2
か、また要求の発信元が ip_address1
か ip_address2
か、などを確認するためのチェックが行われます。DyeInjection
モニタによりその仕分けが要求に「挿入」されます。つまり、要求にアタッチされる仕分けベクトルにあるその仕分け用の仕分けフラグが設定されます。たとえば、要求が username2
によって ip_address1
から発信された場合、DyeInjection
モニタにより仕分けフラグ USER2
と ADDR1
が設定されます (USER1
と ADDR2
は設定されていない状態のままになります)。USER2
と ADDR1
) のみが仕分けベクトルに含まれます。 注意 : すべての仕分けベクトルには、暗黙的に PROTOCOL
仕分け群の 1 つも含まれます。これについては、「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」で説明します。
要求のコンテキストを作成するには、次の手順を行う必要があります。
DyeInjection
モニタをコンフィグレーションするには、仕分けベクトルの仕分けに値を割り当てます。利用できる仕分けフラグについては、表 11-1 で説明します。受信する要求用のコンテキスト作成のために WLDF で要求を評価する際、WLDF では仕分けベクトルに指定されている値の存在をチェックします。値が存在する場合、そのフラグが WLDF によって設定されます。このプロセスが要求の仕分け、または要求への仕分けの挿入と呼ばれます。
たとえば、IP アドレスが 127.0.0.1 のクライアントから admin@avitek
というユーザによって開始されたすべての要求をモニタするには、値 admin@avitek
を USER1
に、値 127.0.0.1 を ADDR1
に割り当てます。その結果、ユーザ admin@avitek
が IP アドレス 127.0.0.1 のクライアントから要求を開始すると、その要求には USER1
および ADDR1
という仕分けが設定されます。すなわち、(要求のコンテキスト内の) 仕分けベクトルの USER1
フラグと ADDR1
フラグが両方とも設定された状態になります。
Administration Console で仕分けに値を割り当てるには、[DyeInjection の設定] ページの [プロパティ] フィールドに値を入力します。
図 11-1 Administration Console における仕分けの値の設定
これらの設定は、診断モジュールの記述子ファイルでは以下のコード リストに示すように表されます。
コード リスト 11-1 DyeInjection モニタのコンフィグレーションのサンプル (DIAG_MODULE.xml 内)
<wldf-resource>
<name>MyDiagnosticModule</name>
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>DyeInjection</name>
<enabled>true</enabled>
<dye-mask xsi:nil="true"></dye-mask>
<properties>ADDR1=127.0.0.1
USER1=admin@avitek
</properties>
</wldf-instrumentation-monitor>
<!-- インスツルメンテーションをコンフィグレーションするための他の要素 -->
<instrumentation>
<!-- この診断モニタをコンフィグレーションするための他の要素 -->
<wldf-resource>
仕分けベクトルで利用できる仕分けについて、以下の表にリストして説明します。
|
|
|
|
|
|
|
|
|
|
|
|
|
DyeInjection
モニタの仕分けフラグ USER
n
、ADDR
n
、COOKIE
n
、および CONNECTOR
n
については、明示的に値を設定する必要があります。一方、フラグ PROTOCOL_HTTP
、PROTOCOL_IIOP
、ROTOCOL_JRMP
、PROTOCOL_RMI
、PROTOCOL_SOAP
、PROTOCOL_SSL
、および PROTOCOL_T3
は、WLDF により暗黙的に設定されます。DyeInjection
モニタが有効になっていれば、すべての要求に適切なプロトコルの仕分けが挿入されます。たとえば、HTTP によって届いた要求にはすべて仕分け PROTOCOL_HTTP
が挿入されます。
THROTTLE
仕分けフラグを使用して、受信する要求のうち仕分けを設定するものの量を制御できます。THROTTLE
は他のフラグとは異なる方法でコンフィグレーションされ、WLDF での使用方法も異なります。詳細については、「インスツルメンテーション イベントの量を制御するスロットル機能の使い方」を参照してください。
診断モジュールで DyeInjection
モニタが有効になっている場合、受信するすべての要求について診断コンテキストが作成されます。DyeInjection
モニタに明示的に設定されているプロパティがない場合でも、ユニークなコンテキスト ID と、暗黙的な PROTOCOL
仕分け群のうち 1 つが指定された仕分けベクトルがすべての要求のコンテキストに含まれます。DyeInjection
モニタが診断モジュールに追加されていないか、無効になっている場合、受信するどの要求についても診断コンテキストは作成されません。
DyeInjection
モニタを、診断モジュールの代理診断モニタまたはカスタム診断モニタのトリガ条件を制限するメカニズムとして使用できます。このプロセスを仕分けフィルタと呼びます。
それぞれのモニタに仕分けマスクを設定できます。仕分けマスクには DyeInjection
モニタから選択された仕分けが指定されます。診断モニタに対して仕分けフィルタが有効になっている場合、マスクに設定された条件に一致する要求でのみモニタの診断アクションがトリガされます。
例として、TraceAction
アクションがアタッチされている JDBC_Before_Start_Internal
診断モニタについて検討します。仕分けフィルタが有効になっていない場合、JDBC_Before_Start_Internal
で処理されるすべての要求によって TraceAction
がトリガされます。一方、仕分けマスクを使用すると、以下に示すとおり IP アドレス 127.0.0.1
から発信された要求のみで TracAction
をトリガするように指定することも可能です。
DyeInjection
モニタで ADDR1=127.0.0.1
とコンフィグレーションして、DyeInjection
モニタを有効にします。詳細については、「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」を参照してください。JDBC_Before_Start_Internal
診断モニタの仕分けフィルタを有効にします。Administration Console では、以下の説明および図 11-2 に示すように、[JDBC_Before_Start_Internal
の設定] ページでこの作業を行います。 このコンフィグレーションでは、IP アドレス 127.0.0.1
から発信された要求でのみ JDBC_Before_Start_Internal
診断モニタの TraceAction
アクションがトリガされます。
図 11-2 Administration Console における仕分けフィルタの設定
これらの設定は、診断モジュールの記述子ファイルでは以下のコード リストに示すように表されます。
コード リスト 11-2 代理モニタで仕分けフィルタを使用するコンフィグレーションのサンプル (DIAG_MODULE.xml 内)
<wldf-resource>
<name>MyDiagnosticModule</name>
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>DyeInjection</name>
<enabled>true</enabled>
<properties>ADDR1=127.0.0.1</properties>
</wldf-instrumentation-monitor>
<wldf-instrumentation-monitor>
<name>JDBC_Before_Start_Internal</name>
<dye-mask>ADDR1</dye-mask>
<dye-filtering-enabled>true</dye-filtering-enabled>
<action>TraceAction</action>
</wldf-instrumentation-monitor>
<!-- インスツルメンテーションをコンフィグレーションするための他の要素 -->
<instrumentation>
<!-- 診断モニタをコンフィグレーションするための他の要素 -->
<wldf-resource>
要求にアタッチされる仕分けベクトルには複数の仕分けを指定でき、代理モニタにアタッチされる仕分けマスクにも複数の仕分けを指定できます。代理モニタの仕分けマスクを使用して、モニタが要求に対してアクションを実行できるようにするには、以下の条件をすべて満たしている必要があります。
DyeInjection
モニタが有効になっている (DyeInjection
モニタが追加されていないか無効になっている場合、仕分けフィルタは無効になります)。weblogic-diagnostics.xml
記述子で、代理モニタまたはカスタム モニタの仕分けフィルタが有効になっている。図 11-3 では、3 つの診断モニタを持つ診断モジュールを使用した仕分けフィルタの仕組みを示しています。
DyeInjection
モニタは次のようにコンフィグレーションされている。Servlet_Around_Service
モニタには、ADDR1
のみを含む仕分けマスクがコンフィグレーションされている。EJB_Around_SessionEjbBusinessMethods
モニタには、USER1
のみを含む仕分けマスクがコンフィグレーションされている。127.0.0.1
からユーザ guest
によって開始された要求がシステムに届きます。ユーザ guest
は DyeInjection
モニタの USER1
の値に一致しないため、この要求は仕分けベクタ USER1
で仕分けされません。発信元 IP アドレス (127.0.0.1
) は DyeInjection
モニタで定義された ADDR1
の値に一致するため、要求は仕分けベクタ ADDR1
で仕分けされます。 ADDR1
で仕分け済み) が Servlet
コンポーネントに届きます。このコンポーネントでは、診断モニタ Servlet_Around_Service
がコード内にウィービングされています (Servlet_Around_Service
は特定のサーブレット メソッドまたは JSP メソッドの入り口と出口で、診断アクションをトリガします)。このモニタでは仕分けモニタが有効になっており、仕分けマスクには ADDR1
という値が 1 つ定義されています。Servlet_Around_Service
でインスツルメンテーションされているメソッドに要求が入るか出るときに、診断モニタは要求に仕分けベクトル ADDR1
があるかどうかをチェックし、その仕分けベクトルが見つかります。その結果、モニタは診断アクションをトリガします。ログへのデータの書き込みなどの診断イベントが発生します。
スロットル機能を使用すると、診断モジュールのモニタで処理される要求の数を制御できます。スロットル機能は、DyeInjection
モニタに定義される THROTTLE
仕分けを使用してコンフィグレーションします。
注意 : USER
n
および ADDR
n
仕分けを使用すると、特定のユーザまたは IP アドレスからの要求を調べることができます。ただし、任意のユーザ トランザクションを調べる手段にはなりません。THROTTLE
仕分けでは、要求のサンプリングによりその機能を提供します。
仕分けベクトルの他の仕分けと異なり、THROTTLE
仕分けは 2 つのプロパティを通じてコンフィグレーションされます。
THROTTLE_INTERVAL
に、新しく受信される要求に THROTTLE
仕分けが指定されるまでの間隔 (ミリ秒) を設定する。 THROTTLE_INTERVAL
が 0
より大きい場合、DyeInjection
モニタでは、最後に THROTTLE
仕分けが指定された要求が届いてから少なくとも THROTTLE_INTERVAL
のミリ秒数だけ経過した後に受信された要求に対して、その新しい要求の仕分けベクトルにある THROTTLE
仕分けフラグが設定されます。たとえば THROTTLE_INTERVAL=3000
と指定した場合、DyeInjection
モニタでは少なくとも 3000 ミリ秒の待機後に、受信したリクエストに THROTTLE
仕分けが指定されます。
THROTTLE_RATE
に、新しく受信される要求に THROTTLE
仕分けが指定される度合い (受信される要求の数で表す) を設定する。 THROTTLE_INTERVAL
と THROTTLE_RATE
は併用できます。いずれかの要求を満たす場合、要求は THROTTLE
仕分けで仕分けされます。
THROTTLE_INTERVAL
または THROTTLE_RATE
のどちらかに値を割り当てる場合 (両方に割り当てることもどちらにも割り当てないことも可)、THROTTLE
仕分けがコンフィグレーションされます。Administration Console での THROTTLE
コンフィグレーションの設定を、以下の図に示します。
図 11-4 THROTTLE 仕分けのコンフィグレーション
コード リスト 11-3 に、結果として診断モジュールの記述子ファイルに記述されるコンフィグレーションを示します。
コード リスト 11-3 DyeInjection モニタの THROTTLE コンフィグレーションのサンプル (DIAG_MODULE.xml 内)
<wldf-resource>
<name>MyDiagnosticModule</name>
<instrumentation>
<wldf-instrumentation-monitor>
<name>DyeInjection</name>
<properties>
THROTTLE_INTERVAL=3000
THROTTLE_RATE=6
</properties>
</wldf-instrumentation-monitor>
</instrumentation>
<!-- この診断モニタをコンフィグレーションするための他の要素 -->
</wldf-resource>
コード リスト 11-4 に、仕分けマスクに THROTTLE
仕分けが設定されている JDBC_Before_Start_Internal
代理モニタのコンフィグレーションを示します。
コード リスト 11-4 代理モニタの仕分けマスクに THROTTLE を設定するコンフィグレーションのサンプル (DIAG_MODULE.xml 内)
<wldf-resource>
<name>MyDiagnosticModule</name>
<instrumentation>
<wldf-instrumentation-monitor>
<name>JDBC_Before_Start_Internal</name>
<enabled>true</enabled>
<dye-mask>THROTTLE</dye-mask>
</wldf-instrumentation-monitor>
</instrumentation>
<!-- この診断モニタをコンフィグレーションするための他の要素 -->
</wldf-resource>
仕分けマスクおよび仕分けフィルタによるメカニズムを使用して、代理モニタおよびカスタム モニタで処理するために渡す要求を、要求のプロパティに基づいて制限できます。「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」で説明したように、要求におけるプロパティの存在は仕分けの存在によって示されます。THROTTLE
仕分けもそうした仕分けの 1 つと見なされるため、THROTTLE
も他の仕分けと同様にフィルタできます。
THROTTLE
仕分けが含まれても含まれなくても構いません。仕分けマスクに THROTTLE
が含まれる場合、モニタに渡される要求の仕分けベクトルにも THROTTLE
が含まれている必要があります。一方、仕分けマスクに THROTTLE
が含まれない場合、要求の仕分けベクトルに THROTTLE
が含まれているかどうかに関わらず、適格な要求はすべてモニタに渡されます。DyeInjection
モニタに THROTTLE
プロパティが設定されていない場合、仕分けフィルタもスロットル機能も実行されない。DyeInjection
モニタに THROTTLE
がコンフィグレーションされている場合、代理モニタでは仕分けマスクが無視されるが、すべての要求について THROTTLE
仕分けの存在がチェックされる。THROTTLE
仕分けの指定された要求のみが代理モニタに渡されて処理されます。したがって、THROTTLE_RATE
または THROTTLE_INTERVAL
(あるいはその両方) を DyeInjection
モニタに設定すると、すべての代理モニタで処理される要求の数が減少します。スロットル機能を利用するために、すべての代理モニタに仕分けマスクをコンフィグレーションする必要はありません。THROTTLE
のみの場合、THROTTLE
仕分けが指定されている要求のみが代理モニタに渡される。この動作は、仕分けフィルタが有効でなく DyeInjection
モニタに THROTTLE
がコンフィグレーションされている場合と同じです。
weblogic.diagnostics.context
パッケージを使用すると、アプリケーションから診断コンテキストに制限付きでアクセスできます。
アプリケーションでは一連の weblogic.diagnostics.context.DiagnosticContextHelper
API を使用して、以下の関数を実行できます。
DYE_0
から DYE_7
までのフラグについての設定または設定の解除 (これらのフラグ ビットを XML を介して設定する方法はありません。DyeInjection
モニタの <properties>
をコンフィグレーションすると、アプリケーション固有でないフラグ ビットについて XML を介して設定できますが、仕分けベクトルの DYE_0
から DYE_7
までを設定できるのは setDye()
メソッドのみです)。アプリケーションで DYE_0
から DYE_7
までのフラグのうち 1 つまたは複数を設定した時点以降には、モニタや別のアプリケーションでそれらのフラグをチェックするように仕分けマスクを設定し、そのフラグ (群) がコンテキストの仕分けベクトルに存在する場合にアクションを実行できます。診断コンテキストにペイロードがアタッチされている場合、モニタで実行されるアクションはペイロードに格納されてアーカイブ化され、結果としてアクセサ コンポーネントを通じて利用できるようになります。
コード リスト 11-5 は、診断コンテキストを (暗黙的に) 作成し、コンテキスト ID を出力して、DYE_0
フラグの値をチェックした上で設定する簡単なサンプルです。
コード リスト 11-5 サンプル : DiagnosticContextExample.java
package weblogic.diagnostics.examples;
import weblogic.diagnostics.context.DiagnosticContextHelper;
public class DiagnosticContextExample {
public static void main(String args[]) throws Exception {
System.out.println("\nContextId=" +
DiagnosticContextHelper.getContextId());
System.out.println("isDyedWith(DYE_0)=" +
DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));
DiagnosticContextHelper.setDye(DiagnosticContextHelper.DYE_0, true);
System.out.println("isDyedWith(DYE_0)=" +
DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));
}
}
![]() ![]() |
![]() |
![]() |