ナビゲーションをスキップ

WebLogic 診断フレームワークのコンフィグレーションと使い方

  前 次 前/次ボタンと目次ボタンとの区切り線 目次  

診断コンテキストのコンフィグレーション

WLDF インスツルメンテーション コンポーネントは、要求をユニークに識別し、システム内でのフローに従って要求を追跡する手段として利用できます。WLDF をコンフィグレーションすると、システムに届く各要求の特定の特性 (発信したユーザやクライアント アドレス) をチェックするようにしたり、要求に (ユニークな ID や、要求の特性を表すフラグにより定義される) コンテキストをアタッチしたりしてから、その要求のコンテキストを基にインスツルメンテーション イベントをトリガするようにできます。そうしたインスツルメンテーション イベントは、後にログを生成したり通知をトリガしたりするために使用できます。

診断コンテキストは、システム レベルでもアプリケーション レベルでも利用できますが、コンフィグレーション方法と使用方法に若干の違いがあります。

この章を通して、診断コンテキストのコンフィグレーションと使用のプロセスについて詳細に説明します。内容は以下のとおりです。

 


診断コンテキストの内容、ライフサイクル、コンフィグレーションについて

診断コンテキストには、ユニークなコンテキスト ID と、コンテキストの特性を識別する仕分けベクトルが含まれます。

コンテキストのライフ サイクルとコンテキスト ID について

要求の診断コンテキストはその要求がシステムに参加したとき (たとえばクライアントで HTTP 要求を発行したとき) に作成され、初期化されます。このコンテキストは、要求がスレッド境界や Java 仮想マシン (Java Virtual Machine : JVM) 境界を越えてもアタッチされ続けます。診断コンテキストは、要求のライフ サイクル全体を通して存続します。

すべての診断コンテキストは、ドメイン内でユニークな ID によって識別されます。この ID が要求に付随して移動するので、システム内でのフローに従って所定の要求を追跡できます。

仕分け、仕分けフラグ、仕分けベクトルについて

コンテキスト情報は、64 ビットの仕分けベクトルとして要求と共に移動します。それぞれのビットは仕分けの存在を識別するフラグです。各仕分けが要求の 1 つの属性 (発信したユーザ、発信したクライアント IP アドレス、アクセス プロトコルなど) を表します。

特定の属性に対応する仕分けフラグが設定されている場合、その属性が存在することを示しています。フラグが設定されていない場合、その属性が存在しないことを示しています。

例として、要求の発信元が IP アドレス 127.0.0.0 であることを示すために仕分け ADDR1 がコンフィグレーションされているコンフィグレーションについて検討します。要求の発信元が IP アドレス 127.0.0.1 であることを示すために仕分けフラグ ADDR2 がコンフィグレーションされています。IP アドレス 127.0.0.0 からの要求がシステムに参加すると、その要求の仕分けベクトルの ADDR1 仕分けフラグが設定されます。ADDR2 仕分けフラグは設定されていないままの状態です。

診断コンテキストを利用する診断機能やモニタ機能では、属性が存在するかどうかを判断する目的で仕分けベクトルを調べられます。上記の例では、管理者は監視をコンフィグレーションして、その監視で ADDR1 仕分けの設定されたすべての要求を調べるようにすることで、IP アドレス 127.0.0.0 から発信された要求を調べられます。

また、仕分けベクトルには THROTTLE 仕分けもあります。この仕分けは、受信する要求に仕分けを設定する頻度を指定するために使用します。この特別な仕分けの詳細については、「THROTTLE 仕分けフラグについて」を参照してください。

利用できる仕分けとそれによって表される属性のリストについては、「DyeInjection モニタでサポートされる仕分け」を参照してください。仕分けベクトルをコンフィグレーションおよび使用するプロセスについては、この章の以降の節で説明します。

診断コンテキストがコンフィグレーションされる場所

診断コンテキストは、診断モジュールの一部としてコンフィグレーションされます。診断コンテキストをコンフィグレーションするための主なメカニズムは、標準の診断モニタである DyeInjection モニタです。DyeInjection モニタがコードにウィービングされるジョインポイントは、要求がシステムに参加する可能性のある場所です。診断アクションによって、各要求が DyeInjection モニタのコンフィグレーションに照らしてチェックされてから、その要求にコンテキストが作成されてアタッチされ、必要に応じた仕分けフラグが設定されます。診断モニタのタイプ、(ジョインポイントを定義する) ポイントカット、および診断アクションについては、「インスツルメンテーションのコンフィグレーション」を参照してください。

 


