ヘルプ 管理 監視の追加 APMインサイト（Javaエージェント版）

APMインサイト（Javaエージェント版）

APMインサイトは、データ取得と送信に、エージェント ベースのインストルメント技術を利用します。APMインサイト（Javaエージェント）は、Java 1.5以上が稼働するアプリケーション サーバーで動作します。

サポートするアプリケーション サーバー
  • Glassfish 3.x以上
  • Oracle WebLogic 10.3.x以上
  • IBM WebSphere 7.x以上
  • Resin 3.1.x以上
  • JBoss AS 4.x以上
  • Tomcat 6.x以上
  • JBoss EAP 6.2.x以上
  • WildFly 8.x以上
  • Jetty
サポートするJDBCドライバー
  • MySQL
  • Sybase：jconn2、jconn3、jconn4
  • Postgres
  • MS-SQL
  • IBM DB2：db2jcc、jt400
  • Generic JDBC drivers
  • Oracle：ojdbc14、ojdbc5、ojdbc6
サポートするフレームワークとコンポーネント
  • Struts 1.x、2.x
  • Hibernate 3.x、4.x
  • Spring
  • IBatis
  • Servlets
  • EJB
  • フィルター
  • Play 1.x
  • JSP

ご利用手順

APMインサイト（Javaエージェント版）のインストール

  1. APM > APMインサイトと選択してださい。
  2. Javaタブをクリックし、APMinsight-javaagent.ZIPファイルをダウンロード。
  3. ダウンロードをクリックし、アプリケーション サーバーにエージェントを展開します。ZIPファイルには、apminsight-javaagent.zipと、その設定ファイルが入っています。
    Javaエージェント

GlassFishサーバーへのJavaエージェント インストール

スタンドアロン構成の場合:
  1. GlassFishサーバー ディレクトリの外部に新規ディレクトリを用意し、ZIPファイルを解凍します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. GlassFishサーバーの管理コンソールを開いてください。設定、サーバーで使用している設定と開きます。
  4. JVM設定 > JVMオプションと選択し、次のパラメーターを追加。
    -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    例：-javaagent:D:/apminsight/apminsight-javaagent.jar
  5. 保存ボタンをクリックし、GlassFishサーバーを起動してください。
クラスター設定の場合:
  1. ZIPファイルを、GlassFishサーバー ディレクトリの外で、新規ディレクトリに解凍。
  2. APMinsight-javaagent.jarファイルを上記ディレクトリから、ドメイン サーバーの <GLASSFISH_HOME>\glassfish\domains\<domain>\lib\extディレクトリにコピーしてください。
  3. 新規ディレクトリ「apminsight」を、サーバー インスタンスの<GLASSFISH_HOME>\glassfish\nodes\<node>\<instance>に作成し、エージェント設定ファイルのみを、このディレクトリにコピーします。
  4. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  5. 上記の手順を、各インスタンスで繰り返してください。
  6. GlassFishサーバーの管理コンソールを開いてください。設定を選択し、クラスターが使用している設定を選びます。
  7. JVM設定 > JVMオプションと選択し、次のパラメーターを追加。
    -javaagent:${com.sun.aas.instanceRoot}/lib/ext/apminsight-javaagent.jar
    -Dapminsight.home=${com.sun.aas.instanceRoot}/apminsight
     
    APM：Java1
  8. 保存ボタンをクリックし、GlassFishクラスターを起動します。

JBoss AS 4.2以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
    3. エージェント設定のチューニングする
    JBoss AS 7.2.xにはバグがあり、Javaエージェント（APMインサイト）のサーバーへの展開の妨げになります。JBossサーバーのアップグレードを実行のうえ、エージェントのインストールへ進むことをお勧めします。
JBoss AS 4.x、5.xサーバーの場合:
  1. Windowsでは、<JBOSS_HOME>\bin\run.batトップに、テキスト エディターで下記を加筆し保存してください。
    set JAVA_OPTS=-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar %JAVA_OPTS%
  2. Linuxでは、<JBOSS_HOME>/bin/run.shトップに、テキスト エディターで下記を加筆し保存してください。
    export JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
JBoss AS 6.xサーバーの場合:
  1. Windowsでは、<JBOSS_HOME>\bin\run.batトップに、テキスト エディターで下記を加筆し保存してください。
    set JAVA_OPTS=-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/lib/jboss-logmanager.jar %JAVA_OPTS%
  2. Linuxでは、<JBOSS_HOME>/bin/run.shトップに、テキスト エディターで下記を加筆し保存してください。
    export JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/lib/jboss-logmanager.jar"
