AutoProbe および ProbeBuilding オプション

内容
apmdevops96jp
内容
AutoProbe および ProbeBuilding の概要
Java エージェントは、監視対象アプリケーションのバイトコードにプローブを挿入します。 ProbeBuilding は、ProbeBuilder ディレクティブ(PBD)および ProbeBuilder リスト(PBL)を使用してアプリケーションに挿入するプローブを決定するプロセスです。 Java エージェントに含まれるデフォルトの PBD および PBL ファイルは、基本的なレベルのメトリック コレクションを提供します。 アプリケーションおよび環境で収集するメトリックのプローブを挿入するように PBD および PBL のデフォルト設定を変更できます。
JVM でアプリケーションをインスツルメントするには、以下の
いずれかの
方法を使用します。
  • JVM AutoProbe と -javaagent プロパティ。 JVM にアプリケーションをインスツルメントする際には、JVM AutoProbe を使用することを強くお勧めします。
  • Manual ProbeBuilding は高度なインスツルメンテーション テクニックです。 この方法を使用する前に、CA サポートに連絡してください。
    手動 ProbeBuilding は最後の手段として使用する必要があります。
重要:
アプリケーションをインスツルメントする場合は、1 つのインスツルメンテーション方法のみを使用してください。
ProbeBuilding の設定
ProbeBuilding テクノロジによってインスツルメンテーション プロセスが実行されます。 ProbeBuilder ディレクティブ(PBD)ファイルで定義されたプローブが、実行時にエージェントが Web アプリケーションと仮想マシンから収集したメトリックを識別します。
デフォルトでは、AutoProbe は Java エージェントで提供される標準の PBD を使用します。 このセットアップによって、適度な数のメトリックが収集されます。 以下のオプションを使用すると、メトリック収集レベルのカスタマイズ、および ProbeBuilding の動作の設定が行えます。
フルまたは標準追跡オプション
Introscope では、ProbeBuilder リスト(PBL)ファイルで、インスツルメンテーション プロセスで使用されるトレーサ グループを制御します。
introscope.autoprobe.directivesFile
プロパティは、1 つ以上の PBL ファイルを指定します。
Introscope では、デフォルト PBL にそれぞれ 2 つのバージョンが用意されています。1 つは
フル
バージョンで、標準バージョンよりも大きなトレーサ グループ セットを指定でき、詳細なメトリック レポートが得られます。もう 1 つは
標準
バージョンで、より小さいトレーサ グループ セットを指定できます。 その結果、メトリック レポートが簡潔になり、オーバーヘッドが軽減されます。 デフォルトで、
introscope.autoprobe.directivesFile
は、標準バージョンのデフォルト PBL ファイルを指定します。
追跡レベルをフルと標準で変更できます。
以下の手順に従います。
  1. 管理対象アプリケーションを停止します。
  2. IntroscopeAgent.profile
    ファイルをテキスト エディタで開きます
  3. 使用する PBL ファイルの名前を
    introscope.autoprobe.directivesFile
    で指定します。
    たとえば、WebLogic Server のフル バージョンの標準 PBL を使用するには、以下のようにプロパティを設定します。
    introscope.autoprobe.directivesFile=weblogic-full.pbl
  4. 管理対象アプリケーションを再起動します。
    追跡レベルが指定されました。
