Skip Headers
Oracle® Business Transaction Management Installation Guide
12.1.0.3

E37016-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Installing Observer Libraries on WebLogic

This chapter provides instructions for installing and uninstalling observer libraries on WebLogic 10.3 servers. The observer for WebLogic 10.3 is capable of monitoring:

Note:

For a list of the exact platform and application server versions supported by this observer, refer to the Business Transaction Management (BTM) Certification Matrix. You can find this document online at http://support.oracle.com.

Separate installation instructions are provided for:

The Observer Distribution File

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 file suitable for installing an observer into a WebLogic application server is BTMObserver_Wls_10.3_Universal_*.zip.

Notes:

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

In previous releases, technology-specific monitoring capabilities were divided between multiple observers. In this release (12.1.0.3), the universal observer combines all of those monitoring capabilities into one observer.

Installation on Node Manager-Configured Servers

  1. Locate the observer distribution ZIP file for WebLogic 10.3 (BTMObserver_Wls_10.3_Universal_*.zip).

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

    The home directory is the wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\WL_10-3-2-0\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 directories named nanoagent and security_add_ons. The nanoagent directory contains three subdirectories named 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 Overriding the Default Location of Observer Libraries.
  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. Open the WebLogic Administration Console (the default URL is http://machine_name:7001/console).

  5. Prepare to edit your WebLogic startup arguments:

    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.
  6. 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. 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
      
  7. 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 14, "Logging Observer Errors and Debugging Information".

  8. Click Save and then click Activate Changes.

  9. Restart your managed server.

  10. 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. 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 for WebLogic 10.3 (BTMObserver_Wls_10.3_Universal_*.zip).

  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 wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\WL_10-3-2-0\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 directories named nanoagent and security_add_ons. The nanoagent directory contains three subdirectories named 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 Overriding the Default Location of Observer Libraries.
  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. 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.

  5. 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.

  6. 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.

  7. 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 6 and 7 for each domain.

  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 14, "Logging Observer Errors and Debugging Information".

  9. Restart your server.

  10. 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 10.3 server. The procedure differs according to whether you configure your server using the Node Manager or local scripts.

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 wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\WL_10-3-2-0\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 all observer-related startup arguments:

    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 any and all of the following strings from the Arguments field:

      -DAP_NANO_HOME=WL_HOME/nanoagent
      -DAP_NANO_HOME=WL_HOME\nanoagent
      -DAP_NANO_CONFIG_URL=http://HOST:PORT/btmmonitor/agent/agent/
      -javaagent:WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      -javaagent:WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      
  5. Click Save and then click Activate Changes.

  6. 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 wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\WL_10-3-2-0\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.