Installing eG Java BTM on WildFly JBoss

The steps for deploying the eG Java BTM on a WildFly JBoss server will differ based on the following:

• The platform on which the target WildFly JBoss server is running - whether on a Windows platform or a Unix platform ;
• The operational mode of the monitored WildFly JBoss server - whether stand-alone or Domain mode;
• How the WildFly JBoss server is monitored - in an agent-based or agentless manner.

BTM-Enabling a WildFly JBoss Server Monitored in an Agent-based Manner

If the WildFly JBoss server is running on a Windows operating system and is operating in the Stand-alone mode, then follow the steps below to BTM-enable that server:

1. Login to the WildFly JBoss server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the WildFly JBoss server as a separate component using the eG administrative interface. When managing, make sure the Agentless flag is unchecked to indicate that the server is being monitored in an agent-based manner.

4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface. Figure 1 will then appear, listing the Java application servers managed in the environment. Locate the WildFly JBoss server that you managed recently in that list, and click the Copy JVM icon () corresponding to it (see Figure 1).

   

   Figure 1 : Identifying the Wildfly JBoss server running on a Windows system and operating in a Stand-alone mode, which is to be BTM-enabled

5. Figure 2 will then appear. Copy the JVM option displayed in Figure 2 to the clip board or any text editor.

   

   Figure 2 : Copying the JVM option for BTM-enabling a WildFly JBoss server running on a Windows system and operating in the stand-alone mode

6. Next, edit the standalone.conf.bat file on the JBoss/WildFly server being monitored.

   

   Figure 3 : Editing the standalone.conf.bat file of the target WildFly JBoss server running in the stand-alone mode on a Windows system

7. Append the code block you copied at step 6 above to the JAVA_OPTS specification that pre-exists in the standalone.conf.bat file, as indicated by Figure 3 above. When doing so, make sure you replace the <<EGURKHA_AGENT_HOME>> tag in the entry with the actual install directory of the eG agent deployed on the WildFly JBoss server.

8. Also, add com.eg as one of the system packages as shown below (see Figure 3).

   set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs="org.jboss.byteman,com.eg"

9. Finally, save the file.
10. Restart the server.

If the WildFly JBoss server is running on a Linux operating system and is operating in the Stand-alone mode, then follow the steps below to BTM-enable that server:

1. Login to the WildFly JBoss server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the WildFly JBoss server as a separate component using the eG administrative interface. When managing, make sure the Agentless flag is unchecked to indicate that the server is being monitored in an agent-based manner.

4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface. Figure 4 will then appear, listing the Java application servers managed in the environment. Locate the WildFly JBoss server that you managed recently in that list, and click the Copy JVM icon () corresponding to it (see Figure 4).

   

   Figure 4 : Identifying the WildFly JBoss server running on a Linux system and operating in a Stand-alone mode, which is to be BTM-enabled

5. Figure 2 will then appear. Copy the JVM option displayed in Figure 2 to the clip board or any text editor.

   

   Figure 5 : Copying the JVM option for BTM-enabling a WildFly JBoss server running on a Linux system and operating in the stand-alone mode

6. Next, edit the standalone.conf file on the WildFly JBoss server being monitored.

   

   Figure 6 : Editing the standalone.conf file of the target WildFly JBoss server running in the stand-alone mode on a Linux system

7. Append the code block you copied at step 6 above to the JAVA_OPTS specification that pre-exists in the standalone.conf file, as indicated by Figure 3 above. When doing so, make sure you replace the <<EGURKHA_AGENT_HOME>> tag in the entry with the actual install directory of the eG agent deployed on the JBoss server.

8. Also, add com.eg as one of the system packages. For this, append ",com.eg" to the values that pre-xist against the JBOSS_MODULES_SYSTEM_PKGS, as depicted by Figure 3.

9. Finally, save the file.

10. Restart the server.

If the WildFly JBoss server is running on a Windows system and is operating in the Domain mode, then follow the steps below to BTM-enable that server:

