10 Installing Observer Libraries on WebLogic

This chapter provides instructions for installing and uninstalling observer libraries for monitoring:

• JavaEE running in WebLogic application servers versions 9.2, 10.0, and 10.3

• Oracle Service Bus 10gR3 running in WebLogic 10.3 application servers

• Oracle Service Bus 11gR1 running in WebLogic 10.3 application servers

• Oracle SOA Suite 11gR1 running in WebLogic 10.3 application servers

Separate instructions are provided for:

• Installation on Node Manager-Configured Servers

• Installation on Script-Configured Servers

The Observer Distribution Files

The Business Transaction Management observers are distributed by way of ZIP files. Each ZIP file contains one type of observer that is suitable for installation into a particular application server. The ZIP files suitable for installing observers into WebLogic application servers are as follows:

• BTMObserver_Wls_10.3_JavaEE_*.zip – Use this ZIP file to install the observer for JavaEE into a WebLogic 10.3 server.

• BTMObserver_Wls_9.2_JavaEE_*.zip – Use this ZIP file to install the observer for JavaEE into a WebLogic 9.2 or 10.0 server (this observer is distributed with release 12.1.0.1 rather than release 12.1.0.2).

• BTMObserver_Wls_10.3_Soa11gR1_*.zip – Use this ZIP file to install the observer for Oracle SOA Suite into a WebLogic 10.3 server.

• BTMObserver_Wls_10.3_Osb11gR1_*.zip – Use this ZIP file to install the observer for Oracle Service Bus 11gR1 into a WebLogic 10.3 server.

• BTMObserver_Wls_10.3_Osb10gR3_*.zip – Use this ZIP file to install the observer for Oracle Service Bus 10gR3 into a WebLogic 10.3 server (this observer is distributed with release 12.1.0.1 rather than release 12.1.0.2).

Note:

In the complete ZIP file names, the asterisk (*) is replaced with the observer version number.

Installation on Node Manager-Configured Servers

Note:

You must not install more than one observer per application server.

1. Locate the observer distribution ZIP file that is appropriate for your version of WebLogic and the type of traffic you want to monitor.

2. Unpack the observer ZIP file into your WebLogic managed server's home directory (WL_HOME).

   The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3. For the remainder of this procedure, replace the string WL_HOME with the actual path to the WebLogic home directory.

   Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.

   Note:

   By default, the observer looks in the lib directory for its libraries. For information on overwriting this default location, see Specifying the Observer Library Location.

3. Ensure that the user account running WebLogic has at least the following privileges:

   • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

   • read permission on all JAR files in the lib directory

