13 診断コンテキストを管理するためのDyeInjectionモニターの構成
診断コンテキストは、リクエストの特性を表す64ビットの仕分けベクトルと一意のコンテキストIDから構成されます。特定のリクエストに関連付けられたコンテキストIDはイベント・アーカイブに記録され、以下の処理に使用できます。
-
インストゥルメンテーション・イベントの生成を調整します。つまり、指定された条件に一致する場合のイベントの生成頻度を決定します。
-
ログ・レコードをリクエストに関連付けます。
-
WLDFアクセサ・コンポーネントを使用して、ログ・レコードやイベント・レコードの検索をフィルタ処理します(「データ・アクセサを使用した診断データへのアクセス」を参照)。
WLSTを使用してDyeInjectionモニターを動的に作成する方法の例は、「サンプル: DyeInjectionモニターの動的な作成」を参照してください。
この章には次の項が含まれます:
- 診断コンテキストの内容、ライフサイクル、構成
診断コンテキストには、一意のコンテキストIDおよび64ビットの仕分けベクトルが含まれます。仕分けベクトルには、リクエストに関連した診断コンテキストの特性を識別するために設定されるフラグが含まれます。 - プロセスの概要
DyeInjectionモニターはリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。DyeInjectionモニターを構成して、リクエストを特定してその流れを追跡できます。リクエストの追跡は、システムを通過するリクエストがどのように処理されるか確認するために役立ちます。 - DyeInjectionモニターによる仕分けベクトルの構成
DyeInjectionモニターを使用して仕訳ベクトルを構成し、システム内のリクエストをモニターします。すべてのリクエストがDyeInjectionモニターの構成に対してチェックされ、診断コンテキストが作成されてリクエストにアタッチされます。 - 仕分けフィルタ処理を使用するための委任モニターの構成
DyeInjectionモニターを、診断モジュールの委任診断モニターまたはカスタム診断モニターのトリガー条件を制限するメカニズムとして使用できます。このプロセスを仕分けフィルタ処理と呼びます。 - 仕分けマスクによるモニターへ渡すリクエストのフィルタ方法
リクエストにアタッチされる仕分けベクトルには複数の仕分けを指定でき、委任モニターにアタッチされる仕分けマスクにも複数の仕分けを指定できます。 - インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法
スロットル機能を使用すると、診断モジュールのモニターで処理されるリクエストの数を制御できます。 - weblogic.diagnostics.contextの使用
weblogic.diagnostics.contextパッケージを使用すると、アプリケーションから診断コンテキストにアクセスできます。
診断コンテキストの内容、ライフサイクル、構成
診断コンテキストには、一意のコンテキストIDおよび64ビットの仕分けベクトルが含まれます。仕分けベクトルには、リクエストに関連した診断コンテキストの特性を識別するために設定されるフラグが含まれます。
現在、仕分けベクトルの32ビットが使用可能な各仕分けフラグにつき1つずつ使用されています(表13-1を参照してください)。
コンテキストのライフ・サイクルとコンテキストID
リクエストの診断コンテキストはそのリクエストがシステムに参加したとき(たとえばクライアントでHTTPリクエストを発行したとき)に作成され、初期化されます。診断コンテキストは、リクエストがスレッド境界やJava仮想マシン(Java Virtual Machine JVM)境界を超えてもそのリクエストにアタッチされ続けます。診断コンテキストは、リクエストのライフ・サイクル全体を通して存続します。
すべての診断コンテキストは、ドメイン内で一意のコンテキストIDによって識別されます。このコンテキストIDはリクエストと共に移動するため、特定のリクエストがシステムで処理される過程でそのリクエストに関連付けられたイベントやログ・エントリを特定することができます。
親トピック: 診断コンテキストの内容、ライフサイクル、構成
仕分け、仕分けフラグ、仕分けベクトル
コンテキスト情報は、64ビットの仕分けベクトルとしてリクエストと共に移動します。それぞれのビットは仕分けの存在を識別するフラグです。各仕分けがリクエストの1つの属性(発信したユーザー、発信したクライアントIPアドレス、アクセス・プロトコルなど)を表します。
特定の属性に対応する仕分けフラグが設定されている場合、その属性が存在することを示しています。フラグが設定されていない場合、その属性が存在しないことを示しています。
たとえば、次のような構成を考えます:
-
リクエストの発信元がIPアドレス127.0.0.1であることを示すために仕分けフラグADDR1が構成されています。
-
リクエストの発信元がIPアドレス127.0.0.2であることを示すために仕分けフラグADDR2が構成されています。
-
USER1フラグは、ユーザーadmin@avitek.comからのリクエストを示すために構成されます。
IPアドレス127.0.0.1からのリクエストがシステムに参加すると、そのリクエストの仕分けベクトルのADDR1仕分けフラグが設定されます。ADDR2とUSER1仕分けフラグは設定されません。
admin@avitek.comからのリクエストが127.0.0.1か127.0.0.2以外のIPアドレスからのシステムを登録する場合、リクエストに対して仕分けベクトルにUSER1フラグが設定されます。ADDR1とADDR2仕分けフラグは設定されません。
admin@avitek.comからのリクエストが127.0.0.2のIPアドレスからシステムを登録する場合、リクエストに対する仕分けベクトルにUSER1とADDR2フラグが設定されます。ADDR1フラグは設定されません。
診断コンテキストを利用する診断およびモニター機能では、仕分けベクトルを調査することにより、1つまたは複数の属性が存在する(すなわち、関連付けられたフラグが設定されている)かどうかを特定することができます。前述の例では、診断モニターを構成して、ADDR1仕分けの設定されたすべてのリクエスト、つまりIPアドレス127.0.0.1から発信されたすべてのリクエストをトレースできます。また、ADDR1とUSER1の両方の仕分けの設定されたすべてのリクエスト、つまりIPアドレス127.0.0.1のユーザーadmin@avitek.comから発信されたすべてのリクエストをトレースする診断モニターを構成することもできます(127.0.0.1の他のユーザーからのリクエストはトレースされません)。
また、仕分けベクトルには受信するリクエストに対して仕分け頻度を指定するTHROTTLE仕分けもあります。この特別な仕分けの詳細は、「THROTTLE仕分けフラグ」を参照してください。
利用できる仕分けとそれによって表される属性のリストについては、「DyeInjectionモニターでサポートされる仕分け」を参照してください。仕分けベクトルを構成および使用するプロセスについては、この章の次の項で説明します。
親トピック: 診断コンテキストの内容、ライフサイクル、構成
診断コンテキストが構成される場所
診断コンテキストは、診断モジュールの一部として構成されます。診断コンテキストを構成するのにサーバー・レベルにDyeInjectionモニターを使用します。DyeInjectionモニターは標準の診断モニターであるため、その動作は変更できません。DyeInjectionモニターがコードにウィービングされるジョインポイントは、リクエストがシステムに参加する可能性のある場所です。
診断アクションによって、各リクエストがDyeInjectionモニターの構成に対してチェックされてから、そのリクエストにコンテキストが作成されてアタッチされ、必要に応じた仕分けフラグが設定されます。リクエストに設定される仕分けフラグが、下流の診断モニターに対して構成される仕分けフラグに適合する場合、リクエストの関連Context IDがあるイベントはEventアーカイブに追加されます。たとえば、リクエストがUSER1とADDR1仕分けフラグのみを設定し、USER1とADDR1フラグ設定の両方で対してリクエストを追跡するための構成された診断モニターがある場合(他に設定されたフラグがない)イベントはEventアーカイブに追加されます。
診断モニターのタイプ、(ジョインポイントを定義する)ポイントカット、および診断アクションについては、「インストゥルメンテーションの構成」を参照してください。
親トピック: 診断コンテキストの内容、ライフサイクル、構成
プロセスの概要
DyeInjectionモニターはリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。DyeInjectionモニターを構成して、リクエストを特定してその流れを追跡できます。リクエストの追跡は、システムを通過するリクエストがどのように処理されるか確認するために役立ちます。
ここでは、サーバー・スコープの診断モジュールにおけるコンテキストの構成と使用について概説します。
-
DyeInjectionモジュールを介して仕分けベクトルを構成します。「DyeInjectionモニターを介した仕分けベクトルの構成」を参照してください。
-
システムにリクエストが入ると、そのリクエストの診断コンテキストがWLDFによって作成されインスタンス化されます。このコンテキストには、一意のコンテキストIDと仕分けベクトルが含まれます。
-
DyeInjectionモニターは、WLDF診断モジュール内でシステム・レベルで有効化されている場合、そのリクエストを調査して、仕分けベクトルで構成されている仕分け値のいずれかがリクエストの属性と一致しているかどうかを確認します。たとえば、そのリクエストの発行元がUSER1またはUSER2に関連付けられているユーザーかどうか、およびADDR1またはADDR2に関連付けられているIPアドレスかどうかが確認されます。
-
DyeInjectionモニターは、リクエストの属性に一致する各仕分け値について、診断コンテキスト内で関連付けられている仕分けビットを設定します。たとえば、DyeInjectionモニターが、
USER1=
weblogic
、USER2=
admin@avitek.com
、ADDR1=127.0.0.1
、ADDR2=
127.0.0.2
のように構成されており、リクエストの発行元がIPアドレス127.0.0.2のユーザーweblogicである場合、仕分けベクトル内でUSER1およびADDR2仕分けビットが設定されます。 -
リクエストがシステム内を移動する過程では、仕分けベクトルを持つ診断コンテキストもそのリクエストと共に移動します。この64ビットの仕分けベクトルの内容はフラグのみで、値は含まれません。そのため、この例では明示的に設定した2つのフラグUSER1とADDR2のみが仕分けベクトルに含まれます。これにはUSER1とADDR2に関する実際のユーザー名とIPアドレスは含まれていません。
ノート:
すべての仕分けベクトルには、暗黙的にPROTOCOL仕分け群の1つも含まれます。これについては、「DyeInjectionモニターを介した仕分けベクトルの構成」で説明します。
-
管理者は下流のコード内で診断モニター(アプリケーション・スコープまたはサーバー・スコープの診断モニター)がアクティブとなるように構成し、モニターの仕分けマスクをUSER1およびADDR2と設定します。詳細は、「仕分けフィルタを使用するための委任モニターの構成」,を参照してください。
-
診断モニターは、診断コンテキストの仕分けベクトルで設定されている仕分けフラグが診断モニターの仕分けマスクと一致すると、関連付けられている1つまたは複数のアクションを実行します。詳細は、「仕分けマスクによるモニターへ渡すリクエストのフィルタ方法」,を参照してください。この例では、USER1とADDR2フラグが仕分けベクトルに設定されていると、モニターは動作を実行します。さらに、リクエストに関連するイベントがイベント・アーカイブに書き込まれます。
DyeInjectionモニターによる仕分けベクトルの構成
DyeInjectionモニターを使用して仕訳ベクトルを構成し、システム内のリクエストをモニターします。すべてのリクエストがDyeInjectionモニターの構成に対してチェックされ、診断コンテキストが作成されてリクエストにアタッチされます。
システムに参加するすべてのリクエストに対して診断コンテキストを作成するには:
- 「診断モジュールのサマリー」ページで、モニターする1つまたは複数のサーバー用に診断モジュールを作成します。「組込みに基づいたカスタム診断システム・モジュールの作成」を参照してください。
- 新規に作成したモジュールの名前をクリックして、「<MODLE_NAME>の設定」ページを開きます。
- 「構成 - インストゥルメンテーション」タブで、「有効」チェック・ボックスを選択します。
- 「このモジュールの診断モニター」タブで、「追加と削除」ボタンを使用してDyeInjectionモニターを追加します。
- DyeInjectionモニターをクリックして、「DyeInjectionの設定」ページを開きます。
- 「有効化」チェック・ボックスを選択します。(1つの診断モジュールで同時に使用できるDyeInjectionモニターは1つのみ。)
DyeInjectionモニターを構成するには、仕分けに値を割り当てます。使用できる仕分けフラグについては、表13-1を参照してください。
たとえば、USER1=
weblogic
、USER2=
admin@avitek.com
、ADDR1=
127.0.0.1
、ADDR2=
127.0.0.2
などのようにフラグを設定できます。基本的に、モニターするリクエストの発行元となる1人または複数のユーザー、1つまたは複数のIPアドレスに対して1つまたは複数のフラグの値を設定します。
たとえば、IPアドレスが127.0.0.1のクライアントからadmin@avitek
というユーザーによって開始されたすべてのリクエストをモニターするには、値admin@avitek
をUSER1
に、値127.0.0.1をADDR1
に割り当てます。
WebLogic Server管理コンソールで、「DyeInjectionの設定」ページの「プロパティ」フィールドに値を入力して、仕分けに値を割り当てます。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプの診断システム・モジュールでの診断監視の構成に関する項を参照してください。
これらの設定は、診断モジュールの記述子ファイルでは以下の例に示すように表されます。
例13-1 DIAG_MODULE.xml内のDyeInjectionモニターの構成の例
<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> <!-- Other elements to configure instrumentation --> <instrumentation> <!-- Other elements to configure this diagnostic monitor --> <wldf-resource>
DyeInjectionモニターでサポートされる仕分け
仕分けベクトルで利用できる仕分けについて、以下の表にリストして説明します。
表13-1 サポートされる診断コンテキストの仕分けと対応するリクエストのプロトコル
仕分けフラグ | 説明 |
---|---|
ADDR1 ADDR2 ADDR3 ADDR4 |
仕分けADDR1、ADDR2、ADDR3、およびADDR4を使用して、リクエストを発信したクライアントのIPアドレスを指定します。DyeInjectionモニターのプロパティ(ADDR1、ADDR2、ADDR3、ADDR4)に指定されているIPアドレスからリクエストが発信されると、それぞれ対応する仕分けフラグがそのリクエストの診断コンテキストに設定されます。 これらの仕分けを使用してDNS名を指定することはできません。 |
CONNECTOR1 CONNECTOR2 CONNECTOR3 CONNECTOR4 |
仕分けCONNECTOR1、CONNECTOR2、CONNECTOR3、およびCONNECTOR4を使用して、コネクタ・ドライバの特性を識別します。 これらの仕分けフィルタは、コネクタ・ドライバによって状況に特有のリクエストのプロパティを識別するために設定されます。これらは、ユーザーがWebLogic Server管理コンソールまたは記述子ファイルに直接構成するものではありません。これらの仕分けにはコネクタ・ドライバによって(コネクタAPIを使用して)値が割り当てられ、その結果、接続に関する情報が診断コンテキストに保持されて運ばれます。 |
COOKIE1 COOKIE2 COOKIE3 COOKIE4 |
COOKIE1、COOKIE2、COOKIE3、およびCOOKIE4は、HTTP/Sリクエストにweblogic.diagnostics.dyeというCookieが含まれていて、その値がDyeInjectionモニターのそれぞれに対応するプロパティ(COOKIE1、COOKIE2、COOKIE3、COOKIE4)の値と同じ場合に、そのリクエストの診断コンテキストに設定されます。 |
DYE_0 DYE_1 DYE_2 DYE_3 DYE_4 DYE_5 DYE_6 DYE_7 |
DYE_0からDYE_7は、アプリケーションの開発者のみが使用できます。「weblogic.diagnostics.contextの使用」を参照してください。 |
PROTOCOL_HTTP PROTOCOL_IIOP PROTOCOL_JRMP PROTOCOL_RMI PROTOCOL_SOAP PROTOCOL_SSL PROTOCOL_T3 |
DyeInjectionモニターによりリクエストに使用されているプロトコルが暗黙的に識別され、使用されているプロトコルに応じて、仕分けベクトルの適切な仕分け(1つまたは複数)が設定されます。 PROTOCOL_HTTPは、リクエストにHTTPまたはHTTPSプロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_IIOPは、リクエストにInternet Inter-ORB Protocol (IIOP)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_JRMPは、リクエストにJava Remote Method Protocol (JRMP)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_RMIは、リクエストにJava Remote Method Invocation (RMI)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_SSLは、リクエストにSecure Sockets Layer (SSL)プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 PROTOCOL_T3は、リクエストにT3またはT3プロトコルが使用されている場合にリクエストの診断コンテキストに設定されます。 |
THROTTLE |
THROTTLE仕分けは、リクエストがDyeInjectionモニターのTHROTTLE_INTERVALまたはTHROTTLE_RATEプロパティに指定された要件を満たす場合に、リクエストの診断コンテキストに設定されます。 |
USER1 USER2 USER3 USER4 |
仕分けUSER1、USER2、USER3、およびUSER4を使用して、リクエストを発信したクライアントのユーザー名を指定します。DyeInjectionモニターのプロパティ(USER1、USER2、USER3、USER4)に指定されているユーザーによってリクエストが発信されると、それぞれに対応する仕分けフラグがそのリクエストの診断コンテキストに設定されます。 |
PROTOCOL仕分けフラグ
DyeInjectionモニターの仕分けフラグUSERn, ADDRn, COOKIEn, and CONNECTORnについては、明示的に値を設定する必要があります。一方、フラグPROTOCOL_HTTP、PROTOCOL_IIOP、ROTOCOL_JRMP、PROTOCOL_RMI、PROTOCOL_SOAP、PROTOCOL_SSLおよびPROTOCOL_T3は、WLDFにより暗黙的に設定されます。DyeInjectionモニターが有効になっていれば、すべてのリクエストに適切なプロトコルの仕分けが挿入されます。たとえば、HTTPによって届いたリクエストにはすべて仕分けPROTOCOL_HTTPが挿入されます。
THROTTLE仕分けフラグ
THROTTLE仕分けフラグを使用して、受信リクエストのうち仕分けを設定するものの量を制御できます。THROTTLEは他のフラグとは異なる方法で構成され、WLDFでの使用方法も異なります。詳細は、「インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法」,を参照してください。
診断コンテキストの作成条件
診断モジュールでDyeInjectionモニターが有効になっている場合、受信するすべてのリクエストについて診断コンテキストが作成されます。診断モジュールでインストゥルメンテーションを有効にするとき、DyeInjectionモニターはデフォルトで有効にされます。これにより診断コンテキストIDが利用でき、イベントが関連付けられます。DyeInjectionモニターに明示的に設定されているプロパティがない場合でも、一意のコンテキストIDと、暗黙的なPROTOCOL仕分け群のうち1つが指定された仕分けベクトルがすべてのリクエストのコンテキストに含まれます。
DyeInjectionモニターが診断モジュールに無効になっている場合、受信するどのリクエストについても診断コンテキストは作成されません。
仕分けフィルタ処理を使用するための委任モニターの構成
DyeInjectionモニターを、診断モジュールの委任診断モニターまたはカスタム診断モニターのトリガー条件を制限するメカニズムとして使用できます。このプロセスを仕分けフィルタ処理と呼びます。
ノート:
アプリケーション(Webアプリケーションなど)に診断モニターを実装する方法については、「アプリケーションのインストゥルメントに必要なステップの概要」を参照してください
それぞれのモニターに仕分けマスクを設定できます。仕分けマスクにはDyeInjectionモニターから選択された仕分けが指定されます。診断モニターに対して仕分けフィルタが有効になっている場合、マスクで設定された条件に一致するリクエストでのみ、モニターの診断アクションがトリガーされ、診断イベントが生成されます。
図13-1に、構成されている診断アクションがトリガーされたときに、生成された診断イベントの例を示します。すべてのイベントのコンテキストIDが同じであることが分かります。これは、これらのイベントが同じリクエストに関連していることを示しています。このコンテキストIDを使用して、リクエストに関連付けられているログ・レコードを問い合わせることができます。リクエストに関連付けられているユーザーIDとDyeInjectionモニターで構成したUSER値は常に同じではありません。リクエストがシステムで処理される過程で、そのリクエストに関連付けられているユーザーが変わることによって、システムで特定の機能を実行することができます(たとえば、ユーザーIDがkernelに変わる場合があります)。
サンプル構成
TraceElapsedTimeActionアクションがアタッチされているServlet_Around_Serviceアプリケーション・スコープの診断モニターについて検討します。仕分けフィルタ処理が有効になっていない場合、Servlet_Around_Serviceで処理されるすべてのリクエストによってTraceElapsedTimeActionがトリガーされます。ただし、IPアドレス127.0.0.1のユーザーadmin@avitek.comからのリクエストに対してのみTraceElapsedTimeActionのトリガーとして仕分けフィルタを使用できます。
-
USER1=admin@avitek.comおよびADDR1=127.0.0.1となるようにDyeInjectionモニターを構成して、DyeInjectionモニターを有効にします。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプの診断システム・モジュールでの診断監視の構成に関する項を参照してください。
-
仕分けマスクを構成して、Servlet_Before_Service診断モニターの仕分けフィルタ処理を有効にします。WebLogic Server管理コンソールで、次の手順に従います。
-
Oracle WebLogic Server管理コンソール・ヘルプのアプリケーションのインストゥルメンテーションの構成に関する項の説明のとおり、WLDFインストゥルメンテーション・ライブラリからのServlet_Around_Service監視をアプリケーションに追加します。
-
モニターの追加後、「<application_name>の設定」ページで「保存」をクリックします。
-
「Servlet_Around_Service」リンクをクリックし、「Servlet_Around_Serviceの設定」ページを表示します。
-
「有効」チェック・ボックスを選択してモニターを有効にします。
-
「アクション」下の「使用可能」リストから「選択済み」リストに「TraceElapsedTimeAction」を移動します。
-
「仕分けマスク」セクションで、「USER1」および「ADDR1」を「使用可能」リストから「選択済」リストへ移動します。
-
「仕分けフィルタを有効化」チェック・ボックスを選択します。
-
「保存」をクリックします。
-
-
アプリケーションを再デプロイします。
WebLogic Server管理コンソールで追加した構成は、アプリケーションのMETA-INF
ディレクトリのweblogic-diagnostics.xml
ファイルやDIAG_MODULE
.xml
ファイルには保持されず、アプリケーションのデプロイメント・プランに保存されます。
DIAG_MODULE
.xml
ファイルを手動で更新して診断モニターを追加することもできますが(コード・リスト13-2を参照)、この方法はお薦めしません。構成は、実行サーバーのWebLogic Server管理コンソールで変更することをお薦めします。DIAG_MODULE
.xml
に対して行った変更は、アプリケーションを再デプロイするまで有効になりません。
コード・リスト13-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 USER1=admin@avitek.com</properties> </wldf-instrumentation-monitor> <wldf-instrumentation-monitor> <name>Servlet_Around_Service</name> <dye-mask>ADDR1 USER1</dye-mask> <dye-filtering-enabled>true</dye-filtering-enabled> <action>TraceElapsedTimeAction</action> </wldf-instrumentation-monitor> <!-- Other elements to configure instrumentation --> </instrumentation> <!-- Other elements to configure this diagnostic monitor --> <wldf-resource>
この構成では、IPアドレス127.0.0.1とユーザーadmin@avitek.comから発信されたリクエストでのみServlet_Around_Service診断モニターのTraceElapsedTimeActionアクションがトリガーされます。
診断モニターで有効となるフラグは、イベント・アーカイブに書きこむようにリクエストの仕分けベクトルで動作がトリガーされるように設定されたビットとイベントに正確に一致する必要があります。たとえば、診断モニターがUSER1とADDR1フラグの両方を有効にし、USER1フラグのみがリクエストの仕分けベクトルで設定されると、トリガーされる動作はなく、イベントも生成されません。
ノート:
診断モニターを構成する際、同じタイプの複数のフラグを有効化しないでください。たとえば、USER1フラグとUSER2フラグの両方を有効化しないでください。これは、特定のリクエストの仕分けベクトルでUSER1フラグとUSER2フラグの両方が設定されない場合があるためです。
仕分けマスクによるモニターへ渡すリクエストのフィルタ方法
リクエストにアタッチされる仕分けベクトルには複数の仕分けを指定でき、委任モニターにアタッチされる仕分けマスクにも複数の仕分けを指定できます。
委任モニターの仕分けマスクを使用して、モニターがリクエストに対してアクションを実行できるようにするには、以下の条件をすべて満たしている必要があります。
-
アプリケーションの
weblogic-diagnostics.xml
記述子、またはWebLogic Server管理コンソールを使用して委任モニターまたはカスタム診断モニターの仕分けフィルタ処理を有効にします。 -
リクエストの仕分けベクトルに、モニターの仕分けマスクで定義されているすべての仕分けが含まれています。(仕分けベクトルには、仕分けマスクにない仕分けが含まれている可能性もあります。)
仕分けフィルタ処理の例
図13-3 では、2つの診断モニターを持つ診断モジュールを使用した仕分けフィルタ処理の仕組みを示しています。
-
DyeInjectionモニターは次のように構成されています。
ADDR1=127.0.0.1 USER1=weblogic
-
Servlet_Around_Serviceモニターには、ADDR1のみを含む仕分けマスクが構成されています。
-
EJB_Around_SessionEjbBusinessMethodsモニターには、USER1のみを含む仕分けマスクが構成されています。
-
IPアドレス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があるかどうかをチェックし、それが見つかります。その結果、モニターは診断アクションをトリガーします。イベント・アーカイブへのデータの書込みなどの診断イベントが発生します。
-
リクエストがSessionEJBコンポーネントに届きます。このコンポーネントでは、診断モニターEJB_Around_SessionEjbBusinessMethodsがコード内に織り込まれています。(EJB_Around_SessionEjbBusinessMethodsはすべてのSessionBeanメソッドの入り口と出口で診断アクションをトリガーします)。このモニターでは仕分けモニターが有効になっており、仕分けマスクにはUSER1という値が1つ定義されています。
-
SessionBeanメソッド(EJB_Around_SessionEjbBusinessMethodsでインストゥルメントされている)にリクエストが入るか出るときに、診断モニターはリクエストに仕分けベクトルUSER1があるかどうかをチェックしますが、見つかりません。したがって、モニターは診断アクションをトリガーしないので、診断イベントは発生しません。
親トピック: 仕分けマスクによるモニターへ渡すリクエストのフィルタ方法
インストゥルメンテーション・イベントの量を制御するスロットル機能の使用方法
スロットル機能を使用すると、診断モジュールのモニターで処理されるリクエストの数を制御できます。
スロットル機能は、DyeInjectionモニターに定義されるTHROTTLE仕分けを使用して構成します。
ノート:
USERnおよびADDR n仕分けを使用すると、特定のユーザーまたはIPアドレスからのリクエストを検査することができます。ただし、任意のユーザー・トランザクションを調べる手段にはなりません。THROTTLE仕分けでは、リクエストのサンプリングによりその機能を提供します。
THROTTLE仕分けの構成
仕分けベクトルの他の仕分けと異なり、THROTTLE仕分けは2つのプロパティを通じて構成されます。
-
THROTTLE_INTERVALに、新しく受信されるリクエストにTHROTTLE仕分けが指定されるまでの間隔(ミリ秒)を設定します。
THROTTLE_INTERVALが0より大きい場合、DyeInjectionモニターでは、最後にTHROTTLE仕分けが指定されたリクエストが届いてから少なくとも
THROTTLE_INTERVAL
のミリ秒数のみ経過した後に受信されたリクエストに対して、その新しいリクエストの仕分けベクトルにあるTHROTTLE仕分けフラグが設定されます。たとえばTHROTTLE_INTERVAL=3000と指定した場合、DyeInjectionモニターでは少なくとも3000ミリ秒の待機後に、受信したリクエストにTHROTTLE仕分けが指定されます。 -
THROTTLE_RATEに、新しく受信されるリクエストにTHROTTLE仕分けが指定される度合い(受信されるリクエストの数で表します)を設定します。
THROTTLE_RATEが0より大きい場合、DyeInjectionモニターでは、最後にTHROTTLE仕分けが設定されたリクエスト以降のリクエストの数が
THROTTLE_RATE
と同じになったときに、受信されたリクエストの仕分けベクトルにあるTHROTTLE仕分けフラグが設定されます。たとえば、THROTTLE_RATE = 6と指定した場合、6リクエストごとにTHROTTLE仕分けが指定されます。
THROTTLE_INTERVALとTHROTTLE_RATEは併用できます。いずれかのリクエストを満たす場合、リクエストはTHROTTLE仕分けされます。
THROTTLE_INTERVALまたはTHROTTLE_RATEのどちらかに値を割り当てる場合(両方に割り当てることもいずれにも割り当てないことも可)、THROTTLE仕分けが構成されます。
例13-3に、結果として診断モジュールの記述子ファイルに記述される構成を示します。
例13-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> <!-- Other elements to configure this diagnostic monitor --> </wldf-resource>
例13-4に、仕分けマスクにTHROTTLE仕分けが設定されているJDBC_Before_Start_Internal委任モニターの構成を示します。
例13-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> <!-- Other elements to configure this diagnostic monitor --> </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パッケージを使用すると、アプリケーションから診断コンテキストにアクセスできます。
アプリケーションでは一連のweblogic.diagnostics.context.DiagnosticContextHelper APIを使用して、以下の関数を実行できます。
-
診断コンテキストの不変のコンテキストIDの検査。
-
コンテキストの仕分けベクトルにある仕分けフラグの設定の検査。
-
有効な仕分けフラグ名の配列の取得。
-
コンテキストの仕分けベクトルにあるDYE_0からDYE_7までのフラグについての設定または設定の解除。(これらのフラグ・ビットをXMLを介して設定する方法はありません。DyeInjectionモニターの<properties>を構成すると、アプリケーション固有でないフラグ・ビットについてXMLを介して設定できますが、仕分けベクトルのDYE_0からDYE_7までを設定できるのはsetDye()メソッドのみです)。
-
診断コンテキストへのペイロード(String型)のアタッチ、または既存のペイロードの読込み。
以下についてはアプリケーションでは処理できません。
-
アプリケーション用に予約されている8フラグ以外の仕分けベクトルのフラグの設定。
-
仕分けベクトルの同じアプリケーション・フラグが別のアプリケーションで設定されることの回避。適切に動作するアプリケーションであれば、仕分けフラグを設定する前にあらかじめ設定されているかどうかをテストできます。
-
別のアプリケーションによるペイロードの置換えの回避。適切に動作するアプリケーションであれば、ペイロードを追加する前にペイロードが存在するかどうかをテストできます。
ノート:
診断コンテキストのペイロードは、同一実行コンテキスト内の他のコードによって表示可能で、Work
インスタンスと共にプロセスから流れ、同一実行コンテキスト内で実行されている他のコードによって上書き可能です。そのため、アプリケーションで次の動作を確認する必要があります。
-
getPayload()
メソッドによって返される可能性のあるような機密データをペイロードには含めないようにします。 -
コンテキスト・ペイロードで使用可能な特定のデータに関する依存関係を作成しないでください。たとえば、アプリケーションは特定のコンテキストIDへ依存してはなりません。アプリケーションは、ペイロードのコンテンツを使用する場合、最初にそのコンテンツが期待通りのものか検証する必要があります。
アプリケーションでDYE_0からDYE_7までのフラグうち1つまたは複数を設定した時点以降には、モニターや別のアプリケーションでそれらのフラグをチェックするように仕分けマスクを設定し、そのフラグ(群)がコンテキストの仕分けベクトルに存在する場合にアクションを実行できます。診断コンテキストにペイロードがアタッチされている場合、モニターで実行されるアクションはペイロードに格納されてアーカイブ化され、結果としてアクセサ・コンポーネントを通じて利用できるようになります。
例13-5は、診断コンテキストを(暗黙的に)作成し、コンテキストIDを出力し、DYE_0フラグの値をチェックし、その後DYE_0を設定する簡単なサンプルです。
例13-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)); } }