1. Login to the WildFly JBoss server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the WildFly JBoss server as a separate component using the eG administrative interface. When managing, make sure the Agentless flag is unchecked to indicate that the server is being monitored in an agent-based manner.

4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface. Figure 7 will then appear, listing the Java application servers managed in the environment. Locate the WildFly JBoss server that you managed recently in that list, and click the Copy JVM icon () corresponding to it (see Figure 7).

   

   Figure 7 : Identifying the WildFly JBoss server running on a Windows system and operating in the Domain mode, which is to be BTM-enabled

5. Figure 2 will then appear. Copy the JVM option displayed in Figure 2 to the clip board or any text editor.

   

   Figure 8 : Copying the JVM option for BTM-enabling a WildFly JBoss server running on a Windows system and operating in the domain mode

6. Next, edit the host.xml file on the JBoss/WildFly server being monitored.

   

   Figure 9 : Editing the host.xml file of the target WildFly JBoss server running in the domain mode on a Windows system

7. Append the code block you copied at step 6 above to the <jvm-options> specification that pre-exists in the host.xml file, as indicated by Figure 3 above. When doing so, make sure you replace the <<EGURKHA_AGENT_HOME>> tag in the entry with the actual install directory of the eG agent deployed on the JBoss server.
8. Then, save the file.

9. Next, edit the domain.xml file to add com.eg as one of the system packages (see Figure 10).

   

   Figure 10 : Editing the domain.xml file of the WildFly JBoss server on Windows running in the Domain mode

10. Finally, save the file, and restart the server.

If the WildFly JBoss server is running on a Linux operating system and is operating in the Domain mode, then follow the steps below to BTM-enable that server:

1. Login to the WildFly JBoss server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the WildFly JBoss server as a separate component using the eG administrative interface. When managing, make sure the Agentless flag is unchecked to indicate that the server is being monitored in an agent-based manner.

4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface. Figure 11 will then appear, listing the Java application servers managed in the environment. Locate the WildFly JBoss server that you managed recently in that list, and click the Copy JVM icon () corresponding to it (see Figure 11).

   

   Figure 11 : Identifying the WildFly JBoss server running on a Linux system and operating in the Domain mode, which is to be BTM-enabled

5. Figure 2 will then appear. Copy the JVM option displayed in Figure 2 to the clip board or any text editor.

   

   Figure 12 : Copying the JVM option for BTM-enabling a WildFly JBoss server running on a Linux system and operating in the Domain mode

6. Next, edit the host.xml file on the JBoss/WildFly server being monitored.

   

   Figure 13 : Editing the host.xml file of the target WildFly JBoss server running in the Domain mode on a Linux system

7. Append the code block you copied at step 6 above to the <jvm-options> specification that pre-exists in the host.xml file, as indicated by Figure 3 above. When doing so, make sure you replace the <<EGURKHA_AGENT_HOME>> tag in the entry with the actual install directory of the eG agent deployed on the JBoss server.

8. Then, save the file.

9. Next, edit the domain.xml file to add com.eg as one of the system packages (see Figure 14).

   

   Figure 14 : Editing the domain.xml file of the WildFly JBoss server on Linux running in the Domain mode

10. Finally, save the file, and restart the server.

BTM-Enabling a WildFly JBoss Server Monitored in an Agentless Manner

If the WildFly JBoss server is running on a Windows operating system, then follow the steps below to BTM-enable that server:

1. Login to the WildFly JBoss server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the WildFly JBoss server as a separate component using the eG administrative interface. When managing, make a note of the Nick name and Port number that you provide.
4. If multiple WildFly JBoss server instances are operating on a single host, and you want to BTM-enable all the instances, then you will have to manage each instance as a separate component using the eG administrative interface. When doing so, make a note of the Nick name and Port number using which you managed each instance.
5. Next, log out of the eG admin interface. Then, create a btm directory anywhere on the WildFly JBoss server - say, C:\btm. Under this directory, create a sub-folder. Make sure that you name this sub-folder in the following format: <Managed_Component_NickName>_<Managed_Component_Port>. For instance, if you have managed the WildFly JBoss server using the nick name JBoss1 and the port number 9990, the new directory under the btm directory should be named as JBoss1_9990.