プロセスの概要

ここでは、サーバ スコープの診断モジュールにおけるコンテキストのコンフィグレーションと使用について概説します。

  1. 管理者が DyeInjection モニタを使用するために診断モジュールをコンフィグレーションします。
  2. 管理者がそのモジュールのインスツルメンテーションを有効にします。
  3. 管理者が仕分けに値を割り当てることにより DyeInjection モニタをコンフィグレーションします。たとえば、USER1=username1USER2=username2ADDR1=ip_address1ADDR2=ip_address2、などのように指定します。
  4. システムに要求が参加すると、WLDF によってその要求のコンテキストが作成されインスタンス化されます。このコンテキストにはユニークな ID と仕分けベクトルが指定されます。これについて次の手順で説明します。
  5. システムに要求が参加すると DyeInjection モニタによってその要求が調べられ、仕分けベクトルの仕分けの値に一致する属性があるか、ある場合にはどの値と一致するかが確認されます。たとえば、要求の発信者が username1username2 か、また要求の発信元が ip_address1 ip_address2 か、などを確認するためのチェックが行われます。
  6. 要求の属性と一致する各仕分けの値について、DyeInjection モニタによりその仕分けが要求に「挿入」されます。つまり、要求にアタッチされる仕分けベクトルにあるその仕分け用の仕分けフラグが設定されます。たとえば、要求が username2 によって ip_address1 から発信された場合、DyeInjection モニタにより仕分けフラグ USER2ADDR1 が設定されます (USER1ADDR2 は設定されていない状態のままになります)。
  7. 仕分けベクトルは (診断コンテキストの一部として) 要求に付随し、システム内の要求のフローとともに移動します。この 64 ビットの仕分けベクトルの内容はフラグのみで、値は含まれません。そのため、この例では明示的に設定した 2 つのフラグ (USER2ADDR1) のみが仕分けベクトルに含まれます。
  8. 注意 : すべての仕分けベクトルには、暗黙的に PROTOCOL 仕分け群の 1 つも含まれます。これについては、「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」で説明します。

  9. 管理者が 1 つまたは複数の代理診断モニタで仕分けフィルタを有効にし、各モニタに仕分けマスクをコンフィグレーションします。仕分けマスクに指定された仕分けが要求にアタッチされた仕分けベクトルの仕分けと正確に一致する場合、つまり ((dye-mask & dye-vector) == dye-mask) の場合、その要求が処理されるときにモニタの診断アクションがトリガされます。

これらの手順について、以降の節で詳しく説明します。

 


DyeInjection モニタを介した仕分けベクトルのコンフィグレーション

要求のコンテキストを作成するには、次の手順を行う必要があります。

  1. モニタする 1 つまたは複数のサーバ用に診断モジュールを作成して有効にする。
  2. モジュールのインスツルメンテーションを有効にする。
  3. モジュールの DyeInjection モニタをコンフィグレーションして有効にする (1 つのモジュールで同時に使用できる DyeInjection モニタは 1 つのみ)。

DyeInjection モニタをコンフィグレーションするには、仕分けベクトルの仕分けに値を割り当てます。利用できる仕分けフラグについては、表 10-1 で説明します。受信する要求用のコンテキスト作成のために WLDF で要求を評価する際、WLDF では仕分けベクトルに指定されている値の存在をチェックします。値が存在する場合、そのフラグが WLDF によって設定されます。このプロセスが要求の仕分け、または要求への仕分けの挿入と呼ばれます。

たとえば、IP アドレスが 127.0.0.0 のクライアントから admin@avitek というユーザによって開始されたすべての要求をモニタするには、値 admin@avitekUSER1 に、値 127.0.0.0 を ADDR1 に割り当てます。その結果、ユーザ admin@avitek が IP アドレス 127.0.0.0 のクライアントから要求を開始すると、その要求には USER1 および ADDR1 という仕分けが設定されます。すなわち、(要求のコンテキスト内の) 仕分けベクトルの USER1 フラグと ADDR1 フラグが両方とも設定された状態になります。

Administration Console で仕分けに値を割り当てるには、[DyeInjection の設定] ページの [プロパティ] フィールドに値を入力します。