動的 ProbeBuilding
Introscope は、動的 ProbeBuilding を使用して、管理対象アプリケーションまたはエージェントを再起動することなく、新規または変更された PBD を実装できます。 動的 ProbeBuilding は、PBD を修正する場合や、問題の切り分けまたは診断中にアプリケーション サービスを中断せずにデータ コレクション レベルを一時的に変更する場合に便利です。
重要:
動的 ProbeBuilding は、Java 1.5 以降を使用している場合にのみ利用可能です。 動的 ProbeBuilding は Java 1.5 の機能、および -javaagent コマンドに依存しています。
注:
Workstation では、トランザクション追跡ビューアから動的インスツルメンテーションを実行できます。 詳細については、「
CA APM Workstation ユーザ ガイド
」を参照してください。
動的 ProbeBuilding によって、Introscope は、新規および変更済みの PBD を定期的に検出します。 オーバーヘッドを最小化するために、Introscope は、変更された PBD により影響を受けるクラスだけを選択的に再インストルメントします。 パフォーマンスを向上させるため、エージェントの動的インスツルメンテーションの範囲は、PBD が編集されたときにインスツルメンテーションが変更されたクラスの再ロードに限定されています。
PBD が編集または hotdeploy ディレクトリに追加された場合、ユーザ ディレクティブ(クラスのディレクティブの追加または削除、またはトレーサ グループの切り替え)のみが再インスツルメントされます。
重要:
サポートされている変更は、IfFlagged スイッチを持つ TraceAllMethods のようなディレクティブへの変更など、トレーサ グループを使用するディレクティブへの変更だけです。 ただし、Introscope には、トレーサ グループまたはフラグを持つ、変更なしに使用できるディレクティブのみが含まれています。 スキップまたは変換に対する変更はサポートされていません。
以下のディレクティブは再インスツルメントされません。
  • トレーサ の追加または新しいトレーサ マッピングの変更などのシステム ディレクティブ
  • Skip ディレクティブで指定された配列、インターフェース、クラス、および任意の変換。
以下の再インスツルメントプロセスを設定できます。
  • 特定のクラスローダがロードするクラスをすべて除外する。
  • 範囲を特定のクラス パッケージに制限する。
注:
動的 ProbeBuilding はデフォルトでは無効になっています。
メトリックのデータをレポートしないようにクラスを再インスツルメントしても、メトリックは、Investigator に表示されたままになります。 既存のメトリックは、クラスが再インスツルメントされても、Investigator ウィンドウからは消えません。
重要:
Java 1.5 の制限のために、一部のクラス バイトにはアクセスすることができず、そのため以下のような影響があります。
  • j2ee.pbd ファイルへの変更がピック アップされず、メトリックは引き続き古い名前のままで公開されます。
  • エージェント ログにいくつかの例外が表示されます。
  • この問題を回避するには、j2ee.pbd ファイルを変更した後に、アプリケーション サーバを再起動します。
動的 ProbeBuilding を設定する場合は、トレーサ グループでの変更を基準にすることをお勧めします。
例: トレーサ グループ XYZ のインスツルメンテーションのレベルを制御します。
この例は、トレーサ グループのインスツルメンテーションのレベルを制御する方法を示します。
以下の手順に従います。
  1. 以下の 2 つのトレーサ グループを作成します。
    • XYZTracing - 通常の追跡オプション
    • XYZTracingLite - 限定されたコンポーネントだけが追跡されます
  2. トレーサ グループの切り替え: XYZTracing をオフにし、XYZTracingLite をオンにします。
  3. 動的 ProbeBuilding が環境のパフォーマンスに与える影響を確認します。
  4. それに応じてトレーサ グループを調整します。
    調整は、各トレーサ グループの一部として追跡中のすべてのクラスに影響します。
