JBossとWildflyのスタートアップ設定

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

Before You Install

To install the agent on JBoss or Wildfly, you add the Java Agent and log manager packages to the server startup routine.

The configured location varies based on your framework version:

  • In Linux, add the settings to standalone.conf or standalone.sh.
  • In Windows, add the settings to standalone.conf.bat .
  • If using JBoss 4.x or 5.x, add the configuration to run.sh for Linux or run.bat for Windows.

Initialize the JVM

To install the Java Agent on JBoss EAP or JBoss Wildfly, you need to initialize the JVM. Run this parameter:

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

If you do not initialize the JVM, the installation generates a "class not found" exception.

Ensure that the property jboss.modules.system.pkgs is available in the environment. If the property is present, then add com.singularity to it.

For example:

CODE 
-Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity

If the property is not present, then configure a new one:

CODE 
-Djboss.modules.system.pkgs=com.singularity

Standalone Mode Agent Installation

These instructions assume the use of Red Hat JBoss. For supported versions, see Application Servers.

To install the Java Agent on JBoss Standalone:
Linux

  1. Open the bin/standalone.sh file.

  2. Add the following javaagent argument:

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

  3. Specify the argument above the following section of standalone.sh:

    CODE 
    ... 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\" \

  4. Restart the application server.

  5. Add the following to the end of the standalone.conf file in the JAVA_OPTS section.

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

    JDK9 and above, -Xbootclasspath/p option has been removed; use -Xbootclasspath/a instead.

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

  6. Replace <path_to_jboss_logmanager> and <version> with the path and log manager JAR filename for your system. See Making the LogManager Location Dynamic for information on making the path dynamic.

    注: Step 5 and Step 6 are required only if the log manager errors manifest. Also, repeat Step 4 after this change.
Windows

  1. In the standalone.bat file, add the following javaagent argument.

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

  2. Specify the argument above the following section in standalone.bat:

    CODE 
    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%

  3. Restart the application server.

  4. Add the following to the end of the standalone.conf.bat file in the JAVA_OPTS section.

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

    JDK9 and above, -Xbootclasspath/p option has been removed; use -Xbootclasspath/a instead.

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

  5. Replace <path_to_jboss_logmanager> and <version> with the path and log manager JAR filename for your system. See Making the LogManager Location Dynamic for information on making the path dynamic.

    注: Step 4 and Step 5 are required only if the log manager errors manifest. Also, repeat Step 3 after this change.

Dynamic LogManager Location

On standalone JBoss instances, instead of hard coding the path and name of the log manager JAR, you can use glob pattern matching techniques to make the path to the log manager file dynamic, so that it is resilient to change or variances among systems.

The exact steps to accomplish this varies by environment. These sections provide an example of this configuration on Windows and Linux systems, and are meant as a starting point for your own implementation.

Windows

In Windows, the standalone.conf.bat gets this additional snippet:

CODE 
...
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%

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Linux

In Linux, you can populate the path dynamically with the following code:

JSON 
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)"

If using the ${JBOSS_HOME} variable, as in the example, be sure to set the variable to the directory to the JBoss installation directory on your system.

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Standalone Mode Agent Installation

These instructions assume the use of Red Hat JBoss. For supported versions, see Java対応環境.

To install the Java Agent on JBoss Standalone (Linux)

To install the Java Agent on JBoss Standalone:
  1. Open the bin/standalone.sh file.
  2. Add the following javaagent argument:
    CODE 
    export JAVA_OPTS="$JAVA_OPTS -javaagent:/agent_install_dir/javaagent.jar"
  3. Specify the argument above the following section of standalone.sh:
    CODE 
    ...
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\" \
  4. Restart the application server.
  5. Add the following to the end of the standalone.conf file in the JAVA_OPTS section:
    JSON 
    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}}
<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
    For JDK9 and above, -Xbootclasspath/p option has been removed; use -Xbootclasspath/a instead:
    CODE 
    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a:<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
  6. Replace <path_to_jboss_logmanager> and <version> with the path and log manager JAR filename for your system.
    See Making the LogManager Location Dynamic for information on making the path dynamic.
    注: Step 5 and Step 6 are required only if the log manager errors manifest. Also, repeat Step 4 after this change.

To install the Java Agent on JBoss Standalone (Windows)

To install the Java Agent on JBoss Standalone:
  1. In the standalone.bat file, add the following javaagent argument.
    CODE 
    set JAVA_OPTS=%JAVA_OPTS% -javaagent:\agent_install_dir\javaagent.jar
  2. Specify the argument above the following section of standalone.sh:
    CODE 
    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%
  3. Restart the application server.
  4. Add the following to the end of the standalone.conf file in the JAVA_OPTS section:
    JSON 
    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}}
