AppDynamics Application Intelligence Platform

3.9.x Documentation


Learn by Watching

Doc Maps

Skip to end of metadata
Go to start of metadata

Instrumenting JBoss applications with the AppDynamics agent requires adding up to three items of information as Java options to the JBoss startup configuration:

  • Location of the Java Agent
  • AppDynamics package names
  • JBoss log manager package name and JAR location

For most deployments (that is, those using a recent version of JBoss and the AppDynamics Java Agent) all three items are required. The following section takes you through the steps for configuring these items. 

Quick Install

If using a recent version of JBoss (AS 7.x or EAP 6.x or later) and running in standalone mode, you can instrument JBoss with the AppDynamics Java agent by adding the three startup options to the startup script for your JBoss instance, typically For older versions of JBoss or if running in domain mode, be sure to verify the settings you need by reading the Startup Argument Configuration Considerations section.

To instrument JBoss with the Java Agent: 

  1. Add the -javaagent argument and set its value to the full path to the Java agent on your system. (See callout  in the figure below.)
  2. Add the AppDynamics package names,, and com.singularity. to the existing -Djboss.modules.system.pkgs property (callout ).
  3. Add the argument -Djava.util.logging.manager with the LogManager package name and add -Xbootclasspath argument, replacing its value with the path to the JBoss log manager JAR file for your instance (callout ).
  4. Restart the JVM. 

    The following figure shows a sample JBoss startup script ( with the three options:  


For the installation instructions in greater detail, see Adding the Java Agent to JBoss in Standalone Mode or Adding the Java Agent to JBoss in Domain Mode.

Startup Argument Configuration Considerations 

The following table describes when you need to configure each Java option. 

CalloutOptionWhen needed?
Location of the Java AgentAlways
AppDynamics packages as system packages 

If using an OSGi-compliant version of JBoss, including: 

  • AS 7.x+
  • EAP 6.x+

Log manager settings, which include:

  • Location of the log manager JAR file (as a -Xbootclasspath argument) 
  • Package name for the log manager (org.jboss.logmanager.LogManager) added as a system package

If using:

  • AppDynamics Agent version 3.9 or later
  • An IBM JVM
  • A Sun JVM with Remote JMX (note that this requirement is not related to the AppDynamics Java Agent)

The Quick Install section describes how to configure the settings in the standalone startup script. But the exact file where you configure the settings depends on the operating mode of JBoss, its version, and even practices that are specific for your organization and environment.  

The following sections describes some of the considerations for where to configure the settings.  

Standalone mode 

For standalone: 

  • In Linux, add the settings to standalone.conf or
  • In Windows, add the settings to standalone.conf.bat.

If using JBoss 4.x or 5.x, add the configuration to for Linux or run.bat for Windows. 

For an example of this configuration, see Adding the Java Agent to JBoss in Standalone Mode

Domain mode

For domain mode, the location in which you need to configure the settings depends upon the nature of your environment. 

Keep in mind that a domain is made up of:

  • A domain controller, which is the administration and configuration server for the JBoss environment. The domain.xml configuration file is the global configuration for the managed hosts. 
  • Host controllers, which manage a particular host with 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. 

If the values of the settings you need to configure are the same for all hosts in the managed domain, you can put them in the domain.xml file for the Domain Controller. On the other hand, if the setting values vary among the hosts (for example, if the path to the log manager file varies between hosts), they should go into the settings in the host.xml file. 

Changes to the domain.xml require a restart of the management host. They are not propagated to the server hosts until they are restarted as well. 

The configuration settings can be split between domain.xml and host.xml, if you want to specify some settings globally and others by host.

For an example of this configuration, see Adding the Java Agent to JBoss in Domain Mode.

Adding the Java Agent to JBoss in Standalone Mode

The following procedures walk you through the steps for adding the agent to JBoss AS 7.x on Linux. These steps should work for OSGi-compliant versions of JBoss. However, note that your own environment may have specific considerations not covered here, for example, if you have existing, site-specific customizations to the JBoss startup configuration files.    

  1. Open the bin/standalone.conf file.
  2. Search for the following line in standalone.conf.

  3. Add the com.singularity and org.jboss.logmanager packages to that line as follows:

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

    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.   

  5. In the file, add the following javaagent argument.

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

    Put the argument above the following section of

    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/\" \
          -jar \"$JBOSS_HOME/jboss-modules.jar\" \
  6. Restart the application server. 

Adding the Java Agent to JBoss in Domain Mode

The following steps walk you through the configuration for a JBoss installation running in domain mode.

For this type of deployment:

  • If all the server instances in the server group are part of the same business application, then configure -Dappdynamics.agent.applicationName in domain.xml; otherwise, configure the application name in the host.xml file for each specific server. 

    The -Dappdynamics.agent.applicationName argument specifies the name of the Business Application to use for the data reported by this Java Agent to the AppDynamics Controller.
  • If all the server instances in the server group are part of the same tier then configure -Dappdynamics.agent.tierName in domain.xml, otherwise configure the tier name in host.xml for each specific server.

    The -Dappdynamics.agent.tierName argument specifies the name of the tier to use for the data reported by this Java Agent to the AppDynamics Controller. 

Edit the JBoss domain.xml and host.xml files as indicated in the following sections and then restart the application server.

Modify the Domain.xml file

  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:

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

    This property tells the JBoss class loader to load the AppDynamics packages. This is required for the Java Agentto run.

  3. Under the server group name where you want to enable your Java 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"/>
            <option value="-javaagent:<agent_install_dir>/javaagent.jar"/> 
            <option value="-Dappdynamics.agent.applicationName=JBOSS-EAP-APP"/>
            <option value="-Dappdynamics.agent.tierName=JBOSS-EAP-TIER"/>
    <socket-binding-group ref="full-sockets"/>

Modify the Host.xml file

Add the -Dappdynamics.agent.nodeName JVM option in host.xml file (usually located under $JBOSS_HOME/domain/configuration/). This option tells the Java Agent the node name to use to connect to the AppDynamics Controller. Use the appropriate values for your node names.

For example:

    <server name="server-one" group="main-server-group">
            <!-- Remote JPDA debugging for a specific server
            <option value="-agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n"/>
            <jvm name="default">
                <option value="-agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n"/>
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-1"/>
     <server name="server-two" group="main-server-group" auto-start="true">
            <!-- server-two avoids port conflicts by incrementing the ports in
                 the default socket-group declared in the server-group -->
            <socket-bindings port-offset="150"/>
            <jvm name="default">
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-2"/>
      <server name="server-three" group="other-server-group" auto-start="false">
            <!-- server-three avoids port conflicts by incrementing the ports in
                 the default socket-group declared in the server-group -->
            <socket-bindings port-offset="250"/>

Making the LogManager Location Dynamic

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 that you specify in the startup options more resilient to changes.   


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


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 following sections contain information that may assist you in getting the Java Agent installed on JBoss. 

Verify JBoss startup arguments

Most issues with installing the Java Agent on JBoss are attributable to conflicts between startup arguments. Settings you add for the Java Agent may be overridden or otherwise conflict with existing arguments in ways that 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. Note that this command needs to be performed while the start up attempt is occurring, and before it fails.   

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

Fix Linkage Error

If you see this error:

Caused by: java.lang.LinkageError: loader constraint violation in interface itable initialization: when resolving method ";" the class loader (instance of org/jboss/modules/ModuleClassLoader) of the current class, com/microsoft/sqlserver/jdbc/SQLServerXAConnection, and the class loader (instance of <bootloader>) for interface javax/sql/XAConnection have different Class objects for the type javax/transaction/xa/XAResource used in the signature

Add the following JVM option to the startup script and restart the server:


The error indicates a race condition while loading classes. The flag controls the class loading hierarchy, thus preventing class loading problems.

JMXRegistrationAdvice callback error for target context ServiceBindingManager

The following error at JBoss start up has been encountered in JBoss 6.x: 

14:06:58,531 ERROR [AbstractKernelController] Error installing to   
Configured: name=ServiceBindingManager state=Configured:   
java.lang.Exception: Error calling callback JMXRegistrationAdvice for   
target context ServiceBindingManager  

If you encounter this error, edit the JBoss startup script run.conf (Linux) or run.conf.bat (Windows) and add the following properties as Java options (JAVA_OPTS):