このページでは、Red Hat JBoss Enterprise アプリケーションサーバと JBoss Wildfly に AppDynamics Java エージェントをインストールする方法について説明します。 

インストールする前に

JBoss または Wildfly にエージェントをインストールするには、Java エージェントおよびログマネージャのパッケージをサーバ起動ルーチンに追加します。

構成されている場所は、フレームワークのバージョンによって異なります。

  • Linux では、設定を standalone.conf または standalone.sh に追加する。
  • Windows では、設定を standalone.conf.bat に追加する。
  • JBoss 4.x または 5.x を使用している場合は、run.sh（Linux の場合）または run.bat（Windows の場合）に構成を追加します。

JVM の初期化

JBoss EAP または JBoss Wildfly に Java エージェントをインストールするには、JVM を初期化する必要があります。次のパラメータを実行します。

JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity"

JVM を初期化しない場合、インストールで「class not found」例外が生成されます。 

スタンドアロンモードエージェントのインストール

次の手順では、Red Hat JBoss（Application Server 7.x または Enterprise Application Server 6.x 以降）を使用することが前提となっています。 

JBossスタンドアロンにJavaエージェントをインストールする方法：

  1. bin/standalone.sh ファイルを開く。

  2. 次の javaagent 引数を追加する。

    export JAVA_OPTS="$JAVA_OPTS -javaagent:/agent_install_dir/javaagent.jar"
    CODE

  3. 引数を standalone.sh の次のセクションの上に置く。

    ...
while true;do
if [ "x$LAUNCH_JBOSS_IN_BACKGROUND" = "X" ]; then
   # Execute the JVM in the foreground
      eval \"$JAVA\" -D\"[Standalone]\"$JAVA_OPTS \
     \"-Dorg.jboss.boot.log.file=$JBOSS_LOG_DIR/boot.log\" \
     \"-Dlogging.configuration=file:$JBOSS_CONFIG_DIR/logging.properties\" \
      -jar \"$JBOSS_HOME/jboss-modules.jar\" \
    CODE

  4. アプリケーションサーバーを再起動する。 

  5. standalone.conf ファイルの最後にある JAVA_OPTS セクションに次を追加する。

    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}}
<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
    CODE

    JDK9 and above, -Xbootclasspath/p オプションは削除されました。代わりに -Xbootclasspath/a を使用してください。

    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a:
<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
    CODE

  6. <path_to_jboss_logmanager> と <version> をシステムのパスおよびログマネージャ JAR ファイル名で置き換える。パスを動的にする方法については、「LogManager の場所を動的にする」を参照。

    注意

    ステップ 5 とステップ 6 は、ログマネージャのエラーが発生した場合にのみ必須です。また、この変更後にステップ 4 を繰り返します。

  1. standalone.bat ファイルで次の javaagent 引数を追加する。

    set JAVA_OPTS=%JAVA_OPTS% -javaagent:\agent_install_dir\javaagent.jar
    CODE

  2. 引数を standalone.bat の次のセクションの上に置く。

    RESTART
"%JAVA%" %JAVA_OPTS% ^
 "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\server.log" ^
 "-Dlogging.configuration=file:%JBOSS_CONFIG_DIR%/logging.properties" ^
 -jar "%JBOSS_HOME%\jboss-modules.jar" ^
 -mp "%JBOSS_MODULEPATH%" ^
 -jaxpmodule "javax.xml.jaxp-provider" ^
 org.jboss.as.standalone ^
 "-Djboss.home.dir=%JBOSS_HOME%" ^
 %SERVER_OPTS%
    CODE
  3. アプリケーションサーバーを再起動する。 

  4. standalone.conf.bat ファイルの最後にある JAVA_OPTS セクションに次を追加する。

    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}}
<path_to_jboss_logmanager>\jboss-logmanager-<version>.jar
    CODE

    JDK9 and above, -Xbootclasspath/p オプションは削除されました。代わりに -Xbootclasspath/a を使用してください。

    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a:
