AutoProbe および ProbeBuilding オプション

Java Agent は、監視するアプリケーションのバイトコードにプローブを挿入します。ProbeBuilding は、ProbeBuilder ディレクティブ(PBD)および ProbeBuilder リスト(PBL)を使用してアプリケーションに挿入するプローブを決定するプロセスです。Java Agent に含まれるデフォルトの PBD および PBL ファイルは、基本的なレベルのメトリック コレクションを提供します。PBD および PBL のデフォルト設定を変更して、収集するメトリックのプローブを挿入することができます。エージェントは、アプリケーションおよび環境内のメトリックを収集します。
apmsaas
Java Agent は、監視するアプリケーションのバイトコードにプローブを挿入します。ProbeBuilding は、ProbeBuilder ディレクティブ(PBD)および ProbeBuilder リスト(PBL)を使用してアプリケーションに挿入するプローブを決定するプロセスです。Java Agent に含まれるデフォルトの PBD および PBL ファイルは、基本的なレベルのメトリック コレクションを提供します。PBD および PBL のデフォルト設定を変更して、収集するメトリックのプローブを挿入することができます。エージェントは、アプリケーションおよび環境内のメトリックを収集します。
3
2
AutoProbe および ProbeBuilding の概要
JVM でアプリケーションをインスツルメントするには、以下の
いずれかの
方法を使用します。
  • JVM AutoProbe と
    -javaagent
    プロパティを使用します。JVM で JVM AutoProbe を使用してアプリケーションをインスツルメントすることを強くお勧めします。
  • Manual ProbeBuilding は高度なインスツルメンテーション テクニックです。
アプリケーションをインスツルメントする場合は、1 つのインスツルメンテーション方法のみを使用します。
ProbeBuilding の設定
ProbeBuilding テクノロジによってインスツルメンテーション プロセスが実行されます。ProbeBuilder ディレクティブ ファイルは、プローブを定義して、実行時にエージェントが Web アプリケーションと仮想マシンから収集したメトリックを識別します。
デフォルトでは、AutoProbe は Java エージェントで提供される標準の PBD を使用します。このセットアップによって、適度な数のメトリックが収集されます。以下のオプションを使用すると、メトリック コレクション レベルのカスタマイズ、および ProbeBuilding の動作の設定が行えます。
フルまたは標準追跡オプション
Introscope では、ProbeBuilder リスト(PBL)ファイルで、インスツルメンテーション プロセスで使用されるトレーサ グループを制御します。
introscope.autoprobe.directivesFile
プロパティは、1 つ以上の PBL ファイルを指定します。
Introscope では、2 つの各デフォルト PBL が提供されます。
フル
バージョンにより、標準バージョンより大きなトレーサ グループ セットが可能になり、詳細なメトリック レポートが生成されます。
標準
バージョンは、より小さいトレーサ グループが可能になり、簡潔なメトリック レポートが生成され、オーバーヘッドが軽減されます。
デフォルトで、
introscope.autoprobe.directivesFile
は、標準バージョンのデフォルト PBL ファイルを指定します。
追跡レベルをフルと標準で変更できます。
以下の手順に従います。
  1. マネージド アプリケーションを停止します。
  2. <Agent_Home>\releases\<release_number>\core\config
    ディレクトリに移動します。
  3. IntroscopeAgent.profile
    ファイルをテキスト エディタで開きます。
  4. 使用する PBL ファイルの名前を
    introscope.autoprobe.directivesFile
    で指定します。
    たとえば、WebLogic Server のフル バージョンの標準 PBL を使用するには、以下のようにプロパティを設定します。
    introscope.autoprobe.directivesFile=weblogic-full.pbl
  5. マネージド アプリケーションを再起動します。
    追跡レベルが指定されました。
動的 ProbeBuilding
Introscope は、動的 ProbeBuilding を使用して、管理対象アプリケーションまたはエージェントを再起動することなく、新規または変更された PBD を実装できます。動的 ProbeBuilding は、PBD を修正する場合や、問題の切り分けまたは診断中にアプリケーション サービスを中断せずにデータ コレクション レベルを一時的に変更する場合に便利です。
動的 ProbeBuilding は、Java 1.5 以降を使用している場合にのみ利用可能です。動的 ProbeBuilding は Java 1.5 の機能、および -javaagent コマンドに依存しています。
動的 ProbeBuilding によって、Introscope は、新規および変更済みの PBD を定期的に検出します。エージェントの動的インスツルメンテーションの範囲は、PBD が編集されたときにインスツルメンテーションが変更されたクラスの再ロードに限定されています。この、より制限された範囲によってパフォーマンスが向上します。
PBD を編集または hotdeploy ディレクトリに追加すると、特定のユーザ ディレクティブのみが再インスツルメントされます。(クラスのディレクティブの追加や削除、またはトレーサ グループの切り替えなど)
トレーサ グループを使用するディレクティブへの変更のみがサポートされます。たとえば、
TraceAllMethods
のように、
IfFlagged
スイッチを持つディレクティブを変更した場合などです。ただし、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>\releases\<release_number>\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 の変更によって多くのクラスを再定義することになる場合、
      introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo
      を使用してプロセスをいくつかにまとめて処理し、適切なレートになるようにできます。
  5. ファイルを保存して閉じます。
  6. 管理対象アプリケーションを再起動します(必要な場合)。
