4.3.x Documentation

PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.


Skip to end of metadata
Go to start of metadata

On this page:

This topic describes how to install the AppDynamics Java Agent on Red Hat JBoss Enterprise Application Server and JBoss Wildfly. 

Before You Install

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

The location you configure this varies depending on your version of the framework:

  • 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 the following parameter:

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

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

Standalone Agent Installation

The following instructions assume the use of Red Hat JBoss (Application Server 7.x or Enterprise Application Server 6.x or later).

To install the Java Agent on JBoss Standalone:

  1. Open the bin/standalone.conf file.

  2. In the standalone.sh file, add the following javaagent argument.

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

  3. Put the argument above the following section of 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\" \

  4. Restart the application server. 

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

    -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<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.

    Note

    Step 5 and Step 6 are required only if the log manger errors manifest. Also, repeat step 4 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. The following 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:

...
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: 

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. 
     

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

    <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 AppDynamics packages. This is required for the Java Agent to run.

  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.

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

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

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

 

 


Have a question about the topic on this page? Ask the AppDynamics Community.