11 Installing Observer Libraries on JBoss

This chapter provides instructions for upgrading, installing, and uninstalling observer libraries for monitoring JavaEE running in JBossEAP 4.3 application servers.

The Observer Distribution File

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 only type of observer that you can install on a JBoss server is the observer for monitoring JavaEE. Use BTMObserver_Jboss_4.3_JavaEE_*.zip to install this observer.

Note:

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

Installing the Observer Libraries on JBossEAP 4.3

Shut down your JBoss server.
Locate the observer distribution ZIP file for JBoss (BTMObserver_Jboss_4.3_JavaEE_*.zip).
Unpack the ZIP file into JBOSS_HOME.

JBOSS_HOME refers to the value of your JBOSS_HOME environment variable

Unpacking the ZIP file creates a nanoagent directory containing three subdirectories—config, jaxws, 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 JBoss 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
If you want to monitor JAX-WS services:
1. Move ap-nano-jaxws.jar from JBOSS_HOME/nanoagent/jaxws to JBOSS_HOME/server/server_config/lib, where server_config stands for the server configuration directory (for example, JBOSS_HOME/server/default/lib).
2. Configure the observer into the message flow of the JAX-WS services that you want to manage by inserting the observer into your services' post handler chains. These post handler chains are defined in JBOSS_HOME/server/server_config/deploy/jbossws.sar/META-INF/standard-jaxws-endpoint-config.xml and standard-jaxws-client-config.xml.
  
  Note:
  Before editing your standard-jaxws-endpoint-config.xml and standard-jaxws-client-config.xml files, save a backup copy to use in case you want to uninstall the observer.
  
  If you are using the default standard-jaxws-client-config.xml and standard-jaxws-endpoint-config.xml files provided by JBoss, you can simply replace them with the like-named files provided with Business Transaction Management and located in JBOSS_HOME/nanoagent/jaxws. In this case, you don't need to edit the files. Otherwise, edit the files according to the following description.
  
  The file standard-jaxws-endpoint-config.xml defines a number of endpoint configurations that control processing of inbound requests. By default, all of your JAX-WS endpoints are associated with the configuration named Standard Endpoint. Likewise, the file standard-jaxws-client-config.xml defines a number of client configurations that control processing of outbound requests. By default, all of your JAX-WS clients (that is, your services acting as clients) are associated with the configuration named Standard Client.
  
  You must insert the observer as a handler into the post handler chain of each configuration associated with the services you want to manage. If you have not explicitly associated particular endpoints and clients with non-default configurations, then you need to edit only the Standard Endpoint and Standard Client configurations.
  
  Place the observer-handler in front of any other handlers that might already exist in the handler chain.
  
  The following example shows the observer-handler inserted into the Standard Endpoint configuration:
```
<endpoint-config>
 <config-name>Standard Endpoint</config-name>
 <post-handler-chains>
  <javaee:handler-chain>
   <javaee:handler>
    <javaee:handler-name>EndpointGlobalHandler</javaee:handler-name>
    <javaee:handler-class>com.amberpoint.jaxws.jboss.handlers.JBossJaxwsEndpointHandler</javaee:handler-class>
   </javaee:handler>
  </javaee:handler-chain>
 </post-handler-chains>
</endpoint-config>
```
  The following example shows the observer-handler inserted into the Standard Client configuration:
```
<client-config>
 <config-name>Standard Client</config-name>
 <post-handler-chains>
  <javaee:handler-chain>
   <javaee:handler>
    <javaee:handler-name>ClientGlobalHandler</javaee:handler-name>
    <javaee:handler-class>com.amberpoint.jaxws.jboss.handlers.JBossJaxwsCallSideHandler</javaee:handler-class>
   </javaee:handler>
  </javaee:handler-chain>
 </post-handler-chains>
 <feature>http://org.jboss.ws/dispatch/validate</feature>
 <property>
  <property-name>http://org.jboss.ws/http#chunksize</property-name>
  <property-value>2048</property-value>
 </property>
</client-config>
```
  For more code examples showing insertion of the observer-handler, refer to the annotated standard-jaxws-client-config.xml and standard-jaxws-endpoint-config.xml files provided with Business Transaction Management and located in JBOSS_HOME/nanoagent/jaxws.

Modify the ClassPath and JVM arguments for your JBoss server.