ProbeBuilding のクラス階層
Introscope では、クラス階層の下位レベルのクラスは自動的にはインスツルメントされません。Introscope は、プローブされるクラスを明示的に拡張するクラスのみをインスツルメントします。
サポートされている JVM では、プローブされるクラスの複数のサブクラス レベルをインスツルメントするように Introscope を設定できます。関連する内部ディレクティブのトレーサ グループは適切に更新され、クラスは動的にインスツルメントされます。ディレクティブの変更は、ログ ファイルに書き込まれます。
PBD を手動で更新する場合は、ディレクティブの更新を無効にします。ログ ファイルを使用して適切な更新を判断できます。
インスツルメントおよび継承
Introscope では、JVM のクラス階層の下位レベルにあるクラスは自動的にインスツルメントされません。プローブされるクラスの 2 レベル以上深いクラスおよびサブクラスがロードされている場合は、新しいメソッドおよび優先メソッドは、自動的にはインスツルメントされません。プローブされるインターフェースに実装中に明示的に名前を付けるクラスは、インターフェースを間接的に実装する場合でもインスツルメントされます。
たとえば、
ClassB
ClassA
を拡張し、
ClassC
ClassB
を拡張するクラス階層があるとします。
Interface/ClassA
ClassB
ClassC
ClassA
をインスツルメントする場合、
ClassB
ClassA
を明示的に拡張してもインスツルメントされません。
サブクラスが確実にインスツルメントされるようにするには、「EJB サブクラスの追跡」の手順に従います。
複数レベルのサブクラスのインスツルメンテーションの有効化
内部ディレクティブを動的に更新するように Java エージェントを設定できます。
以下の手順に従います。
  1. 動的 ProbeBuilding が有効であることを確認します。
  2. <Agent_Home>\releases\<release_number>\core\config
    ディレクトリに移動します。
  3. IntroscopeAgent.profile
    ファイルをテキスト エディタで開きます。
  4. 複数レベルのサブクラスのインスツルメンテーションを有効にするには、このプロパティの設定のコメント化を解除します。
    introscope.autoprobe.hierarchysupport.enabled=true
  5. ファイルを保存して閉じます
複数の継承、インターフェース、および抽象メソッドのサポート
Java Agent は、インターフェースおよび継承によるインスツルメンテーションをサポートします。
Java エージェントでは、API の
getMethodCalls
を使用したサブクラスの呼び出しによって、メソッドのインスツルメンテーションをサポートします。
getMethodCalls
API は、継承されたメソッドまたはインターフェース メソッドのインスツルメンテーションの影響を理解するのに役立つ以下の情報を提供します。
  • メソッドを定義するクラスがインターフェースであるかどうか。
  • メソッドの実行可能なインスツルメンテーションによって影響を受けるクラスの数。この数は、サブクラスの数または実装クラスの数です。
  • メソッドが特定のスタック トレースで呼び出されるかどうか。
以下の構文を使用すると、Java エージェントでインターフェースおよび抽象メソッドをインスツルメントするためのトレーサを使用できます。
TraceOneMethodWithlabelIfInherits: <class> <method> <Label> <Tracer Group> <Tracer Type> <Resource>
以下の場合、このトレーサは、インターフェースを実装するクラスまたはスーパークラスの拡張クラスのメソッドをインスツルメントします。
  • メソッドがインターフェースに定義されている場合
  • スーバークラスの抽象メソッドである場合
