Installing eG Java BTM on an IBM WebSphere

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

BTM-Enabling a WebSphere Server Monitored in an Agent-based Manner

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

  1. Login to the WebSphere server.
  2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
  3. Manage the WebSphere server as a separate component using the eG administrative interface. When doing so, make sure that the Agentless flag is unchecked.

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

    Figure 1 : Identifying theWebSphere server monitored in an agent-based manner, 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 WebSphere server monitored in an agent-based manner

  6. Next, proceed to BTM-enable the WebSphere server, using one of the following procedures:

    • Using the WebSphere administration console;
    • By editing the server.xml file
  7. To use the administration console, do the following:

    • First, login to the console. When Figure 3 appears, click on the WebSphere Application Server link in the right panel.

      Figure 3 : The WebSphere Administration console

    • This will invoke Figure 4. In the right panel of Figure 4, click on the link representing the WebSphere server instance that you want to BTM-enable.

      Figure 4 : Clicking on the WebSphere server instance to be BTM-enabled

    • Figure 14 will then appear.

      Figure 5 : The Configuration tab page of the WebSphere server instance to be BTM-enabled

    • Keep scrolling down the right panel of Figure 6 until you find the Server Infrastructure section. Expand the Java and Process Management node in that section, and click on the Process definition link within.

      Figure 6 : Selecting the Process definition option from Java and Process Management tree

    • Figure 7 will then appear. From the Additional Properties section, select Java Virtual Machines.

      Figure 7 : Configuring the Process definition

    • When Figure 8 appears, scroll down its right panel until the Generic JVM Arguments text box comes into view.

      Figure 8 : Configuring the JVM arguments for a WebSphere Server on Windows

    • Paste the code block you copied at step 5 above to the Generic JVM arguments specification, as indicated by Figure 8 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 WebSphere server.
    • Then, click the Apply button and Save link in Figure 8 to save the changes.
    • Finally, stop and start the server.
  8. To use the server.xml file, do the following:

    • Edit the server.xml file in the <WebSphere_Install_Dir>\AppServer\profiles\AppSrv01\config\cells\eGDP183Node01Cell\nodes\eGDP183Node01 \servers\<WebSphere_server_instance_to_be_BTM-enabled> directory.
    • Look for the genericJvmArguments section in the file, and append the code block you copied at step 5 above to that section (see Figure 9).

      Figure 9 : Editing the server.xml file

    • Then, save the file.
    • Finally, start and stop the server.

BTM-Enabling a WebSphere Server Monitored in an Agentless Manner

To BTM-enable a WebSphere server on Windows, which is monitored in an agentless manner, follow the steps below:

  1. Login to the WebSphere server.
  2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
  3. Manage the WebSphere 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 WebSphere 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 WebSphere 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 WebSphere server using the nick name WebSphere1 and the port number 9080, the new directory under the btm directory should be named as WebSphere1_9080.
  6. If you have managed multiple WebSphere 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 WebSphere 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 10 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WebSphere 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 WebSphere 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 10 : Downloading the APM Profiler Agent for the WebSphere server

  10. Upon clicking the Download icon in Figure 10, a zip file named javaagent_<Nick_name_of_WebSphere_server>_<Port_number_of_WebSphere_server will get downloaded. For instance, if you have managed the WebSphere server using the nickname 'WebSphere1' and the port number '9080', then the name of the zip file will be javaagent_WebSphere1_9080. Where multiple WebSphere 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_WebSphere1_9080, should be copied to the C:\btm\WebSphere1_9080 directory .
  12. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.
  13. Figure 11 depicts the extracted contents of the zip file.

    Figure 11 : Contents of the APM Profiler Agent zip

  14. From Figure 11, 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 WebSphere server with the path to the eg_btm.jar and .props files. For this, first login to the WebSphere administration console. When Figure 3 appears, click on the WebSphere Application Server link in the right panel.

    Figure 12 : The WebSphere Administration console

  16. This will invoke Figure 4. In the right panel of Figure 4, click on the link representing the WebSphere server instance that you want to BTM-enable.

    Figure 13 : Clicking on the WebSphere server instance to be BTM-enabled

  17. Figure 14 will then appear.

    Figure 14 : The Configuration tab page of the WebSphere server instance to be BTM-enabled

  18. Keep scrolling down the right panel of Figure 6 until you find the Server Infrastructure section. Expand the Java and Process Management node in that section, and click on the Process definition link within.

    Figure 15 : Selecting the Process definition option from Java and Process Management tree

  19. Figure 7 will then appear. From the Additional Properties section, select Java Virtual Machines.

    Figure 16 : Configuring the Process definition

  20. When Figure 8 appears, scroll down its right panel until the Generic JVM Arguments text box comes into view.

    Figure 17 : Configuring the JVM arguments for a WebSphere Server on Windows

  21. Here, specify the following:

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

     

    For instance, if the eg_btm.jar file had been copied to the C:\btm\Websphere1_9080 directory, the above specification will be:

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

  22. Save the changes and restart the WebSphere server.
  23. Where multiple instances of WebSphere are monitored, make sure you perform step 15- 23 above for each WebSphere server instance.

