3 Installing the AD4J Agent

This chapter describes the procedure to install the AD4J Agent. It covers the following:

• Before you Start

• Installing the AD4J Agent on Oracle Application Server 10g

• Installing the AD4J Agent on Oracle WebLogic

• Installing the AD4J Agent on Apache Tomcat

• Installing the Oracle AD4J Agent on Apache JServ

• Installing the Oracle AD4J Agent on IBM WebSphere

• Installing the Oracle AD4J Agent on Standalone Java Applications

• Installing the Database Agent

Before you Start

To install the AD4J Agent, you must do the following:

• Login to your Application Server console.

• Download the Java agent from the Oracle AD4J Console and deploy it to the JVM using the standard deployment techniques for your Application Server.

• If necessary, customize the AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent.

• Download the DB Agent from the Oracle AD4J Console and deploy it to your database.

Customizing the Oracle AD4J Agent

The AD4J Agent WAR file contains an embedded web.xml deployment descriptor. This file contains the default values of the Oracle AD4J Agent input parameters. You can change the parameters if you want. To do so, extract the web.xml file from the WAR archive and then update it.

To explode or update the WAR file, do the following:

• To extract the web.xml file from the WAR archive, run the following command:

  jar xvf jamagent.war WEB-INF/web.xml

• Edit the web.xml file with your custom values for input parameters in any text editor. You may only change the values within the <param-name> fields of this file. No other changes are supported.

• Then run the following command to place the new web.xml file back into the archive:

  jar uvf jamagent.war WEB-INF/web.xml

• To remove the newly created directory, run the following command:

  rm -rf WEB-INF

The following are the Oracle AD4J Agent parameters.

Table 3-1 Oracle AD4J Agent Parameters

Parameter	Default	Description
jamconshost	localhost	The server where console is running.
jamconsport	3600	The port where the console is listening for the agents.
jamjvmid	Application Server Port or 5555	Identifies the specific JVM on the console when you have multiple JVMs on the same machine. For most app servers, this identifier is the port which the server is listening on (Web Server Port for Weblogic, Jserv port for Apache). If the application server port cannot be discovered then this value is used.
jamconsretr	90	If the console goes down, the agent will keep trying to reconnect. This parameter specifies the duration in seconds between each attempt. The default value is 90 seconds (15 minutes) between each try. If this parameter is set to 0, then the agent will not try to reconnect.
jamtimeout	300	Maximum time duration for a request. If a request takes longer time than this timeout, it is terminated.
jamloglevel	3	Level of logging. Valid values range from 1 to 5.
jammaxbackoff	10	Some times we wait for other operations to finish (like GC or main thread initialization). The amount of sleep time between the retries increases exponentially till this number. When this number is reached, we give up and return with failure.
jamdelaystartup	0	This parameter is only for standalone programs. If you want to analyze the startup behavior of a monitored program, you can use this parameter. This specifies the number of seconds to wait before starting the target program.
jamisdaemon	false	This parameter is only for standalone programs. When using jamrun with standalone programs, the agent will normally exit when the main method in the target program completes. In some programs the threads might still be active after main completes.In such cases specify jamisdaemon=true to prevent the agent from exiting.

Web.XML Contents

<?xml version="1.0" ?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN""http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<servlet>
<servlet-name>jamagent</servlet-name>
<servlet-class>jamagent.jaminit</servlet-class>
<init-param>
<param-name>jamconshost</param-name>
<param-value>localhost</param-value>
<description>Default Jam Console host</description>
</init-param>
<init-param>
<param-name>jamconsport</param-name>
<param-value>3600</param-value>
<description>Jam console port</description>
</init-param>
<init-param>
<param-name>jamconsretr</param-name>
<param-value>90</param-value>
<description>Jam console number of retries</description>
</init-param>
<init-param>
<param-name>jamtimeout</param-name>
<param-value>900</param-value>
<description>Jam console timeout</description>
</init-param>
<init-param>
<param-name>jamloglevel</param-name>
<param-value>3</param-value>
<description>Jam log level</description>
</init-param>
<init-param>
<param-name>jammaxbackoff</param-name>
<param-value>10</param-value>
<description>Max time to wait for long operations</description>
</init-param> 
<init-param>
<param-name>jamjvmid</param-name>
<param-value>Aplication Server Port</param-value>
<description> Unique Identifier for JVM. It will detect and use the WLS port bydefault.</description>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
</web-app>

Installing the AD4J Agent on Oracle Application Server 10g

This section describes the procedure to install the AD4J Agent on Oracle Application Server 10g. To install the Agent, you must do the following:

• Login to the Enterprise Manager 10g console to administer Application Server 10g. Enterprise Manager 10g is installed by default when you install iAS 10g. Make sure you can log on to Enterprise Manager as the administrative user, ias_admin.