このトレーサを使用すると、システムのパフォーマンスに著しい影響を及ぼす可能性があります。システムの起動時とインスツルメンテーション プロセスの実行中にこのトレーサによる影響をテストしてください。大きなエージェント構成を展開する前に、このテストを実行してください。
インスツルメントされていないサブクラスの定期ポーリングの設定
複数レベルのサブクラスのインスツルメンテーションが有効になっている場合、エージェントは、アプリケーションの起動時に、インスツルメントされていないサブクラスをチェックします。
以下の手順に従います。
  1. <Agent_Home>\releases\<release_number>\core\config
    ディレクトリに移動します。
  2. IntroscopeAgent.profile
    ファイルをテキスト エディタで開きます。
  3. このプロパティの設定のコメント化を解除します。
    introscope.autoprobe.hierarchysupport.runOnceOnly=false
  4. Introscope がインスツルメントされていないサブクラスをポーリングする間隔を変更するには、
    introscope.autoprobe.hierarchysupport.pollIntervalMinutes
    のコメント化を解除し、目的のポーリング間隔を設定します。
    introscope.autoprobe.hierarchysupport.pollIntervalMinutes
    デフォルト
    : 5 (分)
  5. (オプション) Introscope がインスツルメントされていないサブクラスをポーリングする回数を制限できます。このためには、
    introscope.autoprobe.hierarchysupport.executionCount
    のコメント化を解除し、
    目的の制限値を設定します。
    introscope.autoprobe.hierarchysupport.executionCount
    デフォルト:
    3 分
  6. ファイルを保存して閉じます。
ディレクティブの更新の無効化
Introscope がインスツルメントされていないサブクラスを検出すると、複数レベルのサブクラスのインスツルメンテーションにより、内部ディレクティブが適切に更新されます。この更新によって、クラスは確実にインスツルメントされます。PBD を手動で更新する場合は、IntroscopeAgent.profile にある
introscope.autoprobe.hierarchysupport.disableDirectivesChange
のコメント化を解除して、内部ディレクティブの更新を無効にできます。
introscope.autoprobe.hierarchysupport.disableDirectivesChange=true
ディレクティブのログの制御
複数レベルのサブクラスのインスツルメンテーションを有効にする場合、IntroscopeAgent.profile にある以下のプロパティのコメント化を解除し、複数レベルのサブクラスのインスツルメンテーションのログが作成されるようにします。これらのプロパティを設定すると、Introscope によって pbdupdate.log ファイルが
<Agent_Home>
ディレクトリ、または指定したカスタムの場所に作成されます。複数レベルのインスツルメンテーションの詳細が、エージェントのログに書き込まれます。
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
コマンドの使用には、以下の制限があります。
  • IBM JRE バージョン 1.7 以降では、このコマンドはサポートされていません。
  • スマート インスツルメンテーションは無効です。
この例では、
-Xbootclasspath
オプションを使用して WebSphere Application Server をインスツルメントする方法を示します。アプリケーション上でオーバーヘッドが高くなっている場合、以下の手順を試行して JVM が根本原因になっていないか確認します。
以下の手順に従います。
  1. WebSphere Application Server で使用される Java 実行可能ファイルを AppServer/java/jre/bin ディレクトリなどで見つけます。
  2. コマンド プロンプトを開きます。以下のコマンドを入力します。
    cd <Agent_Home>\releases\<release_number>/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 のインストールを設定できます。
以下の手順を使用して 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.agentResource=<Path to Resource containing IntroscopeAgent.profile>
  5. Agent.jar ファイルを <WebSphere_Home>/lib/ext ディレクトリに配置します。
    Agent.jar ファイルを WebSphere インストール ディレクトリに配置しないでください。
    以下に間違ったディレクトリと正しいディレクトリの例を示します。
    Incorrect: /usr/lpp/zWebSphere/V5R0M0/lib/ext
    Correct: /WebSphere/V5R0M0/AppServer/lib/ext
  6. <Agent_Home> ディレクトリ内にある新しく作成されたすべての Java エージェント ファイルおよびディレクトリに、WebSphere プロセスから読み取りアクセスできることを確認します。
  7. すべての *.log ファイルが WebSphere プロセスへの書き込みアクセス権を持つことを確認します。Java エージェントおよび ProbeBuilder は、これらのファイルを <Agent_Home> フォルダに書き込みます。これらのファイルには以下のものが含まれます。
    • すべての Introscope ファイルおよびディレクトリ
    • <
      WebSphere_Home
      >
      /lib/ext にある Introscope のファイル
  8. WebSphere アプリケーション サーバを再起動します。
  9. WebSphere によって「
    open for e-business
    」が表示され、Administration Console が開きます。
    メトリックのレポートが開始されます。
  10. Java2 のセキュリティを有効にした WebSphere 環境で AutoProbe を正しく実行するには、Java2 セキュリティ ポリシーへのアクセス権の追加を行います。
  11. HTTP サーブレットの追跡を設定してサーブレット データを収集します。
https://docops.ca.com/display/APMDEVOPS/.Java+Agent+Directory+Structure+vSaaS