Installing eG Java BTM on an Oracle WebLogic Server

The steps for deploying the eG Java BTM on a WebLogic server will differ based on the what type of server is being monitored - whether an Admin server or a server instance - and how eG Enterprise has been configured to monitor that server/instance - whether in an agent-based or agentless manner.

BTM-Enabling a WebLogic Server Managed in an Agent-based Manner

Follow the steps below to BTM-enable a WebLogic Admin Server that is managed in an agent-based manner:

  1. Login to the WebLogic server.
  2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
  3. Manage the WebLogic server as a separate component using the eG administrative interface. When managing, make sure you set the Agentless flag unchecked.
  4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface.
  5. Figure 1 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WebLogic Admin server that you want to BTM-enable. Once you locate the server, click the Copy JVM icon corresponding to that server.

    Figure 1 : Locating the WebLogic Admin Server that is to be BTM-enabled

  6. Figure 2 will then appear. Click on the Copy button to Figure 2 to copy the JVM options displayed therein to a text editor or clip board.

    Figure 2 : Copying JVM options

  7. Next, navigate to the <WEBLOGIC_HOME_DIR>\bin directory and edit the setDomainEnv.bat file (on Windows; on Unix systems, this will be the setDomainEnv.sh file).
  8. Look for the JAVA_OPTIONS setting in the file. Once you find it, append the code block you copied to the editor/clip board at step 6 above, to the JAVA_OPTIONS setting, as indicated by Figure 3. 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 WebLogic server.

    Figure 3 : Setting JAVA_OPTIONS for the WebLogic Admin server

  9. Save the file, stop the Admin server, and start it.