JBoss AS 7.xサーバーの場合:
  1. スタンドアロン設定の場合：
    <JBOSS_HOME>/bin/standalone.bat（Linuxでは、standalone.sh）を編集し、次のJava引数を既存のJAVA_OPTSに追加してください。
    -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.manageengine -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/modules/org/jboss/logmanager/main/ jboss-logmanager-<version>.jar -Xbootclasspath/p:<JBOSS_HOME>/modules/org/jboss/logmanager/log4j/main/ jboss-logmanager-log4j-<version>.jar -Xbootclasspath/p:<JBOSS_HOME>/modules/org/apache/log4j/main/ log4j-<version>.jar -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
  2. ドメイン設定の場合：
    <JBOSS_HOME>/domain/configuration/Host.xmlファイルを編集し、<servers>タグを見つけ、希望の<server name="your_server" ...> にタグを追加します。
    < system-properties>
            <property name="java.util.logging.manager" value="org.jboss.logmanager.LogManager" boot-time="true"/>
            <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,org.jboss.logmanager,com.manageengine" boottime="true"/>
    </system-properties>
    <jvm name="insight">
    <jvm-options>
            <option value="-Xbootclasspath/p:<JBOSS_HOME>/modules/org/jboss/logmanager/main/jboss-logmanager-<version>.jar" />
            <option value="-Xbootclasspath/p:<JBOSS_HOME>/modules/org/jboss/logmanager/log4j/main/jboss-logmanager-log4j-<version>.jar" />
            <option value="-Xbootclasspath/p:<JBOSS_HOME>/modules/org/apache/log4j/main/log4j-<version>.jar" />
            <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
    ロガーjarの名前はJBoss ASのバージョンにより異なります。適宜、変更を加えてください。
  3. ファイルを保存し、JBossアプリケーション サーバーを再起動してください。

JBoss EAP 6.2以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. スタンドアロン設定の場合：
    <JBOSS_HOME>/bin/standalone.bat（Linuxでは、standalone.sh）を編集し、次のJava引数を既存のJAVA_OPTSに追加してください。
    -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.manageengine -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-<version>.jar -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
  4. ドメイン設定の場合：
    <JBOSS_HOME>/domain/configuration/Host.xmlファイルを編集、<servers>タグを見つけ、希望の<server name="your_server" ...>にタグを追加します。
    <system-properties>
            <property name="java.util.logging.manager" value="org.jboss.logmanager.LogManager" boot-time="true"/>
            <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,org.jboss.logmanager,com.manageengine" boottime="true"/>
    </system-properties>
    <jvm name="insight">
    <jvm-options>
            <option value="-Xbootclasspath/p:<JBOSS_HOME>/modules/org/jboss/logmanager/main/jboss-logmanager-<version>.jar" />
            <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
    ロガーjarの名前はJBoss EAPのバージョンにより異なります。適宜、変更を加えてください。
  5. ファイルを保存し、JBoss EAPを再起動してください。

Tomcat Server 6以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. Tomcatを非サービスとしてインストールするには、
  4. Windowsでは、<TOMCAT_HOME>\bin\catalina.batを編集し、次の項目を最上部に追加してファイルを保存します。
    set JAVA_OPTS=%JAVA_OPTS% -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
  5. Linuxでは、<TOMCAT_HOME>/bin/catalina.shを編集し、次の項目を最上部に追加してファイルを保存します。
    export JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
  6. Tomcatをサービスとして導入するには、nTomcatの設定 > Javaタブ と移動し、Javaオプション欄に次のエントリを追加します。
    -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar in Java Options box.
    APM：Java2 
  7. 追加が終わったら、「適用」をクリック。
  8. Tomcatを起動してください。

WebSphere 7以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. IBM WebSphere Serverの管理コンソールを開き、サーバー > サーバー タイプ > WebSphereアプリケーション サーバーと選択。
    APM：Java3
  4. サーバー名 > Javaおよびプロセス管理 > プロセス定義 と選択します。
    APM：Java4 
  5. 追加プロパティの下で、Java仮想マシンを選択。
    APM：Java5
  6. 汎用JVM引数のテキストボックスを見つけ、次のパラメーターを入力してください。
    -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    APM：Java6 
  7. 設定を保存し、WebSphere Serverを起動してください。

WebLogic 10.3以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. WebLogic Serverの管理コンソールを開き、環境 > サーバー > 設定タブと選択してください。
  4. サーバー名> 設定> サーバー起動タブと選択。
  5. 引数の入力欄を見つけ、下記の通り入力します。
    -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    APM：Java7 
  6. 設定を保存し、WebLogic Serverを起動します