動的 ProbeBuilding の設定
動的 ProbeBuilding を設定するには、IntroscopeAgent.profile を編集します。
以下の手順に従います。
  1. <
    Agent_Home
    >/core/config ディレクトリに移動します。
  2. IntroscopeAgent.profile ファイルをテキスト エディタで開きます。
  3. プロパティ introscope.autoprobe.enable が true に設定されていることを確認します。
  4. 以下のプロパティのコメント化を解除して、設定します。
    • introscope.autoprobe.dynamicinstrument.enabled=true
      このプロパティを使用すると、動的 ProbeBuilding が有効になります。 このプロパティは、管理対象アプリケーションの再起動後に有効になります。
    • introscope.autoprobe.dynamicinstrument.pollIntervalMinutes=1
      PBD の変更をチェックするためのポーリング間隔(分単位)。 デフォルトは 1 分間隔に設定されています。 このプロパティは、管理対象アプリケーションの再起動後に有効になります。
    • introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs=1
      一部のクラスローダの実装では、非常に大きなクラス ファイルを返すように設定されている場合があります。 この動作はメモリ エラーを防ぎます。 このプロパティは、管理対象アプリケーションの再起動後に有効になります。
    • introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo=10
      一度に非常に多くのクラスを再定義すると、CPU に過大な負荷がかかる可能性があります。 PBD の変更によって多くのクラスを再定義することになる場合、このプロパティを使用してプロセスをいくつかにまとめて処理し、適切なレートになるようにできます。
  5. IntroscopeAgent.profile ファイルへの変更を保存し、ファイルを閉じます。
  6. 管理対象アプリケーションを再起動します(必要な場合)。
動的 ProbeBuilding と動的インスツルメンテーション
動的 ProbeBuilding と動的インスツルメンテーションは異なります。
  • 動的 ProbeBuilding は、PBD ファイルに対して手動で行った変更と、IntroscopeAgent.profile に対して行った手動による設定に基づいています。 PBD ファイルを更新または変更して適切な場所に保存すると、動的 ProbeBuilding はその変更をインスツルメントします。 動的 ProbeBuilding では、IntroscopeAgent.profile を設定し、更新する PBD ファイルを変更する必要があります。 すべての変更は、手動でそのファイルをもう一度更新または変更するまで永続します。
  • 動的インスツルメンテーションは Workstation のトランザクション追跡ビューアから実行されます。 インターフェースを使用して選択したインスツルメンテーションへの変更は自動的に行なわれ、多くの場合は一時的なものです。 メソッドを動的にインスツルメントするということは、実行時にインスツルメンテーションを挿入することを意味します。 トランザクション追跡セッション中に、1 つ以上またはすべてのメソッドをインスツルメントできます。 その後、新しくインスツルメントされたメソッドが再度表示されます。 これにより、アプリケーションのパフォーマンス チューニングを動的に実行できます。 動的インスツルメンテーションでは、IntroscopeAgent.profile の変更は必要ありません。 インスツルメンテーションの変更を恒久的なものにする場合は、PBD が適切な場所に作成され、保存されます。
    注:
    Workstation トランザクション追跡ビューアから動的インスツルメンテーションを使用する方法の詳細については、「
    CA APM Workstation ユーザ ガイド
    」を参照してください。
    重要:
    Introscope は、アプリケーション サーバのホスト コンピュータ上に動的インスツルメンテーション キャッシュを格納します。 動的インスツルメンテーションが動作するためには、アプリケーション サーバが Enterprise Manager へアクセスする際に使用するユーザ アカウントが、アプリケーション サーバのホスト コンピュータ上の <
    Agent_Home
    > ディレクトリおよび <
    Agent_Home
    >/logs ディレクトリへの書き込みアクセス権を持っている必要があります。
ProbeBuilding のクラス階層
Introscope では、クラス階層の下位レベルのクラスは自動的にはインスツルメントされません。 Introscope は、プローブされるクラスを明示的に拡張するクラスのみをインスツルメントします。
サポートされている JVM では、プローブされるクラスの複数のサブクラス レベルをインスツルメントするように Introscope を設定できます。 関連する内部ディレクティブのトレーサ グループは適切に更新され、クラスは動的にインスツルメントされます。 ディレクティブの変更は、ログ ファイルに書き込まれます。
PBD を手動で更新する場合は、ディレクティブの更新を無効にし、ログ ファイルを使用して適切な更新を判断できます。
インスツルメントおよび継承
Introscope では、JVM のクラス階層の下位レベルにあるクラスは自動的にインスツルメントされません。 プローブされるクラスの複数レベル下のサブクラスがロードされている場合は、新しいメソッドおよび優先メソッドは、自動的にはインスツルメントされません。 プローブされるインターフェースに実装中に明示的に名前を付けるクラスは、インターフェースを間接的に実装する場合でもインスツルメントされます。
たとえば、ClassB が ClassA を拡張し、ClassC が ClassB を拡張するクラス階層があるとします。
Interface/ClassA
   ClassB
    ClassC
