This chapter provides instructions for installing and uninstalling observer libraries on WebLogic 10.3 and 12 servers.
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 an observer into a WebLogic application server are as follows:
BTMObserver_Wls_10.3_Universal_*.zip – Use this ZIP file to install the observer for JavaEE, Oracle SOA Suite, Oracle Service Bus 11gR1, and Oracle Fusion Applications (ADF-UI, ADF-BC and SOA deployments) into a WebLogic 10.3 server.
BTMObserver_Wls_12_JavaEE_*.zip – Use this ZIP file to install the observer for JavaEE or Oracle Service Bus 12c into a WebLogic 12 server.
BTMObserver_Wls_10.3_Osb11gR1_*.zip – Use this ZIP file to install the observer for Oracle Service Bus 10gR3 into a WebLogic 10.3 server. Note that although the ZIP file name contains the string ”Osb11gR1”, this observer supports Oracle Service Bus 10gR3. This observer is not recommended for Oracle Service Bus 11gR1 (you should instead use BTMObserver_Wls_10.3_Universal_*.zip for that purpose).
Notes:
In the complete ZIP file name, the asterisk (*) is replaced with the observer version number.For a list of the exact platform and application server versions supported by these observers, refer to the Business Transaction Management (BTM) Certification Matrix. You can find this document online at http://support.oracle.com.
For detailed information about a specific observer's compatibility and functionality, refer to the README.txt file located in the observer's nanoagent directory after you expand the observer ZIP file.
Separate installation instructions are provided for:
Locate the appropriate observer distribution ZIP file for your environment and monitoring needs.
Unpack the observer ZIP file into your WebLogic managed server's home directory (WL_HOME).
The home directory is the wlserver_10.3 or wlserver_12.1 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 Section 9.3, "Overriding the Default Location of Observer Libraries."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
Open the WebLogic Administration Console (the default URL is http://machine_name:7001/console).
Prepare to edit your WebLogic startup arguments:
Using the Domain Structure pane (on the left), navigate to Environment > Servers.
In the Servers table, click your managed server.
Display the Configuration / Server Start tab.
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.With the Configuration / Server Start tab displayed, edit your WebLogic startup arguments as follows:
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.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 Section 8.4.
Optional – If you want to target this observer by way of an observer configuration label, create a system property named ap.nano.config.label and set its value to your label string by adding the following string to the Arguments field:
-Dap.nano.config.label=My_Label_String
Replace My_Label_String with the string you want to use as a label for this observer. For more information about targeting observers refer to Section 8.5, "Applying an Observer Communication Policy."
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
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".
Click Save and then click Activate Changes.
Restart your managed server.
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 Section 8.5, "Applying an Observer Communication Policy."
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.Locate the appropriate observer distribution ZIP file for your environment and monitoring needs.
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 or wlserver_12.1 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 Section 9.3, "Overriding the Default Location of Observer Libraries."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
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.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).
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
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 Section 4.3.1, "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.Perform this step for each domain whose services you want to monitor.
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.
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.
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.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/
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 Section 8.4.
If you are performing a domain install, perform steps 6 and 7 for each domain.
Optional – If you want to target this observer by way of an observer configuration label, perform the following substeps:
Note:
The observer script file uses the NANOAGENT_CONFIGURATION_LABEL variable to set the value of the system property ap.nano.config.label. For information about targeting observers refer to Section 8.5, "Applying an Observer Communication Policy."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_LABEL= NANOAGENT_CONFIGURATION_LABEL=
Append your label string to the variable definition, for example:
set NANOAGENT_CONFIGURATION_LABEL=My_Label NANOAGENT_CONFIGURATION_LABEL=My_Label
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".
Restart your server.
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 Section 8.5, "Applying an Observer Communication Policy."
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.
If you configure your server using the Node Manager, see Section 10.3.1, "Uninstallation from a Managed Server Configured by the Node Manager."
If you configure your server using local scripts, see Section 10.3.2, "Uninstallation from a Server Configured by a Local Script."
Stop your WebLogic managed server.
Delete the nanoagent folder located in your WebLogic home directory (WL_HOME).
The home directory is the wlserver_10.3 or wlserver_12.1 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.
Open the WebLogic Administration Console (the default URL is http://Machine_Name:7001/console).
Remove all observer-related startup arguments:
Using the navigation pane (on the left), navigate to Environment > Servers.
In the Servers table, click your managed server.
Display the Configuration / Server Start tab.
Click Lock & Edit.
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/ -Dap.nano.config.label=My_Label -javaagent:WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar -javaagent:WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
Click Save and then click Activate Changes.
Restart your WebLogic server.
Stop your WebLogic server.
Delete the nanoagent folder located in your WebLogic home directory (WL_HOME).
The home directory is the wlserver_10.3 or wlserver_12.1 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.
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
Restart your WebLogic server.