Resinサーバー3.1以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. Resinサーバーの3.xの場合は、<RESIN_HOME>/conf/resin.confファイルをテキスト エディターで開きます。監視するサーバーの <cluster> タグと <server> タグを見つけ、次のタグを追加してください。
    <jvm-arg>-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar</jvm-arg>
  4. Resinサーバーの4.xの場合は、<RESIN_HOME>/conf/resin.xmlファイルをテキスト エディターで開きます。監視するサーバーの <cluster> タグと <server> タグを見つけ、次のタグを追加してください。
    <jvm-arg>-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar</jvm-arg>
  5. ファイルを保存し、Resinサーバーを再起動してください。

WildFly 8以上へのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。エージェント設定のチューニングをするには、 APMインサイト設定ファイルを参照ください。
  3. スタンドアロン設定の場合：
    <WILDFLY_HOME>/bin/standalone.conf.bat（Linuxでは、standalone.conf）ファイルを編集し、次のJava引数を既存のJAVA_OPTSに追加してください。
    -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.manageengine -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<WILDFLY_HOME>/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-<version>.jar -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
  4. ドメイン設定の場合：
    <WILDFLY_HOME>/domain/configuration/Host.xmlファイルを編集、<servers>タグを見つけ、希望の <server name="your_server" ...> <system-properties> の下に、下記のタグ記載を追加してください。
    < property name="java.util.logging.manager" value="org.jboss.logmanager.LogManager" boot-time="true"/>
            <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,org.jboss.logmanager,com.manageengine" boottime="true"/>
    </system-properties>
    <jvm name="insight">
    <jvm-options>
            <option value="-Xbootclasspath/p:<WILDFLY_HOME>/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-<version>.jar" />
            <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
    ロガーjarの名称は、WildFlyサーバーのバージョンによって異なるため、適宜、変更を行います。
  5. ファイルを保存し、WildFlyサーバーを再起動してください。

その他のサーバーへのJavaエージェント インストール

  1. ZIPファイルを新規ディレクトリに解凍し、jarエージェントと設定ファイルを確認します。
  2. apminsight.confファイルをテキスト エディターで開き、APMインサイト ページで入手したlicense.key値を追記してください。APMインサイト設定ファイルを参照ください。
  3. Windowsでは、<your application server startup script>.batを、テキスト エディターで開き、スタートアップ スクリプトの冒頭に次の記載をします。
    SET JAVA_OPTS=%JAVA_OPTS% -javaagent:"<agent_directory_full_path>/apminsight-javaagent.jar"
    例：
    SET JAVA_OPTS=%JAVA_OPTS% -javaagent:"D:/apminsight/apminsight-javaagent.jar"
  4. Linuxでは、<your application server startup script>.shを、テキスト エディターで開き、スタートアップ スクリプトの冒頭に次の記載をします。
    export JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
    例：
    export JAVA_OPTS="$JAVA_OPTS -javaagent:/home/local/softwares/apminsight/apminsight-javaagent.jar"
  5. ファイルを保存し、サーバーを起動してください。

APMインサイト設定ファイル

  1. 一部の項目は、クライアントから操作できません。apminsight.confファイルから設定してください。
  2. 設定オプションの確認には、APMインサイト設定ファイルを参照してください。

バックッグラウンド通信の追跡

  1. バックグラウンド トランザクションの設定については、こちらを参照ください。

カスタム インストルメント

APMインサイトのエージェントではWebコンポーネントとフレームワークについて、設定済みクラスを、アプリケーションに組み込むことができます。APMインサイトは、クラスを選んでのカスタム インストルメントも可能です。カスタム インストルメントによって、アプリケーション内部のことが分かりやすくなり、アプリの特定機能やモジュールのパフォーマンス追跡が容易となります。

Javaエージェントの設定手順

  1. クラスを選択してインストルメントを行うには、クラス名を「custom_instrumentation.conf」ファイルで、下記フォーマットの通り、記載してください。
    Fully qualified class name : Methods to be instrumented
  2. 複数メソッドを記載するには、コンマ「,」で区切ってください。組み込みメソッドを空白にしておくと、指定クラスの全メソッドがインストルメントされます。インストルメントするオーバーロード用メソッドを記載すれば、オーバーロードされるメソッドがすべてインストルメントされます。それぞれのクラスのエントリは、行ごとに記載してください。
    例：
    a/b/c/CustomClass : methodA, methodB
    a/b/c/CustomClass :
  3. パッケージが含む全クラスを組み込む場合は、パッケージ名を以下のように記述します。
    package_name/.* :
    例：
    a/b/c/.* :
  4. パッケージ自体の指定は推奨されません。エージェントから、全クラスの全メソッドがインストルメントされ、CPUとメモリに追加の負荷がかかります。また、後になって、多くのメソッドは利用中のアプリと無関係と判明することがほとんどのうえ、トレース実行も時間がかかります。ただし、パッケージ自体の指定は、コードの流れを調べる目的であれば、選択肢となりえます。
    アプリケーション サーバーを再起動すると、変更が有効になります。

