Skip Headers
Oracle® Enterprise Manager Oracle Application Diagnostics for Java (Oracle AD4J) Installation and Administration Guide
10g Release 5 (10.2.0.5)

Part Number E11085-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Installing the AD4J Agent

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

Before you Start

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

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:

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:

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

    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

    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

    Choosing the jamagent.WAR file
  6. Go to the next screen and click Deploy.

    Figure 3-4 Deploy a Web Application Module

    Deploy a Web Application Module

    A successful deployment takes you to the following screen:

    Figure 3-5 Successful Deployment

    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:

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:

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:

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

    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

    Install new Application
  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:

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

  • 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

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

    Figure 3-9 Add Database Information

    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

    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.