• Deploy the jamgent.war file from the Oracle AD4J Console as described in Deploying the Agent WAR.

• Customize the Oracle AD4J Agent and specify the parameters. The jamgent.war file contains the java classes and native libraries that constitute the Oracle AD4J Agent. It also contains the default Oracle AD4J Agent input parameters in the packaged web.xml file. See Customizing the Oracle AD4J Agent for details.

Deploying the Agent WAR

The following steps assume that the Oracle AD4J Console is running on the host where the .war file is deployed. The steps also assume that Oracle AD4J Console is using the default port, that is, port 3600. If not, then change the default settings. For information about the default settings and the procedure to change them, refer to Customizing the Oracle AD4J Agent.

To deploy the agent WAR file:

1. Log on to Enterprise Manager iAS 10g as ias_admin.

   Enterprise Manager displays the Home page by default.

2. On the Home page, in the System Components section, you will find an OC4J instance called home. This OC4J instance is available by default. Click the home instance name to open the administration page of this OC4J instance.

3. Click the Applications tab.

   Enterprise Manager displays the page for managing applications deployed in the home OC4J instance.

4. Click Deploy WAR file and provide the following details:

   • Web Application - Specify the path (along with the file name) for the jamgent.war file. You can click Browse to locate the file on your computer.

   • Application Name - Specify jamagent.

   • Map to URL - Specify /jamagent.

5. Click Deploy to deploy the jamagent.war file.

6. To test the deployment, log on to the Oracle AD4J Console and view the JVM running the OC4J instance on the main page.

Installing the AD4J Agent on Oracle WebLogic

This section describes the procedure to install the AD4J Agent on Oracle WebLogic. Before you install the AD4J Agent, you must have installed and configured the Oracle AD4J Console. You must also ensure that the Weblogic Administration Console is up and running. To install the AD4J Agent, you must do the following:

• Login to the Oracle WebLogic Admin Console.

• Deploy the jamgent.war containing the agent classes and the native libraries as described in Deploying the Agent WAR.

• Customize the Oracle AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent. The jamagent.war also contains the default Oracle AD4J Agent input parameters in the packaged web.xml file.

Deploying the Agent WAR

To deploy the Agent WAR file, do the following:

1. Log on to the Administration Console using the following URL:

   http://weblogichost:ADMINPORT/console

2. From the tree view, select Deployments and then Web Application Modules.

   The Web Applications page displays the web applications currently deployed on the Weblogic Application Server.

   Figure 3-1 Web Application Modules

   
   

3. On the Web Applications page, click Deploy a New Web Application Module.

   The Deploy a Web Application Module page displays.

   Figure 3-2 Uploading the WAR Archive

   
   

4. On the Deploy a Web Application Module page, do the following:

   • Upload the WAR archive directly from the local file system.Choose the WAR archive placed on the server.Use the exploded WAR on the server

   Explore all three approaches.

5. Select the jamagent.WAR file.

   Figure 3-3 Choosing the jamagent.WAR file

   
   

6. Go to the next screen and click Deploy.

   Figure 3-4 Deploy a Web Application Module

   
   

   A successful deployment takes you to the following screen:

   Figure 3-5 Successful Deployment

   
   

Installing the AD4J Agent on Apache Tomcat

This section describes the procedure to install the AD4J Agent on Apache Tomcat. Before you install the agent, you must ensure that Tomcat has been correctly installed. You can test this by starting Tomcat and bringing up the default page - http://<host>:8080. If you have not installed on the default port, replace 8080 with your port number. To install the agent, you must do the following:

• Copy jamagent.war to $CATALINA_HOME/webapps directory.

• Deploy the jamagent.war file containing the java classes and native libraries that constitute the Oracle AD4J Agent. See Deploying the Agent WAR for details.

• Customize the Oracle AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent. The jamagent.war also contains the default Oracle AD4J Agent input parameters in the packaged web.xml file.

• Restart Tomcat.

Deploying the Agent WAR

These steps assume that the Oracle AD4J Console is running on the same host where the war file is being deployed. It also assumes that Oracle AD4J Console is using the default port - 3600. If not, refer to Customizing the Oracle AD4J Agent to change these default settings.

1. Copy the jamagent.war to the $CATALINA_HOME/webapps directory.

2. Shutdown Tomcat using $CATALINA_HOME/bin/shutdown.sh

3. Startup Tomcat using $CATALINA_HOME/bin/startup.sh

4. Tomcat automatically explodes the war and deploys it.

5. To test, log on to the Oracle AD4J Console. The jvm running Tomcat now appears on the main page.

Installing the Oracle AD4J Agent on Apache JServ

This section describes the procedure to install the Oracle AD4J Agent on Apache JServ. To install the agent, you must do the following:

• Include the file jamagent.zip in the CLASS_PATH. This is described in:

  • Setting Up the CLASSPATH - Automatic Mode

  • Setting Up the CLASSPATH - Manual Mode

• Edit the Jserv configuration files to load the servlet jamagent.jaminit as describe in Loading the Servlet at Startup Time.

  Note:

  You need a copy of jamagent.zip for your platform and a working console for the agent to connect to. (The console must be up and listening for JVM connections on localhost port 3600).

• Customize the Oracle AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent.

Setting Up the CLASSPATH - Automatic Mode

If you are running Apache in automatic mode (jserv.conf: ApJServManual is off), apache automatically starts the JVMs. The CLASSPATH is specified in jserv.properties by the parameter wrapper.classpath. If your jamagent.zip lives in /u01/app/jam/jamagent, then you'll add the following line to jserv.properties wrapper.classpath=/u01/app/jam/jamagent/jamagent.zip.

Setting Up the CLASSPATH - Manual Mode

When ApJServManual is on, you must use a separate script (typically called jservctl) to start the JVM. You have to add jamagent.zip to the CLASS_PATH in this file. You can do this in either of these methods:

• CLASSPATH is defined as an environment variable

• CLASSPATH is passed with -classpath to the java command

If your jamagent.zip is located in the /u01/app/jam/jamagent directory, you must add /u01/app/jam/jamgent/jamagent.zip to the CLASSPATH.

Loading the Servlet at Startup Time

To load the servlet at startup time, add the following lines to the zone.properties file for Apache Jserv:

servlets.startup=jamagent.jaminitservlet.jamagent.jaminit.initArgs=jamconshost=localhostservlet.jamagent.jaminit.initArgs=jamconsport=3600

The first line instructs the servlet container to start the servlet jamagent.jaminit. The other one passes the startup parameters jamconshost=localhost and jamconsport=3600 to specify the location of the console.

Installing the Oracle AD4J Agent on IBM WebSphere

This section describes the procedure to install the Oracle AD4J Agent on IBM WebSphere. Before you install the agent, the WebSphere Administrative Console should be up and running. You must also have installed and configured Oracle AD4J Console. For WebSphere installation, you require a jamagent.war file that contains the java classes and native libraries that constitute the Oracle AD4J Agent. To install the agent, you must do the following:

• Log on to the IBM WebSphere Application Server Express Administrative Console.

• Deploy jamagent.war containing the agent classes and native libraries as described in Deploying the Agent WAR.

• Customize the Oracle AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent. The jamagent.war also contains the default Oracle AD4J Agent input parameters in the packaged web.xml file.

Deploying the Agent WAR

To deploy the Agent WAR file, do the following:

1. Log on to the Administrative Console using the following URL:

   http://hostname:7090/admin

2. From the tree view, select Applications and then Install New Application.

   The Preparing for Application Installation page opens where you can select the module to upload.

   Figure 3-6 Preparing for Application Installation

   
   

3. Click Browse to choose the downloaded jamagent.war file from your desktop.

4. Provide a context root of jamagent in the Context Root text box.

5. Select the Generate Default Bindings and click Next.

6. Review warning if any and click Continue.

7. Select the Enable Class Reloading check box from the AppDeployment Options section and click Next. (figure)

8. Select jamagent.war from the Step:2 Map virtual hosts for Web Module section of the Install New Application page and click Next.

   Figure 3-7 Install New Application - Step 2

   
   

9. Select jamagent.war for Step 3: Map modules to application Servers as well and click Finish.

10. Click Save to Master Configuration and then click Save.

11. Click the Enterprise Application from the tree view on the left side.

12. Select jamagent.war and click Start.

    AD4J agent is deployed and started.

Installing the Oracle AD4J Agent on Standalone Java Applications

This section describes the procedure to install the Oracle AD4J Agent on Standalone Java Applications. Before you install the agent, you must have installed and configured the Oracle AD4J Console. To install the agent, you must do the following:

• Include the jamagent.zip in the CLASSPATH. See Adding the Oracle AD4J Agent and Libraries, Classes to Classpath.

• Change the java call to call the jamagent.jamrun wrapper class. The wrapper class is required to monitor and diagnose Java programs that do not have a way of loading a servlet or another class. The following sections describe the original and modified java call:

  • Original Java Call

  • Modified Java Call with Oracle AD4J Agent

• Customize the Oracle AD4J Agent and specify the parameters as described in Customizing the Oracle AD4J Agent.

Original Java Call

java $JVM_OPTIONS $TARGET_CLASS $TARGET_CLASS_PARAMS

Here, JVM_OPTIONS are the JVM properties and options.

For example:

-Xmx512M -Dweblogic.name