<path_to_jboss_logmanager>\jboss-logmanager-<version>.jar
    For JDK9 and above, -Xbootclasspath/p option has been removed; use -Xbootclasspath/a instead:
    CODE 
    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a:
<path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
  5. Replace <path_to_jboss_logmanager> and <version> with the path and log manager JAR filename for your system.
    See Making the LogManager Location Dynamic for information on making the path dynamic.
    注: Step 4 and Step 5 are required only if the log manager errors manifest. Also, repeat Step 3 after this change.
Dynamic LogManager Location

On standalone JBoss instances, instead of hard coding the path and name of the log manager JAR, you can use glob pattern matching techniques to make the path to the log manager file dynamic, so that it is resilient to change or variances among systems.

The exact steps to accomplish this varies by environment. These sections provide an example of this configuration on Windows and Linux systems, and are meant as a starting point for your own implementation.

Windows

In Windows, the standalone.conf.bat gets this additional snippet:

CODE 
...
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%

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Linux

In Linux, you can populate the path dynamically with the following code:

JSON 
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)"

If using the ${JBOSS_HOME} variable, as in the example, be sure to set the variable to the directory to the JBoss installation directory on your system.

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Domain Mode Agent Installation

For domain mode, the location in which you need to configure the settings depends upon specifics for your environment. Keep in mind that a domain is made up of these components:
  • A domain controller, the administration and configuration server. The domain.xml configuration file is the global configuration for the managed hosts.
  • Host controllers, which manage a particular host containing one or more application server nodes. There can be any number of host controllers and nodes. The hosts.xml file contains settings for the nodes on that host machine.Host Machines

Where you put the configuration, therefore, varies as follows:

  • domain.xml : Settings that can be identical for all hosts in the managed domain (i.e., the log manager and agent files are at the same location on all machines) can go into the domain.xml file for the Domain Controller.
  • host.xml : Settings that need to be specialized for individual hosts (for example, if the paths to relevant files on hosts vary) need to go into the host.xml file.

You can add configuration settings to both domain.xml and host.xml, depending on which are global and which are host-specific. The following sections show an example of adding general settings to the domain configuration and node name setting to the host configuration.

Domain.xml Configuration:
  1. Locate and edit domain.xml for the domain.
    This is usually located under $JBOSS_HOME/domain/configuration/.
  2. Find the system-properties element and add a property named jboss.modules.system.pkgs with a value of com.singularity to the existing system properties.
    For example:
    CODE 
    <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>
    This property tells the JBoss class loader to load the Splunk AppDynamics packages. This is required for the Java Agent to run.

    Ensure that the property jboss.modules.system.pkgs is available in the environment. If the property is present, then add com.singularity to it.

    For example:
    CODE 
    -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity
    If the property is not present, then configure a new one:
    CODE 
    -Djboss.modules.system.pkgs=com.singularity
  3. Under the server group name where you want to enable your agents, add the JVM options using the appropriate values for your agent location, JBoss application name, and tier name.
    CODE 
    <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>
    Changes to the domain.xml file require a restart of the management host to take effect. The changes are not propagated to server hosts until they are restarted as well.
Host.xml Configuration

For each host, specify the Splunk AppDynamics node name in the host.xml file, usually located under $JBOSS_HOME/domain/configuration/.

Add the -Dappdynamics.agent.nodeName JVM option to specify the node name for this instance:

CODE 
<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>

For brevity, comments have been removed from the sample.

Troubleshooting JBoss Startup Issues

Most issues installing the Java Agent on JBoss result from conflicts between startup arguments. That is, settings you add for the Java Agent may be overridden or conflict in other ways with existing arguments. Such issues are not always easy to detect.

The best way to begin troubleshoot such startup issues is to print and inspect the startup arguments that JBoss actually gets when attempting to start. To do this, view JBoss process information during startup using the following command. You need to issue this command while the start up attempt is occurring but before it fails.

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

Troubleshooting JBoss Shutdown Issues

When enabling the JMXremote features of the JVM on a JBoss 5.1.2 server configuration, the following error is generated when calling the /bin/shutdown.sh:

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

Resolution

Sometimes, there is JAVA_OPTS parameter in the environment, and it affects to a java process when the JVM start. From the reason that EAP uses JAVA_OPTS parameter internally, it should not be in the environment.

To clear the parameter in the environment, executing the following from a console:

  1. export JAVA_OPTS=""
  2. env|grep JAVA_OPTS

    JAVA_OPTS= <You will see this message>

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

Root Cause

JMX related options should not be set in JAVA_OPTS when calling shutdown.sh. Ensure JAVA_OPTS is only set when starting JBoss EAP, not when running.