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

  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?

Environment:
All supported APM releases.
Answer:

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

JBOSS_HOME=/jboss-eap-6.1

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/domain.sh

Below is the output:

step2.png

 

Step 3: Create a Management user using JBOSS_HOME/bin/add-user.sh.

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"`
JAVA_HOME=/jdk1.6.0_45
…..

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

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

step4.png

 


Step 5:
 Configure the Agent.jar

Click Host > Server Groups

Select the server group you want to instrument.

Click JVM Configuration.

step5a.png

 

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

Click Save

step5b.png

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

step6.png



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

 

step7a.png

Click Add button

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

step7b.png

Select srv02

Click System Properties

Click Add button

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

step7c.png


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

Click Runtime > Manage Deployments > Content Repository

step8a.png

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

Click “Open”, then “Next” button

step8b.png

Click “Save”

step8c.png

 

step8d.png

Select the WebAppSupport.jar

Click “Assign” button

step8e.png

Select the Server Group, click “Save”

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

step9.png

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

Go to JBOSS_HOME/domain/configuration

Open domain.xml

step10a.png


<option value="-javaagent:/quick_startup_scripts/jboss-eap-6.1/NoInstaller9.1.7.0jboss/wily/Agent.jar"/>
..
<system-properties>
   <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"/>
</system-properties>

Open Host.xml

step10b.png

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.

step11a.png

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:

step11b.png

Step 12: Verify the result in the Investigator.

 step12.png

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