This chapter provides instructions for installing and uninstalling observer libraries for monitoring JavaEE running in WebSphere 6.1 application servers.
Note:
For a list of the exact 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.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 file suitable for installing an observer into a WebSphere application server is BTMObserver_Was_6.1_JavaEE_*.zip (this observer ZIP file is distributed with release 12.1.0.1 rather than release 12.1.0.2).
Note:
In the actual ZIP file, the asterisk (*) is replaced with the observer version number.Locate the observer distribution ZIP file that is appropriate for your version of WebSphere.
This ZIP file contains the observer for WebSphere 6.1.
Unpack the observer ZIP file into your WebSphere installation root directory (WAS_INSTALL_ROOT).
The default location of the WebSphere installation root directory on Windows systems is:
C:\Program Files\IBM\WebSphere\AppServer
On UNIX-like systems, the default location is:
/opt/IBM/WebSphere/AppServer
For the remainder of this procedure, replace WAS_INSTALL_ROOT with the actual path to the WebSphere installation root directory.
Unpacking the ZIP file creates a directory named nanoagent that contains two subdirectories—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.Ensure that the user account running WebSphere 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
Move ap-nano-jaxrpc.jar from nanoagent/lib/bootstrap to WAS_INSTALL_ROOT/lib/ext.
Restart WebSphere and log in to the WebSphere Administrative Console for your profile.
In the WebSphere Administrative Console, navigate to Servers > Application servers > server1 > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine (you might have to substitute a different server name for server1).
Add the observer libraries to your server's class path by adding the observer bootstrap file to the Classpath field as follows:
For Windows systems, add this string:
${WAS_INSTALL_ROOT}\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
For UNIX-like systems, add this string:
${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
Add the following arguments to the Generic JVM arguments field:
For Windows systems, add this string:
-javaagent:${WAS_INSTALL_ROOT}\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar
For UNIX-like systems, add this string:
-javaagent:${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar (Linux/UNIX)
Note:
This property configures the AspectWerkz module. You do not need to set it if you plan to monitor only JAX-RPC services.Add custom properties as follows:
Click the Custom Properties link, and then for each property you are adding, click New, input the name, value, and description, and then click OK. The properties to add follow:
Add a property that specifies the observer home directory:
Name = AP_NANO_HOME
Value = WAS_INSTALL_ROOT/nanoagent
Note:
Replace WAS_INSTALL_ROOT with the actual path to your WebSphere installation root directory. You must uses backslashes for Windows. Follow these examples:For Windows systems:
Value = C:\Program Files\IBM\WebSphere\AppServer
For UNIX-like systems:
Value = /opt/IBM/WebSphere/AppServer
Description = The observer home directory
Add a property that associates the observer with a monitor:
Name = AP_NANO_CONFIG_URL
Value = http://Host:Port/btmmonitor/agent/agent/
Notes:
Replace Host:Port with the host name and port number at which the monitor is available.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.
Description = 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.
Add a property that configures the AspectWerkz module:
Name = aspectwerkz.classloader.preprocessor
Value = com.amberpoint.nanoagent.plugins.APAspectFilterPreProcessor
Description = Business Transaction Management observer class preprocessor
Note:
You do not need to set this property if you plan to monitor only JAX-RPC services.Click Save to save your master configuration.
Shutdown WebSphere and modify the Java policies as described in Java Policy Modifications.
If Java 2 security is enabled for WebSphere, you must make all of the modifications described in the section. If Java 2 security is not enabled, you need modify only the server.policy file.
Ensure that the user under which your WebSphere server is running has permission to write to the observer's error log directory.
By default, the observer's error log directory is the WebSphere profile directory. For information about configuring error logging, see Chapter 16, "Logging Observer Errors and Debugging Information."
Restart WebSphere.
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.
You must modify your WebSphere server's server.policy file as described in Modifications to the WebSphere server.policy file. If Java 2 security is enabled on your WebSphere server, you must also modify your app.policy files as described in Modifications to the app.policy files.
Add the following policy definition to the WebSphere server.policy file and save it (the server.policy file is located at WAS_INSTALL_ROOT/profiles/Profile_Name/properties/server.policy):
grant codeBase "file:${was.install.root}/nanoagent/lib/-" {
permission java.security.AllPermission;
};
Note:
You must use forward slashes in the path, even on Windows.Add permissions to the app.policy file(s) as follows:
WebSphere has an app.policy file for each node. You must make the modification for each node that you want to monitor. The app.policy files are located in:
WAS_INSTALL_ROOT/profiles/profile_name/config/cells/cell_name/nodes/node_name
Add the following permissions to each policy definition in the app.policy file:
permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "accessDeclaredMembers"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "shutdownHooks"; permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.util.logging.LoggingPermission "control"; permission java.lang.RuntimePermission "createClassLoader"; permission java.lang.RuntimePermission "reflectionFactoryAccess"; permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
The following permissions are required in each policy definition in the app.policy file except the application policy definition (the first policy definition in the file). Your app.policy file probably has these permissions already declared. If not, add them.
permission java.net.SocketPermission "*", "connect"; permission java.util.PropertyPermission "*", "read";
Your app.policy file should look something like this when you have finished:
grant codeBase "file:${application}" {
// The following are required by Java mail
permission java.io.FilePermission "${was.install.root}${/}lib${/}mail-impl.jar",
"read";
permission java.io.FilePermission "${was.install.root}${/}lib${/}activation-impl.jar",
"read";
//Permissions Added for BTM observers
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${jars}" {
permission java.net.SocketPermission "*", "connect";
permission java.util.PropertyPermission "*", "read";
//Permissions Added for BTM observers
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${connectorComponent}" {
permission java.net.SocketPermission "*", "connect";
permission java.util.PropertyPermission "*", "read";
//Permissions Added for BTM observers
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${webComponent}" {
permission java.io.FilePermission "${was.module.path}${/}-", "read, write";
permission java.lang.RuntimePermission "loadLibrary.*";
permission java.lang.RuntimePermission "queuePrintJob";
permission java.net.SocketPermission "*", "connect";
permission java.util.PropertyPermission "*", "read";
//Permissions Added for BTM observers
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
grant codeBase "file:${ejbComponent}" {
permission java.lang.RuntimePermission "queuePrintJob";
permission java.net.SocketPermission "*", "connect";
permission java.util.PropertyPermission "*", "read";
//Permissions Added for BTM observers
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.logging.LoggingPermission "control";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "reflectionFactoryAccess";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";
};
Log in to the WebSphere Administrative Console for your profile.
Navigate to Servers > Application Servers > server1 > Server Infrastructure >Java and Process Management > Process Definition >Java Virtual Machine.
You might have to substitute a different server name for server1.
Remove the following line from the Classpath field:
${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
Remove the following line from the Generic JVM arguments field:
-javaagent:${WAS_INSTALL_ROOT}/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar
Navigate to Servers > Application Servers > server1 > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine > Custom Properties.
Remove any and all of the following custom properties (you might not have all of these properties set):
AP_NANO_CONFIG_URL
AP_NANO_HOME
aspectwerkz.classloader.preprocessor
Click Save to save these changes to your master configuration.
Stop the WebSphere server.
Remove ap-nano-jaxrpc.jar from WAS_INSTALL_ROOT\lib\ext.
The default location of the WebSphere installation root directory (WAS_INSTALL_ROOT) on Windows systems is:
C:\Program Files\IBM\WebSphere\AppServer
On UNIX-like systems, the default location is:
/opt/IBM/WebSphere/AppServer
Delete the nanoagent directory from WAS_INSTALL_ROOT, including all subdirectories and files.
Restart WebSphere.