図 10-1 Administration Console における仕分けの値の設定

Administration Console における仕分けの値の設定


 

これらの設定は、診断モジュールの記述子ファイルでは以下のコード リストに示すように表されます。

コード リスト 10-1 DyeInjection モニタのコンフィグレーションのサンプル

<wldf-resource>
  <name>MyAdminModule</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 モニタでサポートされる仕分け

仕分けベクトルで利用できる仕分けについて、以下の表にリストして説明します。

表 10-1 サポートされる診断コンテキストの仕分けと対応する要求のプロトコル

仕分けフラグ

説明

ADDR1

ADDR2

ADDR3

ADDR4

仕分け ADDR1ADDR2ADDR3、および ADDR4 を使用すると、要求を発信したクライアントの IP アドレスを指定できる。DyeInjection モニタのプロパティ (ADDR1ADDR2ADDR3ADDR4) に指定されている IP アドレスから要求が発信されると、それぞれ対応する仕分けフラグがその要求の診断コンテキストに設定される。

CONNECTOR1

CONNECTOR2

CONNECTOR3

CONNECTOR4

仕分け CONNECTOR1CONNECTOR2CONNECTOR3、および CONNECTOR4 を使用すると、コネクタ ドライバの特性を識別できる。

これらの仕分けフィルタは、コネクタ ドライバによって状況に特有の要求のプロパティを識別するために設定される。これらは、ユーザが Administration Console または記述子ファイルに直接コンフィグレーションするものではない。これらの仕分けにはコネクタ ドライバによって (コネクタ API を使用して) 値が割り当てられ、その結果、接続に関する情報が診断コンテキストに保持されて運ばれる。

COOKIE1

COOKIE2

COOKIE3

COOKIE4

COOKIE1COOKIE2COOKIE3、および COOKIE4 は、HTTP または HTTPS 要求に weblogic.diagnostics.dye というクッキーが含まれていて、その値が DyeInjection モニタのそれぞれに対応するプロパティ (COOKIE1COOKIE2COOKIE3COOKIE4) の値と同じ場合に、その要求の診断コンテキストに設定される。

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 は、要求に IIOP プロトコルが使用されている場合に要求の診断コンテキストに設定される。

  • PROTOCOL_JRMP は、要求に JRMP プロトコルが使用されている場合に要求の診断コンテキストに設定される。

  • PROTOCOL_RMI は、要求に RMI プロトコルが使用されている場合に要求の診断コンテキストに設定される。

  • PROTOCOL_SSL は、要求に SSL プロトコルが使用されている場合に要求の診断コンテキストに設定される。

  • PROTOCOL_T3 は、要求に T3 または T3s プロトコルが使用されている場合に要求の診断コンテキストに設定される。

THROTTLE

THROTTLE 仕分けは、要求が DyeInjection モニタの THROTTLE_INTERVAL または THROTTLE_RATE プロパティに指定された要件を満たす場合に、要求の診断コンテキストに設定される。


USER1

USER2

USER3

USER4

仕分け USER1USER2USER3、および USER4 を使用すると、要求を発信したクライアントのユーザ名を指定できる。DyeInjection モニタのプロパティ (USER1USER2USER3USER4) に指定されているユーザによって要求が発信されると、それぞれに対応する仕分けフラグがその要求の診断コンテキストに設定される。



 

PROTOCOL 仕分けフラグについて

DyeInjection モニタの仕分けフラグ USERnADDRnCOOKIEn、および CONNECTORn については、明示的に値を設定する必要があります。一方、フラグ PROTOCOL_HTTPPROTOCOL_IIOPROTOCOL_JRMPPROTOCOL_RMIPROTOCOL_SOAPPROTOCOL_SSL、および PROTOCOL_T3 は、WLDF により暗黙的に設定されます。DyeInjection モニタが有効になっていれば、すべての要求に適切なプロトコルの仕分けが挿入されます。たとえば、HTTP によって届いた要求にはすべて仕分け PROTOCOL_HTTP が挿入されます。

THROTTLE 仕分けフラグについて

THROTTLE 仕分けフラグを使用して、受信する要求のうち仕分けを設定するものの量を制御できます。THROTTLE は他のフラグとは異なる方法でコンフィグレーションされ、WLDF での使用方法も異なります。詳細については、「インスツルメンテーション イベントの量を制御するスロットル機能の使い方」を参照してください。

