Oracle® Fusion Middleware Oracle WebLogic Server診断フレームワークの構成と使い方 11g リリース1 (10.3.4) B60994-02 |
|
前 |
次 |
WebLogic診断フレームワーク(WLDF)のインストゥルメンテーション・コンポーネントは、WebLogic Serverインスタンスおよびそのサーバー・インスタンスで実行中のアプリケーションに診断コードを追加するためのメカニズムを提供します。WLDFのインストゥルメンテーションでの主な機能は次のとおりです。
診断モニター。サーバーまたはアプリケーション・コードの特定の場所に挿入され、動的に管理できるひとまとまりの診断コードです。モニターは、スコープ(システム、アプリケーション)および種類(標準、委任、カスタム)を基に定義します。
診断アクション。プログラムの実行中にトリガーされたモニターが行うアクション。
診断コンテキスト。診断コンテキストは、送信元のIPアドレスやユーザーIDなど、特定のリクエスト・プロパティの存在を示すフラグや固有のリクエスト識別子などのコンテキスト情報です。診断コンテキストでは、プログラムの実行を追跡したり、モニターが診断アクションをトリガーするタイミングを制御したりすることができます。第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
WLDFには、あらかじめ定義された診断モニターと診断アクションのライブラリが用意されています。また、アプリケーション・スコープのカスタム・モニターを作成し、診断コードが挿入されるアプリケーション内の位置をユーザーが決めることもできます。
インストゥルメンテーションについては、次の項で説明します。
この項では、インストゥルメンテーションの概念と用語について説明します。
実行可能なインストゥルメンテーション・サービスには、システム・レベル(サーバーおよびクラスタ)のものとアプリケーション・レベルのものがあります。概念、サービス、構成オプション、および実装機能の多くは両者とも同じです。ただし、相違点もいくつかあります。それらについて、このドキュメントで説明します。「サーバー・スコープ・インストゥルメンテーション」は、WebLogic Serverインスタンスおよびクラスタ固有のインストゥルメンテーションの構成と機能を指し、「アプリケーション・スコープ・インストゥルメンテーション」は、WebLogicサーバーにデプロイされているアプリケーション固有の構成と機能を指します。スコープは各診断モニターに組み込まれており、ユーザーがモニターのスコープを変更することはできません。
サーバーまたはクラスタ向けのサーバー・スコープ・インストゥルメンテーションは、診断モジュールの一部として、DOMAIN_NAME/config/diagnosticsディレクトリにあるXML構成ファイルで構成およびデプロイされ、config.xmlからリンクされています。
アプリケーション・スコープ・インストゥルメンテーションも、診断モジュールとして構成およびデプロイされます。ただし、アプリケーション・スコープの場合は、デプロイされるアプリケーションのARCHIVE_PATH/META-INFディレクトリ内のアプリケーション・アーカイブと共にパッケージ化されたweblogic-diagnostics.xmlというXML構成ファイルを使用します。
インストゥルメンテーション・コードは、サーバーおよびアプリケーションのコード内の特定の場所に挿入(または「ウィービング」)されます。この特定の場所を表すために、以下の用語が使用されています。
「ジョインポイント」は、クラス内の特定の場所です。たとえば、メソッドの入口や出口のポイント、メソッド内の呼出しサイトなどを指します。
「ポイントカット」は、ジョインポイントのセットを示す用語で、作業項目のスケジューリング、開始、および実行に関わるすべてのメソッドなどを指します。ポイントカットを定義するXML要素は<pointcut>です。ポイントカットについては、「カスタム・モニターのポイントカットの定義」を参照してください。
「診断ロケーション」は、ジョインポイントを基準にした、診断アクティビティが実行される位置です。診断ロケーションには、前、後、前後のいずれかを指定できます。診断ロケーションを定義するXML要素は<location-type>です。
診断モニターは、そのスコープと種類によって分類されます。スコープは、サーバー・スコープかアプリケーション・スコープのどちらかです。種類は、モニターのポイントカット、診断場所、およびアクションによって決まります。たとえば、Servlet_Around_Serviceはアプリケーション・スコープの委任モニターです。このモニターを使用すると、特定のサーブレット・メソッドやJSPメソッドの入口と出口で診断アクションをトリガーできます。
インストゥルメンテーション診断モニターには、以下に示す3種類があります。
「標準モニター」は、あらかじめ定義されている特定のポイントカットおよび診断ロケーションで、あらかじめ定義されている特定の診断アクションを実行します。標準モニターでは、これらのアクション、ポイントカット、診断ロケーションはハード・コード化されています。モニターを有効または無効にできますが、モニターの動作を変更することはできません。
標準のサーバー・スコープ・モニターはDyeInjectionモニターのみです。このモニターは、サーバー・レベルで診断コンテキストを作成して仕分けの導入を構成するために使用します。第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
標準のアプリケーション・スコープ・モニターはHttpSessionDebugのみです。このモニターは、HTTP Sessionオブジェクトを検査するために使用します。
「委任モニター」では、スコープ、ポイントカット、および診断ロケーションがハード・コード化されていますが、モニターで実行するアクションは、ユーザーが選択します。「委任」という名前のとおり、このモニターでは、あらかじめ定義されているアクションに代わって、ユーザーが選択したアクションが実行されます。委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。
委任モニターは、それ自体では完成していません。委任モニターが何らかの意味のある処理を行うには、少なくとも1つのアクションをモニターに割り当てる必要があります。
すべてのアクションがどのモニターにも割当て可能なわけではありません。管理コンソールで委任モニターを構成する場合、選択したモニターで対応可能なアクションのみを指定できます。WLSTを使用する場合、または記述子ファイルを手動で編集する場合は、アクションがそのモニターで対応可能かどうかを確認する必要があります。XMLファイルがデプロイメント時にロードされたときに、検証が実行されます。
WLDFインストゥルメンテーション・ライブラリで利用可能な委任モニターとアクションについては付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
「カスタム・モニター」は、特殊なケースで使用する委任モニターで、アプリケーション・スコープのインストゥルメンテーションでのみ利用可能です。ポイントカットや診断ロケーションはあらかじめ定義されていません。
ユーザーはカスタム・モニターに名前を付け、モニターで使用するポイントカットと診断ロケーションを定義し、あらかじめ決められている診断アクションのセットからアクションを割り当てます。<pointcut>要素と<location type>要素はカスタム・モニターでは必須です。
表11-1に、各種類のモニターの違いを簡単に示します。
表11-1 診断監視のタイプ
モニター・タイプ | スコープ | ポイントカット | 場所 | アクション |
---|---|---|---|---|
標準モニター |
サーバー |
固定 |
固定 |
固定 |
委任モニター |
サーバーまたはアプリケーション |
固定 |
固定 |
構成可能 |
カスタム・モニター |
アプリケーション |
構成可能 |
構成可能 |
構成可能 |
モニターに対して「仕分けマスク」を設定すると、診断アクションがトリガーされるタイミングを制限できます。このマスクによって、診断コンテキストのどの仕分けフラグがアクションをトリガーするかが決まります。モニターの仕分けマスクの設定については、「<wldf-instrumentation-monitor> XML要素」を参照してください。
診断アクションは、関連する委任モニターまたはカスタム・モニターに対応する診断コードを実行します(標準モニターの場合、アクションはあらかじめ定義されています)。委任モニターまたはカスタム・モニターが何らかの意味のある処理を行うには、モニターに対して少なくとも1つのアクションを構成する必要があります。
WLDF診断ライブラリでは、以下のアクションを利用できます。アクションをモニターにアタッチするには、DIAG_MODULE.xml構成ファイルの<action>要素でアクション名を指定します。
DisplayArgumentsAction
StackDumpAction
ThreadDumpAction
TraceAction
TraceElapsedTimeAction
MethodInvocationStatisticsAction
アクションは、モニターに正しく対応している必要があります。たとえば、TraceElapsedTimeアクションは、診断ロケーションの種類がaroundのカスタム・モニター、または委任モニターで使用できます。詳細は、付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
インストゥルメンテーションは、診断記述子の一部としてXML構成ファイルで構成されます。このファイルの名前と格納場所は、システム・レベル(サーバー・スコープ)のインストゥルメンテーションを実装しているか、アプリケーション・レベル(アプリケーション・スコープ)のインストゥルメンテーションを実装しているかによって異なります。
システム・レベルのインストゥルメンテーション構成は、以下のディレクトリの診断記述子に格納されます。
DOMAIN_NAME/config/diagnostics
このディレクトリには、複数のシステム・レベルの診断記述子ファイルを格納できます。ファイル名は任意ですが、.xmlで終わる必要があります(myDiag.xmlは有効なファイル名です)。各ファイルには、ハーベスタ、インストゥルメンテーション、または監視および通知のうち、1つまたは複数のデプロイ可能な診断構成の構成情報を格納できます。記述子ファイルの<instrumentation>セクションでは、1つまたは複数の診断モニターを構成できます。サーバー・スコープのインストゥルメンテーションは、サーバーを再起動しなくても有効化および無効化でき、再構成も可能です。
サーバー(またはクラスタ)では、一度に1つのWLDFシステム・リソース(つまり、1つのシステム・レベルの診断記述子ファイル)のみをアクティブにできます。アクティブな記述子は、以下の構成ファイルからリンクおよび対象されます。
DOMAIN_NAME/config/config.xml
診断システム・モジュールの構成の詳細は、「診断システム・モジュールの構成」を参照してください。WebLogic Serverの構成ファイルの作成、コンテンツおよび解析の一般情報については、「Oracle WebLogic Serverドメイン構成の理解」を参照してください。
アプリケーション・レベルのインストゥルメンテーション構成は、以下の場所にあるアプリケーションのアーカイブ内にパッケージ化されます。
META-INF/weblogic-diagnostics.xml
アプリケーションにデプロイ可能な診断コンポーネントはインストゥルメンテーションだけです。したがって、この記述子には、インストゥルメンテーションの構成情報のみを格納できます。
注意: インストゥルメンテーションをアプリケーションで使用できるようにするには、アプリケーションがデプロイされるサーバーでインストゥルメンテーションを有効にする必要があります。(サーバー・スコープ・インストゥルメンテーションは、サーバーの診断記述子の<instrumentation>要素で有効にしたり無効にしたりできます)。 |
アプリケーションを再デプロイせずに診断モニターを有効にしたり無効にしたりできます。ただし、ポイントカットの定義やモニターの削除など、他のインストゥルメンテーション機能を変更した後には、アプリケーションを再デプロイする必要があります。再デプロイする必要があるかどうかは、インストゥルメンテーションの構成方法とアプリケーションのデプロイ方法によって異なります。3つの選択肢があります。
JSR-88デプロイメント・プランを使用しないで、アプリケーションのインストゥルメンテーション構成を直接定義および変更します。
インストゥルメンテーション設定のプレースホルダーを含むデプロイメント・プランを使用して、アプリケーションを構成およびデプロイします。
サーバーの起動時にホット・スワップ機能を有効にし、インストゥルメンテーション設定のプレースホルダーを含むデプロイメント・プランを使用してデプロイします。
これらの選択肢の詳細は、「インストゥルメンテーション構成を動的に制御するためのデプロイメント・プランの使用」を参照してください。
診断アプリケーション・モジュールのデプロイと変更の詳細は、第14章「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リソースの構成の概要は、第4章「WLDFの構成について」を参照してください。
この項では、記述子のコード・フラグメント、インストゥルメンテーションの構成に使用するXML要素をまとめた表、および各インストゥルメンテーション診断モニターについて簡単に説明した表を示します。
「<Instrumentation> XML要素」では、<instrumentation>要素内で使用する最上位の各要素について説明します。
「<wldf-instrumentation-monitor> XML要素」では、<wldf-instrumentation-monitor>要素内で使用する各要素について説明します。
「各モニター・タイプへの <wldf-instrumentation-monitor>のXML要素のマッピング」では、どのインストゥルメンテーション要素をどのモニターに適用するかについて説明します。
表11-2では、DIAG_MODULE.xmlファイルの<instrumentation>要素について説明します。次の構成フラグメントでは、この要素の使用方法を示します。
<wldf-resource> <name>MyDiagnosticModule</name> <instrumentation> <enabled>true</enabled> <!-- The following <include> element would apply only to an application-scoped Instrumentation descriptor --> <include>foo.bar.com.*</include> <!-- <wldf-instrumentation-monitor> elements to define diagnostic monitors for this diagnostic module --> </instrumentation> <!-- Other elements to configure this diagnostic module --> </wldf-resource>
表11-2 DIAG_MODULE.xml構成ファイル内の<instrumentation> XML要素
要素 | 説明 |
---|---|
<instrumentation> |
インストゥルメンテーション構成を開始する要素。 |
<enabled> |
trueの場合、インストゥルメンテーションは有効です。falseの場合、インストゥルメントされたコードは、このインストゥルメンテーション・スコープのクラスに挿入されておらず、このスコープ内のすべての診断モニターは無効です。デフォルト値はfalse。 サーバーとそこにデプロイされているアプリケーションに対するインストゥルメンテーションを有効にするには、サーバー・レベルでインストゥルメンテーションを有効にする必要があります。さらに、(サーバー・スコープのインストゥルメンテーションの有効化に加えて)アプリケーションに対するインストゥルメンテーションを有効にするには、アプリケーション・レベルでインストゥルメンテーションを有効にする必要があります。 |
<include> |
インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。 アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、アプリケーション・スコープ全体に適用されます。 注意: 特定の診断モニターに対して<include>パターンおよび<exclude>パターンを指定することもできます。表11-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モニターの構成は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
表11-3は、<wldf-instrumentation-monitor>要素について説明します。
表11-3 DIAG_MODULE.xmlファイルまたはweblogic-diagnostics.xmlファイル内の<wldf-instrumentation-monitor> XML要素
要素 | 説明 |
---|---|
<wldf-instrumentation-monitor> |
診断モニターの構成を開始する要素。 |
<enabled> |
trueの場合、モニターは有効です。falseの場合、モニターは無効です。各モニターを個別に有効または無効にできます。デフォルト値はtrueです。 |
<name> |
モニターの名前。標準モニターと委任モニターの場合は、付録B「WLDFインストゥルメンテーション・ライブラリ」であらかじめ定義されているモニターの名前を使用します。カスタム・モニターの場合は、モニターを識別する任意の文字列を使用できます。カスタム・モニターの名前は固有であることが必要です。つまり、ライブラリ内の他のモニターと名前が重複することはできません。 |
説明 |
モニターを説明する要素(オプション)。 |
<action> |
委任モニターとカスタム・モニターに適用される要素(オプション)。少なくともアクションを1つは指定しないと、モニターは情報を生成しません。複数の<action>要素を指定できます。アクションは、モニターのタイプに対応している必要があります。委任モニターとカスタム・モニター用にあらかじめ定義されているアクションのリストは、付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。 |
<dye-filtering-enabled> |
省略可能な要素。trueの場合、そのモニターで仕分けフィルタが有効になります。falseの場合、仕分けフィルタは無効です。デフォルト値はfalse。 仕分けフィルタを使用するには、DyeInjectionモニターをサーバー・レベルで適切に構成する必要があります。 |
<dye-mask> |
省略可能な要素。仕分けフィルタが有効になっている場合、仕分けマスクは、診断コンテキスト内の値と比較して、アクションを起こすかどうかを決定します。仕分けおよび仕分けフィルタの詳細は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。 |
<properties> |
省略可能な要素。仕分けフラグ用にname=valueのペアを設定します。 現在はDyeInjectionモニターにのみ適用されます。 |
<location-type> |
before、after、aroundのいずれかの値を持つ要素(オプション)。この要素によって、ポイントカットを基準にアクションがトリガーされるタイミング(ポイントカットの前でトリガーされるか、ポイントカットの後でトリガーされるか、ポイントカットの前後でトリガーされるか)が決まります。 カスタム・モニターの場合にのみ有効です。標準モニターおよび委任モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。 |
<pointcut> |
省略可能な要素。ポイントカット要素には、診断コードが挿入されるジョインポイントを定義する式が格納されます。 カスタム・モニターの場合にのみ有効です。標準モニターおよび委任モニターでは、この値はあらかじめ定義されています。カスタム・モニターでは、診断ロケーションの種類とポイントカットを定義する必要があります。 ポイントカットの構文については、「カスタム・モニターのポイントカットの定義」を参照してください。 |
<include> |
インストゥルメントされたコードを挿入できるクラスのリストを指定する要素(オプション)。ワイルドカード(*)がサポートされています。複数の<include>要素を指定できます。指定した場合、インストゥルメンテーションの対象となるには、クラスは<include>パターンに一致する必要があります。 アプリケーション・スコープのインストゥルメンテーションの場合にのみ有効です。<include>または<exclude>パターンを指定すると、親<wldf-instrumentation-monitor>要素で定義されるモニターにのみ適用されます。 注意:インストゥルメントされたアプリケーション・スコープ全体に対して<include>パターンおよび<exclude>パターンを指定することもできます。表11-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)
このうようにして、仕分けフィルタのメカニズムを使用すると、モニターは特定のリクエストに対してのみ診断アクションを実行でき、それによって他のリクエストの処理が遅くなることはありません。診断コンテキストおよび仕分けベクトルの詳細は、第12章「診断コンテキストを管理するためのDyeInjectionモニターの構成」を参照してください。
表11-4に、どの<wldf-instrumentation-monitor>要素がどのモニターに対応しているかを示します。
表11-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つまたは複数のサーバー・スコープ委任モニターを使用する場合は、どのモニターを使用し、各モニターにどのアクションを関連付けるかを決めます。
構成ファイル(複数可)を作成して構成します。
管理コンソールを使用して委任モニター用のDIAG_MODULE.xmlファイルを作成する場合(推奨手順)、コンソールには、そのモニターに対応するアクションのみが表示されます。エディタまたはWebLogic Scripting Tool (WLST)で構成ファイルを作成する場合は、アクションとモニターを正しく関連付ける必要があります。
詳細は、Oracle WebLogic Serverドメイン構成の理解のドメイン構成ファイルに関する項を参照してください。
デプロイメント記述子ファイルを検証してデプロイします。サーバー・スコープのインストゥルメンテーションの場合は、サーバーの実行中にモニターを追加および削除したり、モニターを有効または無効にしたりできます。
例11-1に、サーバー・スコープ・インストゥルメンテーションの構成ファイルのサンプルを示します。このサンプルでは、インストゥルメンテーションを有効にし、DyeInjection標準モニターおよびConnector_Before_Work委任モニターを構成します。1つの<instrumentation>要素に、モジュールのすべてのインストゥルメンテーションの構成が格納されます。各診断モニターは、個別の<wldf-instrumentation-monitor>要素で定義されます。
例11-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のみです。アプリケーション・スコープの標準モニターはHttpSessionDebugのみです。詳細は、「診断モニター・ライブラリ」のHttpSessionDebugの項目を参照してください。
委任モニターは、サーバー・スコープかアプリケーション・スコープのどちらかです。アプリケーションは、アプリケーション・スコープの委任モニターを使用する必要があります。
カスタム・モニターはすべてアプリケーション・スコープです。
サーバーのインストゥルメンテーション設定は、アプリケーションに影響します。インストゥルメンテーションをアプリケーションに対して有効にするには、アプリケーションがデプロイされるサーバーでインストゥルメンテーションを有効にする必要があります。デプロイメント時にサーバーのインストゥルメンテーションが有効である場合、アプリケーションでインストゥルメンテーションを利用できます。デプロイメント時にサーバーでインストゥルメンテーションが有効になっていない場合、アプリケーションでインストゥルメンテーションを有効にしても無視されます。
アプリケーションのインストゥルメンテーションが、weblogic-diagnostics.xml記述子で構成する必要があります。ユーザーはMETA-INF/weblogic-diagnostics.xmlファイルを作成し、インストゥルメンテーションを構成して、アプリケーションのアーカイブにファイルを格納します。アーカイブがデプロイされると、インストゥルメンテーションは、アプリケーションがロードされたときに自動的に挿入されます。
「デプロイメント・プラン」を使用すると、アプリケーションを再デプロイしなくても、構成要素を動的に更新できます。「インストゥルメンテーション構成を動的に制御するためのデプロイメント・プランの使用」を参照してください。
アプリケーション・スコープ・インストゥルメンテーションのXML記述子は、サーバー・スコープ・インストゥルメンテーションの場合と同じ方法で定義されます。WLDFインストゥルメンテーション・ライブラリで使用可能な委任モニターと診断アクションを使用すると、アプリケーション専用のインストゥルメンテーションを構成できます。また、ユーザー独自のカスタム・モニターも作成できますが、カスタム・モニターにアタッチする診断アクションは、WLDFインストゥルメンテーション・ライブラリから指定する必要があります。
表11-5では、システム・モジュールとアプリケーション・モジュールの機能とスコープを比較します。
注意: WLS10.3では、前のWLSリリースにおけるケースのように、アプリケーションのMETA-INFディレクトリのweblogic-diagnostics.xmlファイルを作成する必要はありません。ただし、この方法でアプリケーションの診断モニターを最初に構成することもできます。 |
アプリケーションの診断モニターを実装するには、以下の手順を実行します。
サーバーでインストゥルメンテーションが有効になっていることを確認します。「サーバー・スコープのインストゥルメンテーションの構成」を参照してください。
適切な形式のMETA-INF/weblogic-diagnostics.xml記述子ファイルをアプリケーション用に作成します。アプリケーションがデプロイされるたびに自動的に有効化されるモニターを追加する場合、以下のようにします。
<instrumentation>要素を有効(<enabled>true</enabled>)にします。
対応可能なアクションがアタッチされた診断モニターを少なくとも1つ追加して有効にします(モニターが有効になっており、イベントを生成するアクションがそのモニターにアタッチされている場合にのみ、モニターは診断イベントを生成します)。
各モニターのタイプ用に整形された記述子ファイルのサンプルについては、「委任モニターの記述子ファイルの作成」および「カスタム・モニターの記述子ファイルの作成」を参照してください。
ポイントカット式の作成については、「カスタム・モニターのポイントカットの定義」を参照してください。
アプリケーション・アーカイブに記述子ファイルを格納します。
アプリケーションをデプロイします。第14章「WLDFアプリケーション・モジュールのデプロイメント」を参照してください。
以下の点に注意します。
weblogic-diagnostics.xmlで定義された診断モニターは、管理コンソールの「デプロイメント」>「<サーバー名>」>「構成」>「インストゥルメンテーション」ページに表示されます。
アプリケーション・アーカイブのMETA-INF/weblogic-diagnostics.xml記述子がモニターを定義する場合、管理コンソールを使用することでそれを取り除くことができません。ただし、無効化や有効化は管理コンソールでも可能です。
管理コンソールから別のモニターを追加できます。管理コンソールから追加したすべてのモニターは、weblogic-diagnostics.xmlには保持されず、アプリケーションのデプロイメント計画に保存されます。この方法で追加したモニターは、管理コンソールで削除できます。
次に、アプリケーション・スコープの委任モニター用に整形された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ファイルの例を示します。このファイルには少なくとも太字で示す行を含める必要があります。
例11-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>の前の<location-type>)に呼び出されます。表11-1では、例11-2のポイントカット式の解析方法を示しています(ワイルドカードの使用に注意してください)。
表11-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 '*'? | '*'
以下のルールが適用されます。
ワイルドカード(*)は、クラスの型やメソッド名に使用できます。
引数リストの省略符号(...)は、その引数以外に任意の型の引数がいくつか(数は可変)あることを示します。
%
(パーセント記号)接頭辞は、静的でないクラスのインスタンス化、パラメータまたは戻り値を指定する値が、機密情報を含まないまたは公開しないことを指定します。この演算子は、メソッド引数または戻り値を取得するDisplayArgumentsActionアクションで特に有効です。この接頭辞が明示的に使用されていない場合は、戻される値にアスタリスクが代入されます。この動作によって、インストゥルメンテーション・イベントがジョインポイントの入力引数を取得する場合またはジョインポイントから値を戻す場合に、アプリケーション内の機密データが誤って送信されないことをことを保証します。
注意: % 演算子は、ポイントカット式内の省略記号またはワイルドカードには適用できません。 |
クラスの型に付けられた+ (プラス記号)接頭辞は、指定したクラス/インタフェース・パターンを実装しているすべてのサブクラス、サブインタフェース、または具象クラスを示します。
ポイントカット式は、適合するジョインポイントを識別するパターンを指定します。パターンに対してジョインポイントを適合させると、有効な適合かどうかを示すブール型の値が返されます。
ポイントカット式は、AND、OR、またはNOTブール演算子と組み合わせて、複雑なポイントカット式ツリーを構築できます。
たとえば、次のポイントカットは、パッケージcom.foo.barとそのサブパッケージ内のすべてのクラスの全パブリックinitializeメソッドのメソッド実行を一致対象にします。initializeメソッドは、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のゲッター・メソッドに一致します。
サーバー・スコープまたはアプリケーション・スコープのインストゥルメントを構成している場合、リクエスト・パフォーマンス・データをWebLogic Server管理コンソールに表示できます。「リクエスト・パフォーマンス」ページには、Weblogic診断フレームワーク・インストゥルメンテーション機能で取得するメソッド・パフォーマンスのリアルタイムと履歴ビューの情報が表示されます。
リクエスト・パフォーマンス・データを作成するには、次の基準が満たされる必要があります。
WLDFシステム・リソースを作成し、サーバーに対象する必要があります。「インストゥルメンテーション構成ファイル」に説明されているとおりに、システム・リソースを作成してください。これは、WebLogic Server管理コンソールまたはWebLogic Scripting Tool (WLST)を使用して行います。
対象されたWLDFシステム・リソースで、インストゥルメンテーションが有効になっている必要があります。
アプリケーション・インストゥルメンテーションは、「インストゥルメンテーション構成ファイル」に説明されているとおりに、アプリケーションのMETA-INF
ディレクトリ内に作成するweblogic-diagnostics.xml
記述子で有効にする必要があります。
アプリケーションのインストゥルメンテーションの記述子では、「Around」タイプの診断モニターにアタッチされた TraceElapsedTimeAction 診断アクションを使用する必要があります。たとえば、次のような記述が含まれる記述子を使用します。
<instrumentation> <enabled>true</enabled> <wldf-instrumentation-monitor> <name>Connector_Around_Inbound</name> <action>TraceElapsedTimeAction</action> </wldf-instrumentation-monitor> </instrumentation>
注意: WebLogic Serverでは、デプロイ済アプリケーションのインストゥルメンテーションを変更をするために、weblogic-diagnostics.xml 記述子がアプリケーションのアーカイブにプリバンドルされている必要はありません。
詳細は、第14章「WLDFアプリケーション・モジュールのデプロイ」を参照してください。 |
「前後」タイプ・モニターのリストは、付録B「WLDFインストゥルメンテーション・ライブラリ」を参照してください。
Weblogic Server管理コンソールでのリクエスト・パフォーマンス・データの作成と分析の詳細は、Oracle WebLogic Server管理コンソール・ヘルプのリクエスト・パフォーマンスの分析に関する項を参照してください。