Installing eG Java BTM on an Apache Tomcat Server

The steps for deploying the eG Java BTM on a Tomcat server will differ based on how the Tomcat server is being monitored - in an agent-based manner or in an agentless manner.

BTM-Enabling a Tomcat Server that is Monitored in an Agent-based Manner

If the Tomcat server is to be monitored in an agent-based manner, then follow the steps below to BTM-enable that server:

1. Login to the Tomcat server.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the Tomcat server as a separate component using the eG administrative interface.
4. If multiple Tomcat 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.

5. 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 Tomcat server that you managed recently in that list, and click the Copy JVM icon () corresponding to it (see Figure 1).

   

   Figure 1 : Clicking the Copy JVM option corresponding to the Tomcat server managed in an agent-based manner

6. 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 displayed in the admin interface to a clip board or text editor

7. If the Tomcat server being monitored is configured as a Windows service, then, do the following:

   • First, open the Tomcat Control Panel.

     

     Figure 3 : BTM-enabling the Tomcat server on Windows

   • Select the Java tab page in Figure 3 above.
   • In the Java Options section of Figure 3, paste the JVM option you copied to the clip board or text editor at step 6. 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 Tomcat server.
   • Click the Apply and OK buttons in Figure 3.
   • Restart the Tomcat service.

   • Where multiple Tomcat server instances on a host are to be monitored, repeat the steps above for each of the server instances.

8. If the Tomcat server being monitored is configured to operate in the non-service mode, do the following:

   • Edit the <TOMCAT_HOME>\bin\catalina.bat file of the Tomcat server being monitored.

   • Insert the JVM option that you copied to the clip board or editor in step 6 above, in the catalina.bat file, as depicted by Figure 4.

     

     Figure 4 : Inserting the JVM option in the catalina.bat file

   • Typically, you need to search for the string 'JAVA_OPTS' in the catalina.bat file. Once you find it, append the copied code block to the JAVA_OPTS line that pre-exists. After inserting the copied JVM option, make sure that you replace the <<EGURKHA_AGENT_HOME>> tag in the copied code block with the actual install directory of the eG agent deployed on the Tomcat server.

   • Then, save the file.
   • Restart the Tomcat server.

   • Where multiple Tomcat server instances on a host are to be monitored, repeat the steps above for each of the server instances.

9. If the Tomcat server being monitored is configured as a Linux service, do the following:

   • Edit the <TOMCAT_HOME>/bin/catalina.sh file of the Tomcat server being monitored.

   • Insert the JVM option that you copied to the clip board or editor in step 6 above, in the catalina.sh file, as depicted by Figure 5.

     

     Figure 5 : Inserting the JVM option copied to clip board / editor, in the catalina.sh file

   • Typically, you need to search for the string 'JAVA_OPTS' in the catalina.sh file. Once you find it, append the copied code block to the JAVA_OPTS line that pre-exists. After inserting the copied JVM option, make sure that you replace the <<EGURKHA_AGENT_HOME>> tag in the copied code block with the actual install directory of the eG agent deployed on the Tomcat server.
   • Then, save the file.
   • Restart the Tomcat server.

   • Where multiple Tomcat server instances on a host are to be monitored, repeat the steps above for each of the server instances.

BTM-Enabling a Tomcat Server that is Monitored in an Agentless Manner

For this, do the following:

1. Login to the Tomcat server to be monitored.
2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
3. Manage the Tomcat server as a separate component using the eG administrative interface. Make sure you set the monitoring mode as Agentless.
4. If multiple Tomcat 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.
5. Then, create a btm directory anywhere on the Tomcat server - say, E:\btm (on Windows), or /opt/btm (on Linux). 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 Tomcat server using the nick name tomcat1 and the port number 8080, the new directory under the btm directory should be named as tomcat1_8080.

6. If you have managed multiple Tomcat 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 Tomcat 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 6 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the Tomcat 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 it. If multiple Tomcat 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 6 : Downloading the APM Profiler Agent for the Tomcat server

10. Upon clicking the Download icon in Figure 6, a zip file named javaagent_<Nick_name_of_Tomcat_server>_<Port_number_of_Tomcat_server will get downloaded. For instance, if you have managed the Tomcat server using the nickname 'tomcat1' and the port number '8080', then the name of the zip file will be javaagent_tomcat1_8080. Where multiple Tomcat 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.  For example, if the Tomcat server is running as a Windows service or as a standalone application server on Windows, then the zip file named javaagent_tomcat1_8080, should be copied to the E:\btm\tomcat1_8080 directory. On the other hand, If the Tomcat server is running as a Linux service, then, 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 Tomcat server.  For example, the zip file named javaagent_tomcat1_8080, should be transferred to the/opt/btm/tomcat1_8080 directory on the target Tomcat server.
12. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.

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

    

    Figure 7 : Contents of the APM Profiler Agent zip

14. From Figure 7, 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 Tomcat server/server instance with the path to the eg_btm.jar file. If Tomcat is configured as a Windows service, then, do the following:

    • First, open the Tomcat Control Panel and then click the Java tab page within.

      

      Figure 8 : Configuring the Java Options for a Tomcat server that is monitored in an agentless manner

    • In the Java Options section of Figure 8, specify the following:

      -javaagent:<<Full_Path_to_eg_btm.jar>>

       

      For instance, if the eg_btm.jar file had been copied to the E:\btm\tomcat1_8080 directory, then your Java Options specification will be as follows:

      -javaagent:E:\btm\tomcat1_8080\eg_btm.jar

    • Click Apply and OK in Figure 8 to save the changes.
    • Restart the Tomcat server.
    • Where multiple Tomcat server instances on a host are to be monitored, repeat the sub-steps of step 15 for each instance.

16. On the other hand, if the Tomcat server is operating in the non-service mode, then you will have to edit the Tomcat start-up script, to BTM-enable the server. The steps in this regard are as follows:

    • Open the catalina.bat file from the <TOMCAT_HOME>\bin directory on the Tomcat server.

    • Insert the lines of code indicated by Figure 9 to BTM-enable the Tomcat server.

      

      Figure 9 : Editing the catalina.bat file

    • Save the file and restart the Tomcat server.

    • Where multiple Tomcat server instances on a host are to be monitored, repeat the sub-steps of step 16 for each server instance.

17. On the other hand, if the Tomcat server is operating as a Linux service, follow the steps below to BTM-enable that server:

    • First, edit the start-up script of the Tomcat server. For that, first open the start-up script.

    • Insert the following lines in the script (as depicted by Figure 10) to BTM-enable the server.

      if [ "$1" = "start" -o "$1" = "run" ]; then

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

      fi

       

      For instance, if the eg_btm.jar file had been copied to the tomcat1_8080 folder within the /opt//btm folder, then your specification will be as follows:

      if [ "$1" = "start" -o "$1" = "run" ]; then

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

      fi

      

      Figure 10 : Editing the start-up script of a Tomcat server running as a Linux service

    • Save the file.
    • Restart the Tomcat server.
    • Where multiple Tomcat server instances on a host are to be monitored, repeat the sub-steps of step 17 for each server instance.

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

To verify whether/not BTM has been successfully enabled on the target Tomcat server, follow the steps below:

1. Once the –javaagent JVM option is added and server is restarted, check for the presence of “[eG BTM]” and  “BTM is ENABLED” in application server’s standard output.

2. If these text strings are found in the standard output log file, as indicated by Figure 11, it implies that the –javaagent entry is taken and BTM is successfully enabled.

   

   Figure 11 : Verifying whether/not BTM has been successfully enabled on the Tomcat server