ClassA をインスツルメントする場合、ClassB は ClassA を明示的に拡張してもインスツルメントされません。
サブクラスが確実にインスツルメントされるようにするには、「EJB サブクラスの追跡」の手順に従います。
複数レベルのサブクラスのインスツルメンテーションの有効化
内部ディレクティブを動的に更新するように Introscope を設定できます。
以下の手順に従います。
  1. 動的 ProbeBuilding が有効であることを確認します。
  2. IntroscopeAgent.profile
    を開きます。
  3. 複数レベルのサブクラスのインスツルメンテーションを有効にするには、このプロパティの設定のコメント化を解除します。
    introscope.autoprobe.hierarchysupport.enabled=true
  4. IntroscopeAgent.profile
    を保存します。
複数の継承、インターフェース、および抽象メソッドのサポート
Java エージェントは、インターフェースおよび継承によるインスツルメンテーションをサポートします。 この機能は、動的インスツルメンテーションで拡張されます。
Java エージェントでは、API の getMethodCalls を使用したサブクラスの呼び出しによって、メソッドのインスツルメンテーションをサポートします。 getMethodCalls を使用すると以下の情報が得られるため、このメソッドを使用して継承されたメソッドまたはインターフェース メソッドのインスツルメンテーションの結果をより深く理解できます。
  • メソッドを定義するクラスがインターフェースであるかどうか。
  • メソッドの実行可能なインスツルメンテーションによって影響を受けるクラスの数。 この数は、サブクラスの数または実装クラスの数です。
  • メソッドが特定のスタック トレースで呼び出されるかどうか。
以下の構文を使用すると、Java エージェントでインターフェースおよび抽象メソッドをインスツルメントするためのトレーサを使用できます。
TraceOneMethodWithlabelIfInherits: <class> <method> <Label> <Tracer Group> <Tracer Type> <Resource>
以下の場合、このトレーサは、インターフェースを実装するクラスまたはスーパークラスの拡張クラスのメソッドをインスツルメントします。
  • メソッドがインターフェースに定義されている場合。
  • スーバークラスの抽象メソッドである場合。
重要:
このトレーサを使用すると、システムのパフォーマンスに著しい影響を及ぼす可能性があります。 さらに大規模なエージェント設定にデプロイする前に、システムの起動時とインスツルメンテーションのプロセスの実行中にこのトレーサが与える影響をテストします。
インスツルメントされていないサブクラスの定期ポーリングの設定
複数レベルのサブクラスのインスツルメンテーションが有効になっている場合、Introscope は、アプリケーションの起動時に、インスツルメントされていないサブクラスをチェックします。
以下の手順に従います。
  1. IntroscopeAgent.profile
    を開きます。
  2. このプロパティの設定のコメント化を解除します。
    introscope.autoprobe.hierarchysupport.runOnceOnly=false
  3. Introscope がインスツルメントされていないサブクラスをポーリングする間隔をデフォルト値の 5 分から変更するには、このプロパティのコメント化を解除し、目的のポーリング間隔を設定します。
    introscope.autoprobe.hierarchysupport.pollIntervalMinutes
  4. オプションで、Introscope がインスツルメントされていないサブクラスをポーリングする回数を制限できます。このためには、このプロパティのコメント化を解除し、目的の制限値を設定します。
    introscope.autoprobe.hierarchysupport.executionCount
    デフォルト:
    3 分
  5. IntroscopeAgent.profile
    を保存します。