TARGET_CLASS is the program which being examined

TARGET_CLASS_PARAMS are parameters passed to the class

The idea is to run the target program through jamagent.jamrun. This is done by calling the jamagent.jamrun.

Modified Java Call with Oracle AD4J Agent

java $JVM_OPTIONS jamagent.jamrun [$JAMAGENT_PARAMS_LIST] $TARGET_CLASS $TARGET_CLASS_PARAMS

Oracle AD4J uses default parameters. If you want to change any parameter, you can specify them as name=value pairs. To specify a different console and port, enter the following command:

jamconshost=<console hostname>, jamconsport=<console port>

Thus, to run the Oracle AD4J Agent, you just need to edit the script which starts your program.

It is not required to do anything with the target program parameters. They are picked up and passed along to the program by jamrun.

Sample Configuration

In this example, the MainClass is being called and the steps to edit the Java Call are shown below:

"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} com.example.MainClass

The class being called is com.example.MainClass. There are no parameters. Insert the class and parameters before the class as follows:

"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} jamagent.jamrun com.example.MainClass

If you want to change some Oracle AD4J parameters, you can specify them as:

"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} jamagent.jamrun jamconshost=myconsole01 jamisdaemon=true jamjvmid=3001 com.example.MainClass

Refer to the Frequently Asked Questions appendix for more details on setting the jamisdemon parameter.

Adding the Oracle AD4J Agent and Libraries, Classes to Classpath

We also need to add the jamagent.zip directory to the CLASSPATH.

It is best to do this just before the call to java.

Here we find a couple of lines above the call to Java.

CLASSPATH="example1.jar:example2.jar

We can add the jamagent.zip file to the CLASSPATH by adding the following line before the original Java call.

CLASSPATH=${CLASSPATH} : /opt/jamagent/jamagent.zip

Target Parameters

About the -Dweblogic and other properties, you must insert jamagent.jamrun just before the calling program and its parameters. This should happen after all the JVM options and properties have been specified.

Installing the Database Agent

To track database bottlenecks to Java and Java bottlenecks into the database, you need to run a DB Agent on the DB Server and register the database with the console. This section outlines the steps to accomplish this and contains the following steps:

• Prerequisites

• Register the Database in the Setup Tab

• Download the DB Agent for Your Platform from the Console

• Download the Agent for Your Database Platform

Prerequisites

• Oracle AD4J Console needs to be installed, configured and accessible.You need to have the admin password on Oracle AD4J Console to register a new databaseYou will then need the DB username and password on the target database with select privileges on GV_$SESSION, GV_$SESSION_WAIT, GV_$PROCESS, GV_$SQLTEXT, GV_$SQLAREA, GV_$LOCK, and GV_$LATCHNAME fixed views.You will also need to be able to run a program on the database server as the OS user who owns the database (in most cases this is the user name oracle)

  Note:

  In this release, databases running on Windows cannot be monitored.

Register the Database in the Setup Tab

Follow these steps to register the database:

1. Click the Setup tab.

2. The Setup options are displayed. Click Databases. The Show Registered Databases screen is displayed.

   Figure 3-8 Show Registered Databases

   
   

3. Click Register New DB. The Add Database Information screen is displayed.

   Figure 3-9 Add Database Information

   
   

4. Enter the database information and click Save to register the new database.

Note:

Before you can monitor a RAC database, you need to register all the nodes in the database and run the Agent on each node.

Download the DB Agent for Your Platform from the Console

Follow these steps to download the DB Agent for your platform:

1. Click the Setup tab.

2. The Setup options are displayed. Click Download Agent. The Download AD4J Agent is displayed.

   Figure 3-10 Download AD4J Agent

   
   

3. Click on the Download icon to download the agent for your database platform.

Download the Agent for Your Database Platform

Depending on your method of upload to the database server, you might need to change the permissions of the agent.

chmod +x dbagent

Note:

On some operating systems (such as AIX), due to system level restrictions, you must run the dbagent as the root user.

The dbagent needs two parameters to be passed to it, which are:

• the host where the console is running.

• the port which is being used to accept connections from the agents (default value 3600).

To pass these parameters, enter the following command:

nohup dbagent jamconshost=console01 jamconsport=3600 > dbagent.log 2>&1 &

You should see the following message in the console error log.

JAM Console: Agent connection from 192.168.1.31:59269, [Hostname] jamdb.us.oracle.com

JAM Console: Received AJDBOracle|Oracle-Sun9i|oracle|SunOS 5.8|oracle|3|0|0 Oracle AD4J Console: New DB 0

The number next to New DB changes everytime a new DB agent is pointed to the AD4J Console.

Note:

If you want to stop the database agent, then manually kill the process. For UNIX platforms, run the ps command to view the database agent process and kill it using the kill command.