Javaアノテーションによるカスタム インストルメント

Javaアノテーションの利用によって、APMインサイトは、アプリケーションのクラスとメソッドを、容易にカスタム インストルメント可能です。Javaアノテーションの利用で、トランザクションにカスタム名を定義したり、コンポーネントを割り当てたりできます。

この機能は、エージェントのバージョン2.2から利用できます。

Javaエージェントの設定手順

  1. 要件としては、apminsight-javaagent.zipのダウンロードが必須です。これには、agent .jarと関連ファイルに加え、apminsight-javaagent-api.jarが含まれています。
  2. apminsight-javaagent-api.jarファイルをプロジェクト ビルド パスに含め、.jarファイルをアプリケーションのライブラリとあわせてエクスポートしてください。
  3. カスタム クラスやメソッドをインストルメントするには、2つのアノテーションを利用できます。
  • APM Tracker：組み込みやトレース取得の対象とする、あらゆるクラスとメソッドに使えます。
  • APM Root Tracker：トランザクション実行の開始点となるメソッドに利用できます。

APM Tracker

APM Trackerアノテーションはクラスとメソッドで使えます。クラスに利用すると、そのクラスのメソッドに属性が適用されます。これにより、メソッド横断で、アノテーションのオーバーライドができます。

属性：

component - Default Value: POJO (Plain Java Object)

これにより、アノテーション対象の要素に、コンポーネント名が定義されます。この属性の利用は、任意です。

例：

ケース1：クラスでの使い方
@ApmTracker
    public class Category {
    ...
}

ケース2：
@ApmTracker(component="payment")
    public class PaymentProcessor {
    ...
}

ケース3：メソッドでの使い方
public class Product {
    @ApmTracker
    public int getPrice(String product, String brand) {
    ...
}
  ...
@ApmTracker(component="FetchBrand")
    private List fetchAllBrandsList(String product) {
    ...
    }
}

APM Root Tracker

APM Root Trackerアノテーションは、メソッドにのみ利用できます。アノテーションを受けたメソッドが、トランザクション処理をサーバーで行う際の、起動点です。これ以降、トランザクションはtxnName属性の値で、読み替えられます。それ以外の場合は、通常のメソッド呼び出しの扱いとなり、トレースに含まれることとなります。

属性：

txnName ：必須属性

この属性の値は、トランザクションの命名に利用されます。これは必須属性です。

component ：Default Value: POJO

これにより、アノテーション対象の要素に、コンポーネント名が定義されます。この属性の利用は、任意です。

例：

public class AppService {
    @ApmRootTracker(txnName="Service-Initialisation")
    public void init() {
    ...
    }
}

類似トランザクションのグループ化

トランザクション名が動的に決まることは、多くのアプリケーションで、日常化しています。そのため、アプリケーションのパフォーマンス追跡は、困難になりつつあります。動的Webトランザクションの場合、アプリケーションは同一URLを提示するもの、起動のたびに一意の識別子（英数字）を埋め込むため、トランザクション名自体が別物に見えるのです。このようなURLを、それぞれ追跡するのは、手間がかかりすぎます。Site24x7の類似トランザクション グループ化機能を利用すれば、多くの動的トランザクションを、監視すべき実際のURLへ、まとめることが可能となります。

Javaエージェントの設定手順

  • 新規ファイルを「transaction_merge_patterns.conf」名で、apminsight.confのあるディレクトリに作成します。
  • ファイルをエディターで開き、下記構文のとおりに、キー・バリューのペアを記載してください。
  • 指定内容は、URLやWebトランザクションの正規表現（キー）=新しい割り当て名（バリュー）です。
    例：
    WebトランザクションのURL例：

    ebay/shop/item/chocolate/nestle
    ebay/shop/item/chocolate/snickers
    ebay/shop/item/chocolate/orion
    ebay/shop/item/stationary/pencil
    ebay/shop/item/stationary/pen

    transaction_merge_patterns.confでの指定方法は、次のようになります。

    ebay/shop/item/chocolate/.*=ebay/shop/chocolate
    ebay/shop/item/stationary/.*=ebay/shop/stationary
    ebay/shop/item/.*=ebay/shop/others

  • 変更を有効にするには、アプリケーション サーバーの再起動が必要です。