ディレクティブの更新の無効化
複数レベルのサブクラスのインスツルメンテーションが有効になっている場合、Introscope は、インスツルメントされていないサブクラスを検出すると、デフォルトで、クラスが確実にインスツルメントされるように適切に内部ディレクティブを更新します。 PBD を手動で更新する場合は、
IntroscopeAgent.profile
にあるこのプロパティの設定のコメント化を解除して、内部ディレクティブの更新を無効にできます。
introscope.autoprobe.hierarchysupport.disableDirectivesChange=true
ディレクティブのログの制御
複数レベルのサブクラスのインスツルメンテーションを有効にする場合、
IntroscopeAgent.profile
にある以下のプロパティのコメント化を解除し、複数レベルのサブクラスのインスツルメンテーションのログが作成されるようにする必要があります。 これらのプロパティが設定されると、pbdupdate.log という名前のログ ファイルが ディレクトリ(デフォルト)、またはカスタムの場所(指定した場合)に作成されます。 複数レベルのインスツルメンテーションの詳細が、エージェントのログに書き込まれます。
log4j.additivity.IntroscopeAgent.inheritance=false
log4j.logger.IntroscopeAgent.inheritance=INFO,pbdlog
log4j.appender.pbdlog.File=pbdupdate.log
log4j.appender.pbdlog=com.wily.introscope.agent.AutoNamingRollingFileAppender
log4j.appender.pbdlog.layout=com.wily.org.apache.log4j.PatternLayout
log4j.appender.pbdlog.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n_
これらのプロパティの変更を有効にするには、管理対象アプリケーションを再起動する必要があります。
バイトコード内の行番号の削除
アプリケーションのバイトコードをインスツルメントする場合、デフォルトでバイトコードの行番号が保持されます。 バイトコードの行番号情報を保持すると、デバッガを使用する場合、またはスタック トレース情報を取得する場合に役立ちます。
この機能は、Java コマンド ラインでシステム プロパティを追加することでオフにできます。 この機能をオフにすると、AutoProbe または ProbeBuilder がアプリケーション コードをインスツルメントするときにすべての行番号が削除されます。
AutoProbe または ProbeBuilder を使用する際にバイトコードの行番号を削除するには、Java のコマンド ラインで「
-D
」オプションを使用して、以下のシステム プロパティを定義します。
com.wily.probebuilder.removeLineNumbers=true
インスツルメンテーションの代替方法
このセクションでは、JVM AutoProbe を使用できないときにアプリケーションをインスツルメントするための代替方法について説明します。 あらゆる場合において、このセクションで説明する代替方法よりも JVM AutoProbe を優先して使用することをお勧めします。
レガシー -Xbootclasspath オプションの使用
標準の -javaagent プロパティを介して JVM Autoprobe を使用すると、基礎となる JVM の実装上の問題のためにオーバーヘッドが増加することがまれにあります。 IBM JVM バージョン 1.5 ~ 1.6 はそのような問題を引き起こす可能性があります。
この例では、-Xbootclasspath オプションを使用して WebSphere Application Server をインスツルメントする方法を示します。 アプリケーション上でオーバーヘッドが高くなっている場合、以下の手順を試行して JVM が根本原因になっていないか確認します。
以下の手順に従います。
  1. WebSphere Application Server で使用される Java 実行可能ファイルを AppServer/java/jre/bin ディレクトリなどで見つけます。
  2. コマンド プロンプトを開き、以下のコマンドを入力します。
    cd <
    agent_install_dir
    >/wily/connectors
    <
    path_to_WAS
    >/AppServer/java/jre/bin/java  - jar CreateAutoProbeConnector.jar  - current
    AutoprobeConnector.jar が作成されます。
  3. 以下のコマンドを入力します。
    -Xbootclasspath/p:<
    path_to_created_Autoprobe_jar
    >/AutoprobeConnector.jar:<
    path_to_agent
    >/Agent[NoRedefNoRetrans].jar
     - Dcom.wily.introscope.agentProfile=<path_to_agent>/IntroscopeAgent[NoRedef].profile
    • -Xbootclasspath/p:
      ディレクトリ、JAR アーカイブ、および ZIP アーカイブのパスをコロンで区切って指定し、デフォルトのブートストラップ クラス パスを先頭に追加して、ブートストラップ時に JVM によってデフォルトでロードされるエンティティを上書きします。
      注:
      UNIX では Xbootclasspath にコロン(:)を使用し、Windows ではセミコロン(;)を使用します。