Follow the steps below to BTM-enable a WebLogic server/instance that is managed in an agent-based manner:

  1. Login to the WebLogic server.
  2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
  3. Manage the WebLogic server as a separate component using the eG administrative interface. When managing, make sure you set the Agentless flag unchecked.
  4. Next, follow the Agents -> BTM Profiler Download menu sequence in the eG admin interface.
  5. Figure 1 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WebLogic server/instance that you want to BTM-enable. Once you locate the server, click the Copy JVM icon corresponding to that server.

    Figure 4 : Locating the WebLogic server/instance that is to be BTM-enabled

  6. Figure 2 will then appear. Click on the Copy button to Figure 2 to copy the JVM options displayed therein to a text editor or clip board.

    Figure 5 : Copying JVM options for a WebLogic server/instance

  7. Next, proceed to BTM-enable the target WebLogic server/instance. This can be achieved using either of the following approaches:

    • Using the WebLogic server console;
    • By editing the setDomainEnv file on the server/instance

  8. To use the WebLogic server console, first login to the console. Then, navigate to the <WEBLOGIC_HOME_DIR>\bin directory and edit the setDomainEnv.bat file (on Windows; on Unix systems, this will be the setDomainEnv.sh file).
  1. Look for the JAVA_OPTIONS setting in the file. Once you find it, append the code block you copied to the editor/clip board at step 6 above, to the JAVA_OPTIONS setting, as indicated by Figure 3. 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 WebLogic server.

    Figure 6 : Setting JAVA_OPTIONS for the WebLogic Admin server

  2. Save the file, stop the Admin server, and start it.

  1. Login to the WebLogic server.
  2. Open a browser on the server, connect to the eG manager, and login to the eG admin interface.
  3. Manage the WebLogic server as a separate component using the eG administrative interface. When managing, make sure you set the Agentless flag unchecked.
  4. If multiple WebLogic 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 WebLogic 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 WebLogic server using the nick name weblogic1 and the port number 7001, the new directory under the btm directory should be named as weblogic1_7001.
  6. If you have managed multiple WebLogic 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 WebLogic 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 1 will appear listing the servers that can be instrumented for APM by eG. In this list, locate the WebLogic 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 WebLogic 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 7 : Downloading the APM Profiler Agent for the WebLogic server

  10. Upon clicking the Download icon in Figure 1, a zip file named javaagent_<Nick_name_of_WebLogic_server>_<Port_number_of_WebLogic_server will get downloaded. For instance, if you have managed the WebLogic server using the nickname 'weblogic1' and the port number '7001', then the name of the zip file will be javaagent_weblogic1_7001. Where multiple WebLogic 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_weblogic1_7001, should be copied to the C:\btm\weblogic1_7001 directory .
  12. Extract the contents of each zip file into the same sub-directory to which that zip file was copied.
  13. Figure 8 depicts the extracted contents of the zip file.

    Figure 8 : Contents of the APM Profiler Agent zip

  14. From Figure 8, 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. Next, proceed to BTM-enable the WebLogic server/instance. For that, edit the btmOther.props file in the sub-directory (of the btm directory) that corresponds to that WebLogic server/ instance. You will find the following lines in the file:

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Below property is BTM Server Socket Port, through which eG Agent Communicates

    # Restart is required, if any changes in this property

    # Default port is "13931"

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    #

    BTM_Port=13931

    #

    By default, the BtmPort parameter is set to 13931. If you want to enable eG Java BTM on a different port, then specify the same here. In this case, when configuring the Java Business Transactions test or the Key Java Business Transactions test for that application server, make sure you configure the btm port parameter of the test with this port number.

    Note:

    When BTM-enabling multiple instances on the same server, make sure you configure a different BTM Port for each instance.

    Also, by default, the Designated_Agent parameter will be empty; do not disturb this default setting. In this case therefore, the eG Java BTM will treat the host from which the very first 'measure request' comes in as the Designated_Agent

    Note:

     

    In case a specific Designated_Agent is not provided, and the eG Java BTM treats the host from which the very first 'measure request' comes in as the Designated_Agent, then if such a Designated_Agent is stopped or uninstalled for any reason, the eG Java BTM will wait for a maximum of 10 measure periods for that 'deemed' Designated_Agent to request for metrics. If no requests come in for 10 consecutive measure periods, then the eG Java BTM will begin responding to 'measure requests' coming in from any other eG agent.

  16. Finally, save the btmOther.props file.

  17. Then, you need to configure the WebLogic server/server instance with the path to the eg_btm.jar and .props files. The procedure to achieve this varies, depending upon the following:

    • Whether you want to BTM-enable a stand-alone WebLogic server/server instance
    • Whether you want to BTM-enable the Admin server of a WebLogic cluster
  18. To BTM-enable a stand-alone WebLogic server/server instance, first login to the WebLogic Administration console. Then, follow the steps detailed below:

    • When Figure 9 appears, click on the Servers link in the right panel.

      Figure 9 : Clicking on the Servers link

    • Figure 10 will then appear. Here, click on the server instance to be BTM-enabled.

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

    • Figure 11 will then appear.

      Figure 11 : Viewing the configuration of the chosen server instance

    • Keep scrolling down the right panel of Figure 11 until the Arguments text box comes into view (see Figure 12).

      Figure 12 : Configuring the JVM arguments

    • In the Arguments text box, specify the following lines:

      -javaagent:<Path_to_eg_btm.jar_file>

      -DEG_PROPS_HOME=<Path_to_the_folder_containing_the_.props_files>

      For instance, if the eg_btm.jar file and .props files are extracted into the C:\btm\weblogic1_7001 directory, the above specification will be:

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

      -DEG_PROPS_HOME=C:\btm\weblogic_7001

    • Finally, save the changes and restart the WebLogic server.
  19. Where multiple instances of WebLogic are monitored, make sure you perform step 15-18 above for each WebLogic server instance.
  20. To BTM-enable the Admin server of a WebLogic cluster, you need to edit the start-up script of the Admin server. For that, follow the steps below:

    • Login to the Admin server, open the start-up script, and insert the following lines in it:

       

      set EG_JAVA_OPTIONS_ADMIN_SERVER="-javaagent:<Path_to_eg_btm.jar_file> -DEG_PROPS_HOME=<Path_to_the_folder_containin_.props_files>"

      if "%SERVER_NAME%"=="AdminServer" (

      set EG_JAVA_OPTIONS=%EG_JAVA_OPTIONS_ADMIN_SERVER%

      )

      set JAVA_OPTIONS=%JAVA_OPTIONS% %JAVA_PROPERTIES% -Dwlw.iterativeDev=%iterativeDevFlag% -Dwlw.testConsole=%testConsoleFlag% -Dwlw.logErrorsToConsole=%logErrorsToConsoleFlag% %EG_JAVA_OPTIONS%

       

      For instance, if the eg_btm.jar file and .props files are extracted into the C:\btm\WebLogic_7001 directory, the above specification will be:

      set EG_JAVA_OPTIONS_ADMIN_SERVER="-javaagent:c:\btm\WebLogic_7001\eg_btm.jar -DEG_PROPS_HOME=c:\btm\WebLogic_7001"

      if "%SERVER_NAME%"=="AdminServer" (

      set EG_JAVA_OPTIONS=%EG_JAVA_OPTIONS_ADMIN_SERVER%

      )

      set JAVA_OPTIONS=%JAVA_OPTIONS% %JAVA_PROPERTIES% -Dwlw.iterativeDev=%iterativeDevFlag% -Dwlw.testConsole=%testConsoleFlag% -Dwlw.logErrorsToConsole=%logErrorsToConsoleFlag% %EG_JAVA_OPTIONS%

       

      Figure 13 : Editing the start-up script of the WebLogic Admin server on Windows that is monitored in an agent-based manner

    • Finally, save the file and restart the Admin server.