If the target WebSphere 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 WebSphere 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 WebSphere 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 WebSphere 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 WebSphere 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 WebSphere server using the nick name tomcat1 and the port number 8080, the new directory under the btm directory should be named as tomcat1_8080.
  7. If you have managed multiple WebSphere 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 WebSphere 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 10 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WebSphere 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 WebSphere 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 10, a zip file named javaagent_<Nick_name_of_WebSphere_server>_<Port_number_of_WebSphere_server will get downloaded. For instance, if you have managed the WebSphere server using the nickname 'WebSphere1' and the port number '9080', then the name of the zip file will be javaagent_WebSphere1_9080. Where multiple WebSphere 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 WebSphere 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 WebSphere server in steps 6 and 7 above.  For example, the zip file named javaagent_WebSphere1_9080, should be transferred to the/opt/btm/WebSphere1_9080 directory on the target WebSphere server.
  13. Log out of the system and log back into the WebSphere server.
  14. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.
  15. Figure 11 depicts the extracted contents of the zip file.

  16. From Figure 11, 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 WebSphere server with the path to the eg_btm.jar and .props files. For this, first login to the WebSphere administration console. When Figure 3 appears, click on the WebSphere Application Server link in the right panel.

  18. This will invoke Figure 4. In the right panel of Figure 4, click on the link representing the WebSphere server instance that you want to BTM-enable.

  19. Figure 14 will then appear.

  20. Keep scrolling down the right panel of Figure 6 until you find the Server Infrastructure section. Expand the Java and Process Management node in that section, and click on the Process definition link within.

  21. Figure 6 will then appear. From the Additional Properties section, select Java Virtual Machines.

  22. When Figure 8 appears, scroll down its right panel until the Generic JVM Arguments text box of Figure 8 comes into view.

    Figure 18 : Configuring the JVM arguments for a WebSphere Server on Unix

  23. Here, specify the following:

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

     

    For instance, if the eg_btm.jar file and .props files have been copied to the /opt/egurkha/lib/btm/Websphere1_9080 directory, the specification will be: :

    -javaagent:/opt/btm/WebSphere1_9080/eg_btm.jar

  24. Save the changes and restart the WebSphere server.
  25. Where multiple instances of WebSphere are monitored, make sure you perform step 17- 25 above for each WebSphere server instance.

Verifying Whether/not the WebSphere server is Successfully BTM-enabled

You can verify whether/not the WebSphere server was successfully BTM-enabled. For that, follow the steps below:

  • Open the application server’s standard output log file. This is the native.stdout.log file, which you will find in the <WEBSPHERE_INSTALL_DIR>\AppServer\profiles\AppSrv01\logs\<WEBSPHERE_SERVER_INSTANCE>\ directory.

  • Check for the presence of “[eG BTM]” and “BTM is ENABLED” in application server’s standard output. If this text is present in the native.stdout.log file, as indicated by Figure 19, it implies that the –javaagent entry is taken and BTM is successfully enabled.

    Figure 19 : Verifying whether/not the WebSphere server is successfully BTM-enabled