<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
    CODE

  5. <path_to_jboss_logmanager> と <version> をシステムのパスおよびログマネージャ JAR ファイル名で置き換える。パスを動的にする方法については、「LogManager の場所を動的にする」を参照。

    注意

    ステップ 4 とステップ 5 は、ログマネージャのエラーが発生した場合にのみ必須です。また、この変更後にステップ 3 を繰り返します。

動的な LogManager の場所

スタンドアロン JBoss インスタンスでは、パスおよびログマネージャ JAR 名をハードコーディングするのではなく、glob パターンマッチング技術を使ってログマネージャファイルへのパスを動的にすることで、システム間の変更や差異に対する回復機能を持たせることができます。 

これを実行する正確な手順は、環境によって異なります。次のセクションでは、独自の実装を開始する場合の、Windows システムと Linux システムでの構成例を示します。 

Windows

Windows の場合、standalone.conf.bat にこの付加的なスニペットが追加されます。

...
rem jboss.modules.system.pkgs
set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity,org.jboss.logmanager

rem java.util.logging 
set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.jboss.logmanager.LogManager

rem bootclasspath
set LOGMANAGER= 
for /f %%i in ('dir /b "%JBOSS_HOME%\modules\system\layers\base\org\jboss\logmanager\main\jboss-logmanager-*.jar"') do ( 
   set LOGMANAGER_JAR=%JBOSS_HOME%\modules\system\layers\base\org\jboss\logmanager\main\%%i 
) 
set JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:%LOGMANAGER_JAR%

JBossホーム下のLogManager JARファイルへのパスはJBossのバージョンにより異なる場合があります。ご使用のシステムを確認し、それに応じて例にあるようにパスを調整します。 

Linux

Linuxの場合、次のコードを使いパスを動的に追加できます。

JBOSS_MODULES_SYSTEM_PKGS ="org.jboss.byteman,com.singularity,org.jboss.logmanager"

JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:$(ls ${JBOSS_HOME}/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-*.jar)"

例にあるように ${JBOSS_HOME} 変数を使用する場合、ディレクトリへの変数をご利用のシステムの JBoss インストールディレクトリに設定します。 

JBoss ホーム下の LogManager JAR ファイルへのパスは JBoss のバージョンにより異なる場合があります。ご使用のシステムを確認し、それに応じて例にあるようにパスを調整します。 

ドメインモードエージェントのインストール

ドメインモードの場合、設定を構成する場所はご使用の環境の性質により異なります。ドメインは以下のもので構成されています。

  • ドメインコントローラ（管理および構成サーバー）。domain.xml 構成ファイルは、管理対象ホストのグローバル構成です。 
  • ホストコントローラ（1 つまたは複数のアプリケーション サーバ ノードを持つ特定のホストを管理します）。ホストコントローラとノードの数に制限はありません。hosts.xml ファイルには、そのホストマシン上にあるノードの設定が含まれます。 
    Host Machines 

したがって、構成を配置する場所は次のように異なります。

  • domain.xml：管理対象ドメイン内のすべてのホストで同一である可能性のある（つまり、ログマネージャとエージェントのファイルはすべてのマシン上の同じ場所にある）設定は、ドメインコントローラの domain.xml ファイルに移動できます。 
  • host.xml：ホストごとに特殊化する必要がある設定（たとえば、ホスト上の関連ファイルへのパスが異なる場合）は、host.xml ファイルに移動する必要があります。 

構成設定は、グローバルであるのか、ホスト固有であるのかに応じて、domain.xml と host.xml の両方に追加できます。次のセクションでは、一般的な設定をドメイン構成に追加し、ノード名の設定をホスト構成に追加する例を示します。 

Domain.xmlの構成

  1. ドメイン用に domain.xml を探し編集する。このファイルは通常$JBOSS_HOME/domain/configuration/にあります。

  2. system-properties エレメントを見つけ、既存のシステムプロパティに com.singularity の値を持つ jboss.modules.system.pkgs という名のプロパティを追加する。例：

    <system-properties>
        <!-- IPv4 is not required, but setting this helps avoid unintended use of IPv6 -->
        <property name="java.net.preferIPv4Stack" value="true"/>
        <property name="jboss.modules.system.pkgs" value="com.singularity"/>