6. If you have managed multiple WildFly JBoss server instances running on a single host, then you will have to create multiple sub-directories under the btm directory - one each for every instance. Each of these sub-directories should be named after the Nick name and Port number using which the corresponding instance has been managed in eG.

7. Once the new sub-directory(ies) is created, open a browser on the WildFly JBoss server, connect to the eG manager, and login to the eG admin interface again.
8. Follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface.

9. Figure 15 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WildFly JBoss server that you want to BTM-enable. Once you locate the server, click the Download icon corresponding to that server to download the APM Profiler Agent to that server. If multiple WildFly JBoss server instances on a single host are managed, then you will have to download the APM Profiler Agent separately for each of the managed instances.

   

   Figure 15 : Downloading the APM Profiler Agent for the WildFly JBoss server

10. Upon clicking the Download icon in Figure 15, a zip file named javaagent_<Nick_name_of_JBossWildFly_server>_<Port_number_of_JBossWildFly_server will get downloaded. For instance, if you have managed the WildFly JBoss server using the nickname 'JBoss1' and the port number '9990', then the name of the zip file will be javaagent_JBoss1_9990. Where multiple WildFly JBoss server instances have been managed, you will be downloading multiple zip files - one each for every instance. The names of these zip files will automatically carry the nick name and port number you assigned to the corresponding server instance.
11. Copy the downloaded zip file(s) to the corresponding sub-directory(ies) of the btm directory (see steps 5 and 6 above).  For example, the zip file named javaagent_JBoss1_9990, should be copied to the C:\btm\JBoss1_9990 directory .
12. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.

13. Figure 16 depicts the extracted contents of the zip file.

    

    Figure 16 : Contents of the APM Profiler Agent zip

14. From Figure 16, it is evident that the zip file contains an eg_btm.jar file and a few property files, namely - btmOther.props, btmLogging.props, config.props, custom.props, exclude.props, and threshold.props files.

15. Then, you need to configure the WildFly JBoss server with the path to the eg_btm.jar file. To achieve this, you need to edit the start-up script of the WildFly JBoss server. The first step towards that is to open the start-up script.

16. Then, in the file, enter the following lines, as depicted by Figure 17.

    -javaagent:<<PATH TO THE eg_btm.jar FILE>>

    For instance, if the eg_btm.jar file file is extracted into the C:\btm\JBoss1_9990 directory, the above specification will be:

    -javaagent:C:\btm\JBoss1_9990\eg_btm.jar

    

    Figure 17 : Editing the start-up script to BTM-enable a WildFly JBoss server running on Windows

17. Where multiple instances of WildFly JBoss are monitored, make sure you perform steps 15-18 above for each WildFly JBoss server instance.

18. Next, if the WildFly JBoss server is running in domain mode, open the domain.conf file in JBoss_Home\bin directory. If the server is running in standalone mode, open the standalone.conf file in the JBoss_Home\bin directory.

    

    Figure 18 : Editing the domain.conf file or standalone.conf file

19. Append ",com.eg" to the following line in the file, as depicted by Figure 18:

    set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs="org.jboss.byteman"

     

20. Finally, save the file. and restart the WildFly JBoss server.

If the target WildFly JBoss server is running on a Unix operating system, then follow the steps below to BTM-enable that server:

1. Login to any system in your environment that supports a browser and has network access to the eG manager.
2. Open a browser on that system, connect to the eG manager, and login to the eG admin interface.
3. Manage the target WildFly JBoss server as a separate component using the eG administrative interface. When managing, make a note of the Nick name and Port number that you provide.

4. If multiple WildFly JBoss server instances are operating on a single host, and you want to monitor each of those instances, then you will have to manage each instance as a separate WildFly JBoss server component using the eG administrative interface. When doing so, make a note of the Nick name and Port number using which you managed each instance.