4. If your WebLogic server accesses an Oracle database using either the ojdbc5.jar or ojdbc6.jar database driver, then you must add oraclepki.jar to your server's WL_HOME/server/lib directory.

   You can download oraclepki.jar from the downloads section of Oracle Technology Network (http://www.oracle.com/technetwork/index.html). This JAR file is necessary for the JDBC probe to collect observations correctly.

5. Open the WebLogic Administration Console (the default URL is http://machine_name:7001/console).

6. Do not perform this step if you are installing the JavaEE observer for WebLogic 10.3 (BTMObserver_Wls_10.3_JavaEE_*.zip), but do perform it for all other observers. – Add WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar to your managed server's classpath:

   1. Using the Domain Structure pane (on the left), navigate to Environment > Servers.

   2. In the Servers table, click your managed server.

   3. Display the Configuration / Server Start tab.

   4. Click Lock & Edit.

      Note:

      These instructions assume you are operating in a production environment and that your WebLogic server's Automatically Acquire Lock and Activate Changes setting is therefore disabled. However, if this setting is enabled as it might be in a development environment, you do not have to click Lock & Edit in order to make changes and you do not have to activate changes after saving them.

   5. Add the observer libraries to your server's class path by adding the observer bootstrap file to the Class Path field as follows:

      For Windows systems, add this string, using a semicolon (“;”) to separate entries in the field:

      WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      

      For UNIX-like systems, add this string, using a colon (“:”) to separate entries in the field:

      WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      

      Note:

      If the Class Path field is initially blank, it means that the server is using the default classpath. In this case, adding the observer JAR file to the field will override the default classpath and cause the server not to start. You must, therefore, explicitly specify the default classpath in the field and then append the observer JAR file to it. You can find the value of the default classpath in the your server's log file. The log file is named after the server (for example, server_name.log) and is located in the server's directory under the domain directory. When you open the log file, search for java.class.path. The Class Path field permits spaces, forward slashes, and abbreviated Windows 8.3 names (that use the ~ symbol) within paths.

   6. Keep this page open.

7. With the Configuration / Server Start tab displayed, edit your WebLogic startup arguments as follows:

   1. Create an AP_NANO_HOME system property and set it to the location of the observer's nanoagent directory by adding the following string to the Arguments field:

      Add this string for Windows systems, using spaces to separate entries:

      -DAP_NANO_HOME=WL_HOME\nanoagent
      

      Add this string for UNIX-like systems, using spaces to separate entries:

      -DAP_NANO_HOME=WL_HOME/nanoagent
      

      Note:

      Do not use new lines to separate argument entries.

   2. Create an AP_NANO_CONFIG_URL system property by adding the following string to the Arguments field:

      -DAP_NANO_CONFIG_URL=http://Host:Port/btmmonitor/agent/agent/
      

      Replace Host:Port with the host name and port number of the monitor to which the observer will forward messages.

      This property associates the observer with the monitor whose URL you specify. At startup, the observer retrieves its configuration from the specified monitor and begins sending observations to the monitor.

      Note:

      If you are using replicated monitors, you must set the host and port portion of the URL to the host and port of your load balancer's HTTP virtual server. For example, if the HTTP virtual server's IP address is 10.147.46.152, and its port number is 5072, then you would set the URL to:

      http://10.147.46.152:5072/btmmonitor/agent/agent/
      

      For more information on this topic, see Configuring Your Load Balancer.

   3. Perform this step only if you are installing the JavaEE observer for WebLogic 10.3 (BTMObserver_Wls_10.3_JavaEE_*.zip). – Configure the observer bootstrap module into your server by adding one of the following JVM arguments to the Arguments field.

      Add this argument for Windows systems:

      -javaagent:WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      

      Add this argument for UNIX-like systems:

      -javaagent:WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      

   4. Do not perform this step if you are installing the JavaEE observer for WebLogic 10.3 (BTMObserver_Wls_10.3_JavaEE_*.zip), but do perform it for all other observers. – Configure the AspectWerkz module into your server by adding one of the following sets of JVM arguments to the Arguments field.

      Add these arguments for Windows systems:

      -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar
      

      Add these arguments for UNIX-like systems:

      -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar
      

8. Ensure that the user under which your WebLogic server is running has permission to write to the observer's error log directory.

   By default, the observer's error log directory is the WebLogic domain directory. For information about configuring error logging, see Chapter 15, "Logging Observer Errors and Debugging Information".

9. Click Save and then click Activate Changes.

10. Restart your managed server.

11. Ensure that the monitor to which your observer forwards messages has an Observer Communication policy applied to it.

    For information on applying an Observer Communication policy, see Applying an Observer Communication Policy.

Installation on Script-Configured Servers

Note:

Depending on how you perform this procedure, you can install the observer into either all servers defined in the WebLogic installation or into servers of a specific domain. If you choose to install the observer into a specific domain, you are permitted to install one package of observer types into one domain and a different package of observer types into a different domain. For example, you could install BTMObserver_Wls_10.3_JavaEE_*.zip into one domain in order to observe JavaEE services, install BTMObserver_Wls_10.3_Soa11gR1_*.zip into a second domain in order to observe SOA services, and install BTMObserver_Wls_10.3_Osb11gR1_*.zip into a third domain in order to observe OSB services. In this procedure, the term global install refers to installing the observer into all servers, and the term domain install refers to installing the observer into a specific domain.

1. Locate the observer distribution ZIP file that is appropriate for your version of WebLogic and the type of traffic you want to monitor.

2. Unpack the observer ZIP file into either your WebLogic server's home directory (to perform a global install) or into one of its domain directories (to perform a domain install).

   The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3. For the remainder of this procedure, replace WL_HOME with the actual path to the WebLogic home directory.

   Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.

   Note:

   By default, the observer looks in the lib directory for its libraries. For information on overwriting this default location, see Specifying the Observer Library Location.

3. Ensure that the user account running WebLogic has at least the following privileges:

   • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

   • read permission on all JAR files in the lib directory

4. If your WebLogic server accesses an Oracle database using either the ojdbc5.jar or ojdbc6.jar database driver, then you must add oraclepki.jar to your server's WL_HOME/server/lib directory.

   You can download oraclepki.jar from the downloads section of Oracle Technology Network (http://www.oracle.com/technetwork/index.html). This JAR file is necessary for the JDBC probe to collect observations correctly.

5. Configure your WebLogic domain startup scripts to call the observer script file:

   Note:

   This step assumes that you haven't modified your startWebLogic scripts. If you have modified your scripts, you might also have to modify the installation procedure accordingly.

   1. Navigate to the bin directory of one of the WebLogic domains whose services you want to monitor and open the startup script in a text editor (open bin\startWebLogic.cmd for Windows systems or bin/startWebLogic.sh for UNIX-like systems; do not edit the startup script located directly within the domain directory).

   2. Locate the following line (the first line is for Windows and the second for UNIX-like systems):

      call "%DOMAIN_HOME%\bin\setDomainEnv.cmd"
      
      . ${DOMAIN_HOME}/bin/setDomainEnv.sh
      

   3. Directly after that line, add a line that calls the observer script file:

      If you are performing a global install on a Windows system, add this line:

      call "%WL_HOME%\nanoagent\bin\nanoEnvWeblogic.cmd"
      

      If you are performing a global install on a UNIX-like system, add this line (note the initial period and space):

      . ${WL_HOME}/nanoagent/bin/nanoEnvWeblogic.sh   
      

      If you are performing a domain install on a Windows system, add this line:

      call "%DOMAIN_HOME%\nanoagent\bin\nanoEnvWeblogic.cmd"
      

      If you are performing a domain install on a UNIX-like system, add this line (note the initial period and space):

      . ${DOMAIN_HOME}/nanoagent/bin/nanoEnvWeblogic.sh   
      

      Note:

      If you performed the security-related configuration described in Configuring Security Using Oracle Wallet, you will have already added a call to the setBtmOverriderEnv_via_CredStore script in this location. The relative order in which these scripts are called does not matter.

   4. Perform this step for each domain whose services you want to monitor.

6. Open the observer script file in a text editor.

   The observer script file is the nanoEnvWeblogic.cmd or nanoEnvWeblogic.sh file that your startWebLogic script file calls.

7. If you are performing a domain install, make the following change (otherwise, skip to the next step):

   For Windows systems, locate the line:

     set NANOAGENT_HOME=%WL_HOME%\nanoagent
   

   and change it to:

     set NANOAGENT_HOME=%DOMAIN_HOME%\nanoagent
   

   For UNIX-like systems, locate the line:

     NANOAGENT_HOME=$WL_HOME/nanoagent
   

   and change it to:

     NANOAGENT_HOME=$DOMAIN_HOME/nanoagent
   

   Keep the file open.

8. Associate your observer with a monitor.

   Note:

   The observer script file uses the NANOAGENT_CONFIGURATION_URL variable to set the value of the system property AP_NANO_CONFIG_URL. This system property associates the observer with the monitor whose URL you specify. At startup, the observer retrieves its configuration from the specified monitor and begins sending observations to the monitor.

   1. In the observer script file, locate the following variable definition (the first line is for Windows and the second for UNIX-like systems):

      set NANOAGENT_CONFIGURATION_URL=http://HOST:PORT/btmmonitor/agent/agent/
      
      NANOAGENT_CONFIGURATION_URL=http://HOST:PORT/btmmonitor/agent/agent/
      

   2. Replace HOST:PORT with the host name and port number of the monitor to which you want the observer to send observations, for example:

      set NANOAGENT_CONFIGURATION_URL=http://myhost:7002/btmmonitor/agent/agent
      
      NANOAGENT_CONFIGURATION_URL=http://myhost:7002/btmmonitor/agent/agent"
      

      Note:

      If you are using replicated monitors, you must set the host and port portion of the URL to the host and port of your load balancer's HTTP virtual server. For example, if the HTTP virtual server's IP address is 10.147.46.152, and its port number is 5072, then you would set the URL to:

      http://10.147.46.152:5072/btmmonitor/agent/agent/
      

      For more information about the load balancer's HTTP virtual server, see Configuring Your Load Balancer.

   3. If you are performing a domain install, perform steps 7 and 8 for each domain.

9. Ensure that the user under which your WebLogic server is running has permission to write to the observer's error log directory.

   By default, the observer's error log directory is the WebLogic domain directory. For information about configuring error logging, see Chapter 15, "Logging Observer Errors and Debugging Information".

10. Restart your server.

11. Ensure that the monitor to which your observer forwards messages has an Observer Communication policy applied to it.

    For information on applying an Observer Communication policy, see Applying an Observer Communication Policy.

Uninstalling Observer Libraries for WebLogic

This section describes how to uninstall observer libraries from a WebLogic 9.2 or 10.3 server. The procedure differs according to whether you configure your server using the Node Manager or local scripts.

• If you configure your server using the Node Manager, see Uninstallation from a Managed Server Configured by the Node Manager.

• If you configure your server using local scripts, see Uninstallation from a Server Configured by a Local Script.

Uninstallation from a Managed Server Configured by the Node Manager

1. Stop your WebLogic managed server.

2. Delete the nanoagent folder located in your WebLogic home directory (WL_HOME).

   The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3. For the remainder of this procedure, replace WL_HOME with the actual path to the WebLogic home directory.

3. Open the WebLogic Administration Console (the default URL is http://Machine_Name:7001/console).

4. Remove WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar from your WebLogic managed server's classpath:

   1. Using the navigation pane (on the left), navigate to Environment > Servers.

   2. In the Servers table, click your managed server.

   3. Display the Configuration / Server Start tab.

   4. Click Lock & Edit.

   5. Remove the following string from the Class Path field.

      WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar 
      

   6. Keep this page open.

5. Remove all observer-related startup arguments:

   With the Configuration / Server Start tab displayed, remove any and all of the following strings from the Arguments field:

   -DAP_NANO_HOME=WL_HOME/nanoagent 
   
   -DAP_NANO_CONFIG_URL=http://HOST:PORT/btmmonitor/agent/agent/
   
   -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor
   
   -javaagent:WL_HOME/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar 
   

6. Click Save and then click Activate Changes.

7. Restart your WebLogic server.

Uninstallation from a Server Configured by a Local Script

1. Stop your WebLogic server.

2. Delete the nanoagent folder located in your WebLogic home directory (WL_HOME).

   The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3. For the remainder of this procedure, replace WL_HOME with the actual path to the WebLogic home directory.

3. Navigate to the bin directory of the WebLogic domain whose services you no longer want to monitor and edit the startWebLogic script (startWebLogic.cmd for Windows or startWebLogic.sh for UNIX-like systems). Delete the following line from the script (the first line is for Windows and the second for UNIX-like systems):

   call "%WL_HOME%\nanoagent\bin\nanoEnvWeblogic.cmd"
   
   . ${WL_HOME}/nanoagent/bin/nanoEnvWeblogic.sh
   

4. Restart your WebLogic server.