This chapter describes how to install JENNIFER Agent. JENNIFER agent can be installed in the web application server or a stand-alone JAVA daemon.
Descriptions about Agent Directories
Unzip JENNIFER agent package file, and the agent.java directory is then created. This chapter explains the directories in the agent.java directory.
Directory Name | Description |
|---|---|
conf | Directory that contains Agent configuration files |
upgrade | Directory to save Agent upgrade files |
logs | Directory that contains Agent log files |
libs | Directory that contains libraries needed by the Agent |
Description of Agent Files
In the agent.java directory, a pair of .jar files are included for each version. The jennifer.jar file contains only the interface, and the file of the latest version is loaded when the Agent starts. Descriptions of these files are provided below.
File Name | Description |
|---|---|
jennifer.impl-x.x.x.jar | Contains codes that can trace the BCI code and the Agent |
jennifer.jar | Contains the common interface of JENNIFER Agent |
conf/jennifer.conf | Default settings file of the Agent |
If a single server has multiple monitoring targets, you can copy the configuration file.
Agent Configuration and Settings
Installation of JENNIFER Agent could be more accurately described as changing the JAVA option settings of the monitoring target.
JAVA Options for JENNIFER Agent Configuration
To configure JENNIFER Agent in the web application server, the following two options should be activated.
Provided that the Agent home is /home/jennifer5/agent.java, add options as follows.
Options |
|---|
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf |
-javaagent:/home/jennifer5/agent.java/jennifer.jar |
JENNIFER Agent supports JDK 1.5 or higher.
Required Agent Options
There are options that need to be activated to initialize the Agent. Descriptions of the required options are as follows:
Option | Default Value | Description |
|---|---|---|
server_address | 127.0.0.1 | IP of the Data Server |
server_port | 5000 | Port of the Data Server |
domain_id | 1000 | Domain ID |
log_dir | ../logs | Folder to save log files |
log_encoding | UTF-8 | Encoding type of log files |
log_rotation | true | Determines whether to create a new log file daily or continue recording the log in a file consecutively. When set to True, a new log file is created daily. |
The valid range of a Domain ID is an integer from 1 to 32767. As this value is referenced by both the Data Sever and the View Server, a different value should be designated for each Domain ID, even if multiple Data Servers are operated.
In addition, it is possible to access up to 100 Instances per Domain. When 100 Instances are registered in the list, access by a new agent is denied.
Configure inst_id (Instance ID) Manually
You can add an inst_id to the configuration file (jennifer.conf) and configure the settings for the ID.
inst_id = 999
If there is no inst_id at the time of initial installation, an inst_id is automatically assigned from the data server, and the applicable inst_id is created in an ascending order from 10000.
The valid range of inst_id is an integer from 1 to 32767.
Install JENNIFER Agent
This chapter describes how to install JENNIFER Agent for each web application server. Installation means adding two options to the JAVA option.
Add JENNIFER Agent settings to the JAVA start-up options for the monitoring target.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
A restart is required after the initial installation of JENNIFER.
The default installation method for each web application server is summarized below.
Install JENNIFER Agent on WebSphere
In the WebSphere control console, select the [Select Application Server | Define Process | Java Virtual Machine] menu.
Only WebSphere 6.1 or higher is supported (only JDK 1.5 or higher is supported).
Input the value stated below in the general JDM factor.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
Save the settings.
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on WebLogic
$DOMAIN_HOME/bin/startWebLogic.sh(bat) is the file that configures the default JAVA options for WebLogic.
Only WebLogic 9.x or higher is supported (only JDK 1.5 or higher is supported).
In the $DOMAIN_HOME/bin/startWebLogic.sh(bat) file of WebLogic, add the following two options to JAVA_OPTIONS.
When running multiple instances in a single Domain, all instances are started via startWebLogic.sh. In this case, it is necessary to ensure that different configuration files are applied to the -Djennifer.conf option. For example, the configuration file needs to be received as server.name variable, or to be inserted in the script calling startWebLogic.sh(bat); in other words, a start-up script for each Instance.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent is properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on Tomcat
The default configuration file for Tomcat is $CATALINA_HOME/bin/catalina.sh(bat).
Only Tomcat 5.0 or higher is supported (only JDK 1.5 or higher is supported).
In the $CATALINA_HOME/bin/catalina.sh(bat) file of Tomcat, add the following two options to JAVA_OPTS.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on Resin
With Resin, the default configuration file is different for each version.
The default configuration file for Resin 3.1.x is $RESIN_HOME/conf/resin.conf.
The default configuration file for Resin 4.x is $RESIN_HOME/conf/resin.xml.
Only Resin 3.1 or higher is supported (only JDK 1.5 or higher is supported).
In the $RESIN_HOME/conf/resin.conf or $RESIN_HOME/conf/resin.xml file of Resin, add the following two options to <jvm-arg>.
<jvm-arg>-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf</jvm-arg> <jvm-arg>-javaagent:/home/jennifer5/agent.java/jennifer.jar</jvm-arg>
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on JEUS
$JEUS_HOME/config/$hostname/JEUSMain.xml is the file that configures the default JAVA options for JEUS.
Only JEUS 4.2 or higher is supported (only JDK 1.5 or higher is supported).
In the $JEUS_HOME/config/$hostname/JEUSMain.xml file of JEUS, add the following two options inside <command-option></command-option>.
<command-option> -Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar </command-option>
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on JBoss
JBoss is divided into the community version and the EAP version. The description in this chapter is based on the EAP version. With JBoss, the default configuration file is different for each version.
The default configuration file for JBoss EAP 4 and 5 is $JBOSS_HOME/bin/run.conf.
The default configuration file for JBoss EAP 6 is $JBOSS_HOME/bin/standalone.conf (domain.conf for the domain version).
Only JBoss-eap 4 (JBoss community version 5) or higher is supported (only JDK 1.5 or higher is supported).
In the configuration file for JBoss, add the following two options to JAVA_OPTS.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
For JBoss EAP 7, add jennifer to the jboss.modules.system.pkgs option in the configuration file.
Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on GlassFish
You can see the JAVA options for GlassFish in the [Configuration | JVM Settings | JVM Options] menu on the Management screen.
Only GlassFish 3 or higher is supported (only JDK 1.5 or higher is supported).
In the [Configurations | JVM Settings | JVM Options] menu on the management console screen, click Add JVM Option to add the following two options and save the settings.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
In the osgi.properties file located in $GLASSFISH_HOME/config directory, add the following to the org.osgi.framework.bootdelegation option.
org.osgi.framework.bootdelegation=${eclipselink.bootdelegation}, \
com.sun.btrace, com.sun.btrace.*, \
jennifer, jennifer.*, \
org.netbeans.lib.profiler, org.netbeans.lib.profiler.*Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Install JENNIFER Agent on Jetty
The default JAVA option configuration file for Jetty is jetty.sh.
Only Jetty 6 or higher is supported (only JDK 1.5 or higher is supported).
In the jetty.sh file located in $JETTY_HOME/bin directory, add the following two options.
-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf -javaagent:/home/jennifer5/agent.java/jennifer.jar
#####################################################
# Add jetty properties to Java VM options.
#####################################################
JAVA_OPTIONS+=("-Djetty.home=$JETTY_HOME" "-Djava.io.tmpdir=$TMPDIR" "-Djennifer.config=/home/j5/jennifer5/agent.java/conf/jennifer.conf" "-javaagent:/home/j5/jennifer5/agent.java/jennifer.jar" )Restart the application server in which the JENNIFER Agent is installed.
Check the log to verify that the JENNIFER Agent has been properly applied.
2014-03-19/15:35:29 JenniferAgent initialized!! 2014-03-19/15:35:29 Load control module : /home/j5/jennifer5/agent.java/jennifer.impl-1.0.1.jar 2014-03-19/15:35:30 jennifer control module config loading = /home/j5/jennifer5/agent.java/conf/jennifer.conf 2014-03-19/15:35:30 Jennifer Agent Version 1.0.1 2014-03-19/15:35:30 Jennifer Data Server address : 127.0.0.1 2014-03-19/15:35:30 Jennifer Data Server port : 5000 2014-03-19/15:35:30 Jennifer System Domain ID(SID) : 1000 2014-03-19/15:35:30 Jennifer Instance ID : 1 ... 2014-03-19/15:35:39 Jennifer Runtime module loading complete...
Using JNI Module to collect System Resources (CPU, Memory)
To collect system resources (CPU, Memory) via JNI module, follow these steps
Identify appropriate JNI module for the system from the libraries located in the agent lib directory (ex : aix-7.1/libjennifer5-0.1.0-aix7.1_32.so)
Copy the JNI module from the OS directory to the agent lib directory (e.g: AGENT_HOME/libs)
set enable_jmx_for_system_resource option value to false
Restart the Java agent
Confirm that the library is loaded by checking the agent log file for a message similar to the following
2014-03-19/15:35:29 native lib libjennifer5-0.1.0-aix7.1_32.so loaded
Remove JENNIFER Agent
To remove JENNIFER agent, delete the two options applied at the time of installation configuration and restart the WAS.
Upgrade JENNIFER Agent
To remove the JENNIFER agent, delete the two options applied at the time of installation configuration and restart the WAS.