Your edit to the JVM arguments includes adding a system property named AP_NANO_CONFIG_URL. This property associates the observer with the monitor whose URL you specify in the property. At startup, the observer retrieves its configuration from the specified monitor and begins sending observations to the monitor. Following is an example of the URL. Edit only the host name and port number:

http://my_host:8080/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.

Here are the platform-specific details:

(Windows systems) – Locate the following line in JBOSS_HOME\bin\run.bat:

set JBOSS_ENDORSED_DIRS=%JBOSS_HOME%\lib\endorsed

Directly after that line, insert the following code (replacing Monitor_URL, in the next-to-last line, with the monitor's URL):

rem Set up the observer.

set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;..\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar

set AW_OPTS=-javaagent:..\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar

set JAVA_OPTS=%JAVA_OPTS% %AW_OPTS% -DAP_NANO_HOME=..\nanoagent -DAP_NANO_CONFIG_URL=Monitor_URL -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor

(UNIX-like systems) – Locate the following line in JBOSS_HOME/bin/run.sh:

JBOSS_ENDORSED_DIRS="$JBOSS_HOME/lib/endorsed"

Directly after that line, insert the following code (replacing Monitor_URL, in the next-to-last line, with the URL of the monitor):

#Set up the observer. 

JBOSS_CLASSPATH=$JBOSS_CLASSPATH:../nanoagent/lib/bootstrap/ap-nano-bootstrap.jar

AW_OPTS="-javaagent:../nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar"

#LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../nanoagent/lib/bootstrap

#export LD_LIBRARY_PATH

#Note: set LD_LIBRARY_PATH as $LD_LIBRARY_PATH:../nanoagent/lib/bootstrap/solaris/x86
for Solaris Intel

#and $LD_LIBRARY_PATH:../nanoagent/lib/bootstrap/solaris/sparc for Solaris Sparc.

JAVA_OPTS="$JAVA_OPTS $AW_OPTS -DAP_NANO_HOME=../nanoagent -DAP_NANO_HOME=..\nanoagent
-DAP_NANO_CONFIG_URL=Monitor_URL  -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor"

Note:

If your server is running on Solaris, set your LD_LIBRARY_PATH variable as indicated in the commented lines. Otherwise, you can omit the commented lines.

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

By default, the observer's error log directory is JBOSS_HOME/bin. For information about configuring error logging, see Chapter 14, "Logging Observer Errors and Debugging Information."
Restart your JBoss 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 Applying an Observer Communication Policy.

Uninstalling the Observer Libraries from JBossEAP 4.3

Shut down your JBoss server.
Remove ap-nano-jaxws.jar from JBOSS_HOME/server/server_config/lib.

JBOSS_HOME refers to the value of your JBOSS_HOME environment variable and server_config refers to the server configuration directory (for example, JBOSS_HOME/server/default/lib).

Note:
This JAR file is used for monitoring JAX-WS services and will be present only if you set up your observer to monitor JAX-WS services.
Replace the files JBOSS_HOME/server/server_config/deploy/jbossws.sar/META-INF/standard-jaxws-client-config.xml and standard-jaxrws-endpoint-config.xml with the backup copies you made of the original files.
Delete the JBOSS_HOME/nanoagent directory.

Unset all observer-related system properties:

(Windows systems) – Remove any and all of the following lines from JBOSS_HOME/bin/run.bat:

rem Set up observer.
set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;..\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar

set AW_OPTS=-javaagent:..\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar

set JAVA_OPTS=%JAVA_OPTS% %AW_OPTS% -DAP_NANO_HOME=..\nanoagent -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor

(UNIX-like systems) – Remove any and all of the following lines from JBOSS_HOME/bin/run.sh:

#Set up observer. 

JBOSS_CLASSPATH=$JBOSS_CLASSPATH:../nanoagent/lib/bootstrap/ap-nano-bootstrap.jar

AW_OPTS="-javaagent:../nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar"

#LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../nanoagent/lib/bootstrap

#export LD_LIBRARY_PATH

#Note: set LD_LIBRARY_PATH as $LD_LIBRARY_PATH:../nanoagent/lib/bootstrap/solaris/x86 for Solaris Intel and

#$LD_LIBRARY_PATH:../nanoagent/lib/bootstrap/solaris/sparc for Solaris Sparc.

JAVA_OPTS="$JAVA_OPTS $AW_OPTS -DAP_NANO_HOME=../nanoagent -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor"

Restart your JBoss server.