</system-properties>
    CODE

    このプロパティは、JBossクラスローダーにAppDynamicsパッケージをロードするよう指示します。これは Javaエージェント を実行するのに必須です。

  3. エージェントを有効にするサーバーグループ名の下に、エージェントの位置、JBossアプリケーション名、ティア名に適切な値を使いJVMオプションを追加する。

    <server-group name="main-server-group" profile="full">
    <jvm name="default">
         <heap size="1303m" max-size="1303m"/>
         <permgen max-size="256m"/>
         <jvm-options>
            <option value="-javaagent:<agent_install_dir>/javaagent.jar"/> 
            <option value="-Dappdynamics.agent.applicationName=JBOSS-EAP-APP"/>
            <option value="-Dappdynamics.agent.tierName=JBOSS-EAP-TIER"/>
         </jvm-options>
    </jvm>
    <socket-binding-group ref="full-sockets"/>
 </server-group>
    CODE

domain.xml ファイルの変更を有効にするには、管理ホストを再起動する必要があります。変更をサーバーホストに反映させるには、それらも再起動する必要があります。

Host.xmlの構成

ホストごとに、host.xml ファイル（通常は $JBOSS_HOME/domain/configuration/ に配置されている）で AppDynamics ノード名を指定します。

このインスタンスのノード名を指定するには、-Dappdynamics.agent.nodeName JVM オプションを追加します。

<servers>
    <server name="server-one" group="main-server-group"> 
            <jvm name="default">
              <jvm-options>
                <option value="-agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n"/>
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-1"/>
              </jvm-options>
            </jvm>
     </server>
     <server name="server-two" group="main-server-group" auto-start="true">
            <socket-bindings port-offset="150"/>
            <jvm name="default">
              <jvm-options>
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-2"/>
              </jvm-options>
            </jvm>
      </server>
      <server name="server-three" group="other-server-group" auto-start="false">
            <socket-bindings port-offset="250"/>
      </server>
</servers>
CODE

簡潔にするために、サンプルからコメントが削除されています。 

JBossスタートアップに関する問題のトラブルシューティング

JBossにJavaエージェントをインストールする際に起こる問題のほとんどは、起動引数の競合によるものです。つまり、Javaエージェントに追加した設定が既存の引数でオーバーライドされているか、別の方法で衝突を起こしている可能性があります。このような問題は、常に簡単に検出できるとはかぎりません。

このような起動時の問題をトラブルシュートする最善の方法は、JBoss が起動を試みた時に実際に取得する起動引数を出力し検査することです。これを行うには、次のコマンドを使用して起動時に JBoss 処理情報を表示します。このコマンドは、起動の試行中（ただし失敗する前）に実行する必要があります。   

ps -ef | grep [o]rg.jbossas | tr ' ' '\n' | sed -e '/^$/d'

JBossのシャットダウンに関する問題のトラブルシューティング

JBoss 5.1.2 サーバ構成で JVM の JMXremote 機能を有効にすると、/bin/shutdown.sh の呼び出し時に次のエラーが生成されます。

javax.management.JMRuntimeException: Failed to load MBeanServerBuilder class org.jboss.system.server.jmx.MBeanServerBuilderImpl: 
java.lang.ClassNotFoundException: org.jboss.system.server.jmx.MBeanServerBuilderImpl

解決

環境内に JAVA_OPTS パラメータがあるため、JVM の起動時に Java プロセスが影響を受けることがあります。
JAVA_OPTS パラメータが EAP 内部で使用されるという理由から、環境内には配置しないようにしてください。

環境内のパラメータをクリアするには、コンソールから次のように実行します。

  1. export JAVA_OPTS=""

  2. env|grep JAVA_OPTS
    JAVA_OPTS= <このメッセージが表示されます>

  3. shutdown.sh -s jnp://localhost:1099 -u USER -p PASSWORD

根本原因

JMX 関連のオプションは、shutdown.sh の呼び出し時に JAVA_OPTS に設定しないようにしてください。JAVA_OPTS は JBoss EAP の起動時にのみ設定され、実行時には設定されません。