BTM-Enabling a WebLogic Server Running on a Unix Platform

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

  16. From Figure 8, 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. Next, proceed to BTM-enable the WebLogic server/instance. For that, edit the btmOther.props file in the sub-directory (of the btm directory) that corresponds to that server/ instance. You will find the following lines in the file:

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Below property is BTM Server Socket Port, through which eG Agent Communicates

    # Restart is required, if any changes in this property

    # Default port is "13931"

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    #

    BTM_Port=13931

    #

    By default, the BtmPort parameter is set to 13931. If you want to enable eG Java BTM on a different port, then specify the same here. In this case, when configuring the Java Business Transactions test or the Key Java Business Transactions test for that application server, make sure you configure the btm port parameter of the test with this port number.

    Note:

    When BTM-enabling multiple instances on the same server, make sure you configure a different BTM Port for each instance.

    Also, by default, the Designated_Agent parameter will be empty; do not disturb this default setting. In this case therefore, the eG Java BTM will treat the host from which the very first 'measure request' comes in as the Designated_Agent

    Note:

     

    In case a specific Designated_Agent is not provided, and the eG Java BTM treats the host from which the very first 'measure request' comes in as the Designated_Agent, then if such a Designated_Agent is stopped or uninstalled for any reason, the eG Java BTM will wait for a maximum of 10 measure periods for that 'deemed' Designated_Agent to request for metrics. If no requests come in for 10 consecutive measure periods, then the eG Java BTM will begin responding to 'measure requests' coming in from any other eG agent.

  18. Finally, save the btmOther.props file.

  19. Then, you need to configure the WebLogic server/server instance with the path to the eg_btm.jar and .props files. The procedure to achieve this varies, depending upon the following:

    • Whether you want to BTM-enable a stand-alone WebLogic server/server instance
    • Whether you want to BTM-enable the Admin server of a WebLogic cluster
  20. To BTM-enable a stand-alone WebLogic server/server instance, first login to the WebLogic Administration console. Then, follow the steps detailed below:

    • When Figure 9 appears, click on the Servers link in the right panel.

    • Figure 10 will then appear. Here, click on the server instance to be BTM-enabled.

    • Figure 11 will then appear.

    • Keep scrolling down the right panel of Figure 11 until the Arguments text box comes into view (see Figure 12).

      Figure 14 : Configuring the JVM arguments for a WebLogic server on Unix

    • In the Arguments text box, specify the following lines:

      -javaagent:<Path_to_eg_btm.jar_file>

      -DEG_PROPS_HOME=<Path_to_the_folder_containing_the_.props_files>

      For instance, if the eg_btm.jar file and .props files are extracted into the /opt/btm/weblogic1_7001 directory, the specification will be:

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

      -DEG_PROPS_HOME=/opt/btm/weblogic1_7001

    • Additionally, in Unix environments, if the eG agent is deployed on the same host as the WebLogic server, then both the agent and the server will be running using different user privileges. In this situation, by default, the eG Java BTM logs will not be created. In order to create the same, insert the following entry after the -DEG_PROPS_HOME specification .

      -DEG_LOG_HOME=<LogFile_Path>

      Before providing this specification, make sure you create a folder for BTM logs - say, eGBTMLogs - in any directory to which the target application server has access. Then, against, -DEG_LOG_HOME, provide the full path to the eGBTMLogs directory. Where multiple instances on the same server are to be BTM-enabled, you can use the same directory for writing log files of all instances.

      For example, to create log files in the /App001/eGBTMLogs directory, the complete specification will be as follows:

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

      -DEG_PROPS_HOME=/opt/btm/webLogic_7001

      -DEG_LOG_HOME=/App001/eGBTMLogs

    • Finally, save the changes and restart the WebLogic server.
  21. Where multiple instances of WebLogic are monitored, make sure you perform steps 17-20 above for each WebLogic server instance.
  22. To BTM-enable the Admin server of a WebLogic cluster, you need to edit the start-up script of the Admin server. For that, follow the steps below:

    • Login to the Admin server, open the start-up script, and insert the following lines in it:

       

      set EG_JAVA_OPTIONS_ADMIN_SERVER="-javaagent:<Path_to_eg_btm.jar_file> -DEG_PROPS_HOME=<Path_to_the_folder_containin_.props_files>"

      if "%SERVER_NAME%"=="AdminServer" (

      set EG_JAVA_OPTIONS=%EG_JAVA_OPTIONS_ADMIN_SERVER%

      )

      set JAVA_OPTIONS=%JAVA_OPTIONS% %JAVA_PROPERTIES% -Dwlw.iterativeDev=%iterativeDevFlag% -Dwlw.testConsole=%testConsoleFlag% -Dwlw.logErrorsToConsole=%logErrorsToConsoleFlag% %EG_JAVA_OPTIONS%

       

      For instance, if the eg_btm.jar file and .props files are extracted into the /opt/btm/webLogic1_7001 directory, then your specification will be as follows:

      EG_JAVA_OPTIONS_ADMIN_SERVER="-javaagent:/opt/btm/webLogic_7001/eg_btm.jar -DEG_PROPS_HOME=/opt/btm/webLogic_7001"

       

    • If the eG agent and the Admin server are co-hosted on the same Unix host, then to create the log files, insert the following entry after the -DEG_PROPS_HOME specification and before the closing quotes.

      -DEG_LOG_HOME=<LogFile_Path>

      Before providing this specification, make sure you create a folder for BTM logs - say, eGBTMLogs - in any directory to which the target application server has access. Then, against, -DEG_LOG_HOME, provide the full path to the eGBTMLogs directory. Where multiple instances on the same server are to be BTM-enabled, you can use the same directory for writing log files of all instances.

      For example, to create log files in the /App001/eGBTMLogs directory, the complete specification will be as follows:

      EG_JAVA_OPTIONS_ADMIN_SERVER="-javaagent:/opt/btm/weblogic1_7001/eg_btm.jar -DEG_PROPS_HOME=/opt/btm/webLogic_7001 -DEG_LOG_HOME=/App001/eGBTMLogs"

      if [ "${SERVER_NAME}" = "AdminServer" ] ; then

      EG_JAVA_OPTIONS="${EG_JAVA_OPTIONS_ADMIN_SERVER}"

      fi

      SAVE_JAVA_OPTIONS="${JAVA_OPTIONS} ${EG_JAVA_OPTIONS}"

    • Finally, save the file and restart the Admin server.