コンテキストの作成条件

診断モジュールで DyeInjection モニタが有効になっている場合、受信するすべての要求について診断コンテキストが作成されます。DyeInjection モニタに明示的に設定されているプロパティがない場合でも、ユニークなコンテキスト ID と、暗黙的な PROTOCOL 仕分け群のうち 1 つが指定された仕分けベクトルがすべての要求のコンテキストに含まれます。DyeInjection モニタが診断モジュールに追加されていないか、無効になっている場合、受信するどの要求についても診断コンテキストは作成されません (ただし、次の注意を参照)。

注意 : Administration Console では DyeInjection モニタを有効にした場合にのみ診断コンテキストを作成できますが、WLST を利用すると WLDFServerDiagnosticMBeanDiagnosticContextEnabled 属性を設定できます。

 


仕分けフィルタを使用するための代理モニタのコンフィグレーション

DyeInjection モニタを、診断モジュールの代理診断モニタまたはカスタム診断モニタのトリガ条件を制限するメカニズムとして使用できます。このプロセスを仕分けフィルタと呼びます。

それぞれのモニタに仕分けマスクを設定できます。仕分けマスクには DyeInjection モニタから選択された仕分けが指定されます。診断モニタに対して仕分けフィルタが有効になっている場合、マスクに設定された条件に一致する要求でのみモニタの診断アクションがトリガされます。

例として、TraceAction アクションがアタッチされている Connector_After_Inbound 診断モニタについて検討します。仕分けフィルタが有効になっていない場合、Connector_After_Inbound で処理されるすべての要求 (つまり、メソッドを抜けるすべての要求) によって TraceAction がトリガされます。一方、仕分けマスクを使用すると、以下に示すとおり IP アドレス 127.0.0.0 から発信された要求のみで TracAction をトリガするように指定することも可能です。

  1. DyeInjection モニタで ADDR1=127.0.0.0 とコンフィグレーションして、DyeInjection モニタを有効にします。手順については、前述の「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」を参照してください。
  2. 仕分けマスクをコンフィグレーションして、Connector_After_Inbound 診断モニタの仕分けフィルタを有効にします。Administration Console では、以下の説明および図 10-2 に示すように、[Connector_After_Inbound の設定] ページでこの作業を行います。
    1. [Connector_After_Inbound の設定] ページに移動します (診断モジュールの Connector_After_Inbound 診断モニタの追加とコンフィグレーションに関する詳細な手順については、Administration Console オンライン ヘルプを参照してください)。
    2. [Connector_After_Inbound の設定] ページの [仕分けマスク] フィールドで、[ADDR1] を [使用可能] リストから [選択済み] リストに移動します。
    3. [仕分けフィルタを有効化] チェック ボックスを選択します。

このコンフィグレーションでは、IP アドレス 127.0.0.0 から発信された要求でのみ Connector_After_Inbound 診断モニタの TraceAction アクションがトリガされます。

図 10-2 Administration Console における仕分けフィルタの設定

Administration Console における仕分けフィルタの設定


 

これらの設定は、診断モジュールの記述子ファイルでは以下のコード リストに示すように表されます。

コード リスト 10-2 代理モニタで仕分けフィルタを使用するコンフィグレーションのサンプル

<wldf-resource>
  <name>MyAdminModule</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>Connector_After_Inbound</name>
      <dye-mask>ADDR1</dye-mask>
      <dye-filtering-enabled>true</dye-filtering-enabled>
      <action>TraceAction</action>
    </wldf-instrumentation-monitor>
  <!-- インスツルメンテーションをコンフィグレーションするための他の要素 -->
  <instrumentation>
<!-- 診断モニタをコンフィグレーションするための他の要素 -->
<wldf-resource>

 


仕分けマスクによるモニタへ渡す要求のフィルタ方法

要求にアタッチされる仕分けベクトルには複数の仕分けを指定でき、代理モニタにアタッチされる仕分けマスクにも複数の仕分けを指定できます。代理モニタの仕分けマスクで、要求に対してモニタによるアクションを実行できるようにするには、以下の条件をすべて満たしている必要があります。

 


インスツルメンテーション イベントの量を制御するスロットル機能の使い方

スロットル機能を使用すると、診断モジュールのモニタで処理される要求の数を制御できます。スロットル機能は、DyeInjection モニタに定義される THROTTLE 仕分けを使用してコンフィグレーションします。

