How to configure the APM JBoss Agent with JBoss EAP 6.x in Domain mode.

Document ID : KB000011380
Last Modified Date : 14/02/2018
Show Technical Document Details

  Can you provide the instructions on how to configure the APM JBoss Agent 9.6.x, 9.7.x and 10.x with JBoss EAP 6.x in Domain mode?

All supported APM releases.

Case scenario : JBoss domain setup with 1 server group (clu01) with 2 JBoss instances (srv01,srv02),

AGENT_HOME= /quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily


If the JBoss setup involves a domain server with slave servers, copy the Java agent package to the domain server only, the domain server will populate the agent configuration to the slave servers.


Step 1:

Copy AGENT_HOME/common/WebAppSupport.jar to AGENT_HOME/core/ext

This file is needed by the following agent features:

a) Auto naming of the agent: when automatic agent naming is enabled, the agent starts and looks for name information from the application server. The agent waits until an agent name is obtained before attempting to connect to the Enterprise Manager. In the agent profile, make sure to set introscope.agent.agentAutoNamingEnabled=true.

b) JMX metrics gathering. In the agent profile, set introscope.agent.jmx.enable=true

Step 2:
 Start JBoss in domain mode by running JBOSS_HOME/bin/

Below is the output:



Step 3: Create a Management user using JBOSS_HOME/bin/

Before that, you need to edit the script and define the JAVA_HOME environment variable. 

# Add User Utility
# A simple utility for adding new users to the properties file used
# for domain management authentication out of the box.
DIRNAME=`dirname "$0"`

Step 4: Go to the JBoss Admin console: http://localhost:9990

When prompted for credentials, enter the user that you created above



Step 5:
 Configure the Agent.jar

Click Host > Server Groups

Select the server group you want to instrument.

Click JVM Configuration.



Click Edit button, set  JVM options=-javaagent:/quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily/Agent.jar

Click Save


Step 6: Configure the Agent profile and additional system property:

Click “System Properties” tab and add the below 2 properties:

-          jboss.modules.system.pkgs=com.wily,com.wily.*

-          com.wily.introscope.agentProfile=/quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily/core/config/IntroscopeAgent.profile


Step 7: If you would like you need to use the autonaming.  If you would like to explicitly assign a name to the agents, follow the below steps:

Click Server Configurations

Select srv01

Click System Properties



Click Add button

Create new property com.wily.introscope.agent.agentName=clu01-srv01


Select srv02

Click System Properties

Click Add button

Create new property com.wily.introscope.agent.agentName=clu01-srv02


Step 8:
 To enable autonaming, register the WebAppSupport.jar

Click Runtime > Manage Deployments > Content Repository


Click “Add” > Browse > select “WebAppSupport.jar”

Click “Open”, then “Next” button


Click “Save”




Select the WebAppSupport.jar

Click “Assign” button


Select the Server Group, click “Save”

Step 9: Restart the appserver – the output will be the same as the initial without the agent.


Step 10: Verify the Agent configuration in Jboss config files:

Go to JBOSS_HOME/domain/configuration

Open domain.xml


<option value="-javaagent:/quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily/Agent.jar"/>
   <property name="jboss.modules.system.pkgs" value="com.wily,com.wily.*" boot-time="true"/>
   <property name="com.wily.introscope.agentProfile" value="/quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily/core/config/IntroscopeAgent.profile" boot-time="true"/>

Open Host.xml


Step 11: Go to the admin console to start the srv01 and srv02 instances.

By default,  Overview > Topology should be the first page.

Move your mouse over srv01, a “Start Server” link will show up. Click the link to start the server instance.

Do the same for server instance#2.


As soon as you start the server instances, you should now be able to confirm that the agent is instrumenting the application by looking at the console:


Step 12: Verify the result in the Investigator.


Additional Information:

How the Agent Determines its Name?

Method 1 - Agent Name Specified in a Java System Property: -Dcom.wily.introscope.agent.agentName=
Method 2 - Agent Name Specified in a System Property Key in the IntroscopeAgent.profile: introscope.agent.agentNameSystemPropertyKey
Method 3 - Agent Name Obtained Automatically from the Application Server. Only supported by Weblogic, Websphere and Jboss. You need to deploy WebAppSupport.jar
Method 4 - Agent Name Specified Explicitly in the Agent Profile: introscope.agent.agentName
Method 5 - Agent Name Determined to be "Unknown agent"

For more information, refer to the documentation > Java Agent Naming section