3 Installing the AD4J Agent

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.

<?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>

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.

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

   
   

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.

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.

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.

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.

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.

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

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.