5. Next, log out of the eG admin interface and the system.
6. Log into the target WildFly JBoss server. Then, create a btm directory anywhere on the target server - say, /opt/btm. Under this directory, create a sub-folder. Make sure that you name this sub-folder in the following format: <Managed_Component_NickName>_<Managed_Component_Port>. For instance, if you have managed the WildFly JBoss server using the nick name JBoss1 and the port number 9990, the new directory under the btm directory should be named as JBoss1_9990.

7. If you have managed multiple JBoss server instances running on a single host, then you will have to create multiple sub-directories under the btm directory - one each for every instance. Each of these sub-directories should be named after the Nick name and Port number using which the corresponding instance has been managed in eG.

8. Once the new sub-directory(ies) is created, log out of the WildFly JBoss server. Log back into the system you used in step 1 above. Open a browser on the system, connect to the eG manager, and login to the eG admin interface again.
9. Follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface.

10. Figure 15 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WildFly JBoss server that you want to BTM-enable. Once you locate the server, click the Download icon corresponding to that server to download the APM Profiler Agent to that server. If multiple WildFly JBoss server instances on a single host are managed, then you will have to download the APM Profiler Agent separately for each of the managed instances.

11. Upon clicking the Download icon in Figure 15, a zip file named javaagent_<Nick_name_of_JBossWildFly_server>_<Port_number_of_JBossWildFly_server will get downloaded. For instance, if you have managed the WildFly JBoss server using the nickname 'JBoss1' and the port number '9990', then the name of the zip file will be javaagent_JBoss1_9990. Where multiple WildFly JBoss server instances have been managed, you will be downloading multiple zip files - one each for every instance. The names of these zip files will automatically carry the nick name and port number you assigned to the corresponding WildFly JBoss server instance.
12. Next, using FTP tools like putty or WinSCP, transfer the downloaded zip file(s) to the corresponding sub-directory(ies) (of the btm directory), which you created on the WildFly JBoss server in steps 6 and 7 above.  For example, the zip file named javaagent_JBoss1_9990, should be transferred to the/opt/btm/JBoss1_9990 directory on the target WildFly JBoss server.
13. Log out of the system and log back into the WildFly JBoss server.
14. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.

15. Figure 16 depicts the extracted contents of the zip file.

16. From Figure 16, it is evident that the zip file contains an eg_btm.jar file and a few property files, namely - btmOther.props, btmLogging.props, config.props, custom.props, exclude.props, and threshold.props files.

17. Then, you need to configure the WildFly JBoss server with the path to the eg_btm.jar file. To achieve this, you need to edit the start-up script of the server. The first step towards that is to open the start-up script.

18. Then, in the file, enter the following lines, as depicted by Figure 19.

    JAVA_OPTS="$JAVA_OPTS -javaagent:<<PATH TO the eg_btm.jar>>"

     

    For instance, if the eg_btm.jar file is extracted into the /opt/btm/JBoss1_9990 directory, the above specification will be:

    JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/btm/JBoss1_9990/eg_btm.jar"

    

    Figure 19 : Editing the start-up script to BTM-enable a WildFly JBoss server on Unix that is monitored in an agentless manner

19. Where multiple instances of WildFly JBoss are monitored, make sure you perform steps 17 and 18 above for each WildFly JBoss server instance.

20. Next, if the JBoss server is running in domain mode, open the domain.conf file in JBoss_Home/bin directory. If the JBoss server is running in standalone mode, open the standalone.conf file in the JBoss_Home/bin directory. 

    

    Figure 20 : Editing the domain.conf file or standalone.conf file

21. Append ",com.eg" to the following line in the file, as depicted by Figure 18:

    set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs="org.jboss.byteman"

22. Finally, save the file and restart the WildFly JBoss server instance.

Verifying Whether/Not the WildFly JBoss Server Has Been Successfully BTM-Enabled

Once the –javaagent JVM option is added and server is restarted, do the following:

• Check for the presence of “[eG BTM]” and  “BTM is ENABLED” in application server’s standard output (see Figure 21). If text similar to the ones indicated by Figure 21 is found in the log file, it implies that the -javaagent entry is taken and BTM is successfully enabled.

  

  Figure 21 : Verifying whether/not the WildFly JBoss server is successfully BTM-enabled