THROTTLE 仕分けをコンフィグレーションする

仕分けベクトルの他の仕分けと異なり、THROTTLE 仕分けは 2 つのプロパティを通じてコンフィグレーションされます。

THROTTLE_INTERVALTHROTTLE_RATE は併用できます。要求に THROTTLE 仕分けが指定されるには、両方の条件が満たされている必要があります。たとえば、THROTTLE_RATE=6 と指定されていても、(THROTTLE 仕分けが最後に指定された要求から数えて) 6 番目の要求が THROTTLE_INTERVAL が経過する前に届いた場合、その 6 番目の要求には仕分けは指定されません。THROTTLE_INTERVAL の経過後、最初に届いた要求に仕分けが指定され、THROTTLE_RATE のカウントはリセットされます。逆に、THROTTLE_INTERVAL が経過していても、THROTTLE 仕分けが最後に指定された要求以降の要求数が THROTTLE_RATE 未満の場合、THROTTLE_RATE の数に達するまで、受信される要求には仕分けが指定されません。

THROTTLE_INTERVAL または THROTTLE_RATE のどちらかに値を割り当てる場合 (両方に割り当てることもどちらにも割り当てないことも可)、THROTTLE 仕分けがコンフィグレーションされます。Administration Console での THROTTLE コンフィグレーションの設定を、以下の図に示します。

図 10-3 THROTTLE 仕分けのコンフィグレーション

THROTTLE 仕分けのコンフィグレーション


 

リスト 10-3 に、結果として診断モジュールの記述子ファイルに記述されるコンフィグレーションを示します。

コード リスト 10-3 DyeInjection モニタの THROTTLE コンフィグレーションのサンプル

    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <properties>
        THROTTLE_INTERVAL=3000
          THROTTLE_RATE=6
        </properties>
      </wldf-instrumentation-monitor>

リスト 10-4 に、仕分けマスクに THROTTLE 仕分けが設定されている Connector_After_Inbound 代理モニタのコンフィグレーションを示します。

コード リスト 10-4 代理モニタの仕分けマスクに THROTTLE を設定するコンフィグレーションのサンプル

    <wldf-instrumentation-monitor>
      <name>Connector_After_Inbound</name>
      <enabled>true</enabled>
      <dye-mask>THROTTLE</dye-mask>
    </wldf-instrumentation-monitor>

代理モニタ、カスタム モニタでのスロットル機能の処理方法

仕分けマスクおよび仕分けフィルタによるメカニズムを使用して、代理モニタおよびカスタム モニタで処理するために渡す要求を、要求のプロパティに基づいて制限できます。「DyeInjection モニタを介した仕分けベクトルのコンフィグレーション」で前述したように、要求におけるプロパティの存在は仕分けの存在によって示されます。THROTTLE 仕分けもそうした仕分けの 1 つと見なされるため、THROTTLE も他の仕分けと同様にフィルタできます。ただし、THROTTLE のもっとも一般的な使い方は、仕分けフィルタと併用せずに使用して代理モニタに渡される要求を制限する方法です。

以下に、スロットル機能の処理方法について説明します。

 


weblogic.diagnostics.context の使い方

weblogic.diagnostics.context パッケージを使用すると、アプリケーションから診断コンテキストに制限付きでアクセスできます。

アプリケーションでは一連の weblogic.diagnostics.context.DiagnosticContextHelper API を使用して、以下の関数を実行できます。

以下についてはアプリケーションでは処理できません。

アプリケーションで DYE_0 から DYE_7 までのフラグのうち 1 つまたは複数を設定した時点以降には、モニタや別のアプリケーションでそれらのフラグをチェックするように仕分けマスクを設定し、そのフラグ (群) がコンテキストの仕分けベクトルに存在する場合にアクションを実行できます。診断コンテキストにペイロードがアタッチされている場合、モニタで実行されるアクションはペイロードに格納されてアーカイブ化され、結果としてアクセサ コンポーネントを通じて利用できるようになります。

リスト 10-5 は、診断コンテキストを (暗黙的に) 作成し、コンテキスト ID を出力して、DYE_0 フラグの値をチェックした上で設定する簡単なサンプルです。

コード リスト 10-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));
}
}

 

フッタのナビゲーションのスキップ  ページの先頭 前 次