WebSphere for z/OS の AutoProbe の設定
対象: WebSphere for z/OS 6.1 および 7.0
AutoProbe を使用してアプリケーションをインスツルメントするために、z/OS 上の WebSphere のインストールを設定できます。 AutoProbe の詳細については、「AutoProbe および ProbeBuilding オプション」を参照してください。
注:
以下の手順を使用して WebSphere 7.0 for z/OS をインスツルメントする場合には、JVM 1.5 による方法ほど詳細なメトリックは提供されません。 たとえば、スレッドのメトリック レベルはインスツルメントされません。
重要:
Java エージェント 9.0 以降を使用して z/OS 上の WebSphere 7.0 を監視している場合、アプリケーション サーバ プロセスが繰り返し再起動されることがあります。 この問題を回避するには、WAS 7.0 のビルド レベルを 7.0.0.8 以上にアップグレードします。
以下の手順に従います。
  1. WebSphere で、Administration Console を起動します。
  2. [Application Servers]-[<
    サーバ
    >]-[Process Definition]を選択します。
    [Control]と[Servant]の項目がリスト表示されます。
  3. [Servant]-[JavaVirtualMachine]をクリックします。
  4. [Generic JVM Argument]フィールドを、クラスローダ プラグイン、および IntroscopeAgent.profile ファイルの場所を指定するよう設定します。 以下のいずれかを設定します。
    com.wily.introscope.agentProfile
    または
    com.wily.introscope.agentResource
    引数は、以下の値を持ちます(1 つの引数で複数のプロパティが設定されています)。
    -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api.websphere.WASAutoProbe
    -Dcom.wily.introscope.agentProfile=<path to IntroscopeAgent.profile>
    または
    -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api.websphere.WASAutoProbe
    -Dcom.wily.introscope.agentResource=<
    path to Resource containing IntroscopeAgent.profile
    >
  5. Agent.jar ファイルを
    <WebSphere インスタンス ディレクトリ>
    /lib/ext ディレクトリに配置します。
    注:
    Agent.jar ファイルを WebSphere インストール ディレクトリに配置しないでください。
    以下に間違ったディレクトリと正しいディレクトリの例を示します。
    Incorrect: /usr/lpp/zWebSphere/V5R0M0/lib/ext
    Correct: /WebSphere/V5R0M0/AppServer/lib/ext
  6. ./wily ディレクトリ内にある新しく作成されたすべての Introscope ファイルおよびディレクトリに、WebSphere プロセスから読み取りアクセスできることを確認します。
  7. すべての *.log ファイルが WebSphere プロセスへの書き込みアクセス権を持つことを確認します。 Java エージェントおよび ProbeBuilder は、これらのファイルを ./wily フォルダに書き込みます。 これらのファイルには以下のものが含まれます。
    • すべての Introscope ファイルおよびディレクトリ
    • <WAS インスタンス ディレクトリ>
      /lib/ext にある Introscopeの ファイル
  8. WebSphere アプリケーション サーバを再起動します。
  9. WebSphere によって「open for e-business」が通知され、Administration Console が開きます。
    メトリックのレポートが開始されます。
  10. Java2 のセキュリティを有効にした WebSphere 環境で AutoProbe を正しく実行するには、Java2 セキュリティ ポリシーへのアクセス権の追加を行います
  11. HTTP サーブレットの追跡を設定してサーブレット データを収集します。