This chapter describes how you can install JVM Diagnostics (JVMD) manually in the Enterprise Manager Cloud Control environment.
In particular, this chapter covers the following:
JVM Diagnostics is integrated with Oracle Enterprise Manager Cloud Control. It primarily enables administrators to diagnose performance problems in Java applications in the production environment. By eliminating the need to reproduce problems, it reduces the time required to resolve these problems, thus improving application availability and performance. Using JVMD, administrators can identify the root cause of performance problems in the production environment, without having to reproduce them in the test or development environment.
The following diagram shows the JVMD Architecture:
JVMD Engine is the core analytical engine of the JVMD monitoring system. JVMD Engine collects runtime data from JVMD Agents on request from the OMS, and stores the data in the repository. Multiple JVMD Engines can be configured.
JVMD Agents are the data collectors of the target JVM. JVMD Agents are deployed to managed application servers to collect JVM monitoring data related to JVM threads, stacks, heap and CPU usage, and so on, in real-time, while introducing minimal overhead.
The JVMD Engine runs as an Enterprise JavaBeans (EJB) technology on a WebLogic Server. The JVMD Agent is deployed on the targeted JVM (the one running a production WebLogic Server). It collects real-time data and transmits it to the JVM Diagnostics Engine. This data is stored in the Management Repository, and the collected information is displayed on the Enterprise Manager Cloud Control console for monitoring purposes. The communication between JVMD Engine and JVMD Agent can be secure (SSL), or non-secure.
Before installing JVMD Engine or JVMD Agent, review the points outlined in Oracle Enterprise Manager Cloud Control Basic Installation Guide.
Before installing JVMD Engine or JVMD Agent, ensure that you meet the prerequisites described in Oracle Enterprise Manager Cloud Control Basic Installation Guide.
This section describes how to deploy JVMD Engines and JVMD Agents manually. It consists of the following:
You can deploy JVMD Engine manually, using the ApmEngineSetup.pl
script. You can run this script in the following ways:
In interactive mode, where you are prompted for input details in an interactive manner
In silent mode, where you specify all the input details using a properties file
Important:
You can use theApmEngineSetup.pl
script to deploy JVMD Engine only on a host that is running the OMS, and not on a remote host.To deploy JVMD Engine manually using the ApmEngineSetup.pl
script, follow these steps:
Navigate to the following location on the OMS host:
$<MIDDLEWARE_HOME>/plugins/oracle.sysman.emas.oms.plugin_12.1.0.8.0/archives/jvmd/deployment_Scripts/engine/
View the README.txt
file, for information on using the ApmEngineSetup.pl
script.
Run the ApmEngineSetup.pl
script.
If you want to run the ApmEngineSetup.pl
script in interactive mode, such that you are prompted for the input details, use the following command:
perl ApmEngineSetup.pl
Ensure that you specify the operation as deploy,
and the Engine Type as JVMD.
If you want to run the ApmEngineSetup.pl
script in silent mode, specify all the input details in a properties file, then use the following command:
perl ApmEngineSetup.pl -silent -file <properties_file_name> -password <password>
<properties_file_name>
is the name of the properties file where the JVMD Engine and operation details are provided. <password>
is the WebLogic console password.
To learn how to specify the input details in a properties file, view the sample properties file SAMPLE_engine.properties.
This section describes how to deploy JVMD Agents manually. It consists of the following:
Deploying JVMD Agents Manually by Downloading and Deploying javadiagnosticagent.ear or jamagent.war
Ensuring Secure Communication by Connecting JVMD Agent to the JVMD Engine Secure Port
To deploy JVMD Agents manually, follow these steps:
Download javadiagnosticagent.ear or jamagent.war.
Note:
Oracle recommends that you usejavadiagnosticagent.ear
to deploy a JVMD Agent on Oracle WebLogic Server. To deploy a JVMD Agent on an application server other than Oracle WebLogic Server, use jamagent.war.
Downloading javadiagnosticagent.ear or jamagent.war Using Cloud Control
To download javadiagnosticagent.ear
or jamagent.war
using Cloud Control, follow these steps:
In Cloud Control, from the Setup menu, select Middleware Management, then select Application Performance Management.
On the Application Performance Management page, select JVM Diagnostics Engine.
Click Configure. The JVM Diagnostics Setup page appears.
On the JVM Diagnostics Setup page, click JVMs and Pools, then click Download. The Download JVM Diagnostics Component dialog box appears.
From the JVMD Component menu, to download javadiagnosticagent.ear,
select JVMD Agent with MDA (Weblogic only), then click OK. To download jamagent.war,
from the JVMD Component menu, select JVMD Agent, then click OK. The JVM Diagnostics Agent web.xml
parameters dialog box appears.
From the Available Engines menu, select an option from the list, then click Download:
Select the HTTP URL if you want the JVMD Agent to connect to the JVMD Engine using a non-secure connection.
Select the HTTPS URL if you want the JVMD Agent to connect to the JVMD Engine using a secure connection.
Select Custom if you want the JVMD Agent to connect to a JVMD Engine through a load balancer. Specify the host name and the port that the JVMD Agent must connect to.
For example:
HTTP: http://slc01.us.example.com:3800
HTTPS: https://slc01.us.example.com:3801 (secure communication)
Click Download to download javadiagnosticagent.ear
or jamagent.war.
Downloading jamagent.war Using javadiagnosticagent.ear
To download jamagent.war
using javadiagnosticagent.ear,
follow these steps:
Download the javadiagnosticagent.ear
file to the following location:
<middleware_home>/oms/jvmd
The javadiagnosticagent.ear
file can be downloaded from the following location:
<MIDDLEWARE_HOME>/plugins/oracle.sysman.emas.oms.plugin_12.1.0.8.0/archives/jvmd/javadiagnosticagent.ear
Run the following command to extract javadiagnosticagent.ear
:
jar -xvf javadiagnosticagent.ear
The extracted javadiagnosticagent.ear
file contains jamagent.war.
Run the following command to extract jamagent.war:
jar -xvf jamagent.war
Navigate to WEB-INF/web.xml.
Edit the web.xml
file to update the values of the jamconshost
and jamconsport
parameters, where jamconshost
is the IP of the host on which JVMD Engine is deployed, and jamconsport
is the port of the same host.
Note:
To enable secure communication for the selected JVMD Engine, make the following change to theweb.xml
file:
jamsecureCommunication = 1
For example:
<init-param> <param-name>jamconshost</param-name> <param-value>slc01axn</param-value> <description>Jam console host - demolnx.auptyma.com</description> </init-param> <init-param> <param-name>jamconsport</param-name> <param-value>3800</param-value> <description>Jam console port</description> </init-param>
Note:
Once JVMD Engine is deployed, the IP and the port appear on the JVMD Deployment page as:<Machine Name:Port Number>
Run the following command to reassemble the jamagent.war
file:
jar -cMvf jamagent.war META-INF WEB-INF jamagent oracle
The updated jamagent.war
file is now ready for deployment.
If you encounter any errors during the deployment, see Section J.2.
Deploy JVMD Agent manually.
Deploying JVMD Agent on WebLogic Server
To deploy JVMD Agent on a WebLogic Managed Server manually, follow these steps:
Make a copy of the deployment profile sample_jvmdagent_deploy.properties
available in the jvmd.zip
file. Update the location of the javadiagnosticagent.ear
file, the name of the WebLogic domain, and the server information. Save the profile as jvmdagent_deploy.properties.
For more information about the parameters, view the README.txt
file present in the customprov
folder of the jvmd.zip
file.
Run the following perl script available in the customprov
folder of the jvmd.zip
file to deploy JVMD Agent on all the specified servers.
Deploying JVMD Agent on GlassFish
To deploy JVMD Agent on a GlassFish server manually, follow these steps:
Log in to the Glassfish Administration console.
In the Common Tasks section, click Applications.
In the Deployed Applications section, click Deploy.
For Location, select Packaged File to Be Uploaded to the Server, then specify the location on your local host where jamagent.war
is present.
For Selected Targets, add the server on which you want to deploy jamagent.war.
Click OK.
To deploy JVMD Agent on JBoss manually, follow these steps:
Log in to the JBoss Administration console.
Under Applications, click Web Application (WAR)s.
Click Add a new resource.
Enter the absolute path to jamagent.war
present on your local host.
For both Deploy Exploded and Deploy Farmed, select No.
Click Continue.
To deploy JVMD Agent on JBoss manually, you can also do the following:
Transfer jamagent.war
to the following location:
<JBOSS_HOME>/server/all/deploy
Restart the application server.
Deploying JVMD Agent on Tomcat
To deploy JVMD Agent on Tomcat manually, follow these steps:
Transfer jamagent.war
to the following location:
$CATALINA_BASE/webapps
Restart the application server.
For the latest versions of Tomcat, if the autoDeploy
flag is set to true
in $CATALINA_BASE/conf/server.xml,
you do not need to restart the application server. Tomcat will pick up jamagent.war
at runtime.
Deploying JVMD Agent on Websphere
To deploy JVMD Agent on Websphere manually, follow these steps:
Log in to the Websphere Administration console.
Expand Applications, then click New Application.
Click New Enterprise Application.
For Path to the new application, select Local file system, then specify the location on your local host where jamagent.war
is present.
Provide the context root for jamagent.war.
Save the con figuration.
Start the application.
To deploy JVMD Agent on OC4J manually, follow these steps:
Log in to the OC4J Administration console.
Click Applications.
Click Deploy.
Select Archive is present on local host. For Archive Location, specify the location on your local host where jamagent.war
is present. Click Next.
For Application Name, enter jamagent.
For Context Root, enter /jamagent.
Click Deploy.
Deploying JVMD Agent on a Standalone JVM
A JVMD Agent can be deployed on a standalone JVM such that the inputs are read from web.xml,
or such that you specify the inputs on the command line.
To deploy a JVMD Agent on a standalone JVM such that all the inputs are read from web.xml,
run the following command from the command line:
java -cp <absolute_path_to_jamagent.war> jamagent.jamrun <java_class_with_a_main_method>
To deploy a JVMD Agent on a standalone JVM by specifying all the inputs on the command line, run the following command from the command line:
java -cp <absolute_path_to_jamagent.war> jamagent.jamrun <java_class_with_a_main_method> jamconshost=<jvmd_engine_host> jamconsport=<jvmd_engine_listen_port> jamjvmid=<unique_jvmd_identifier> jamtimeout=<timeout_period_in_seconds> jamloglevel=<jvmd_agent_log_level>
Note:
Whenjamagent.war
is run using an IBM Java Development Kit (JDK), you may see the following warning in the logs:
******can_tag_objects capability is not set.Copy library libjamcapability to another directory and restart Java with argument "-agentpath:<absolute_path_to_libjamcapability.so>" ******
To troubleshoot this warning, include the libjamcapability.so
library and restart the IBM JVM:
/scratch/IBM/WebSphere/AppServer/java/bin/java -agentpath:/scratch/libjamcapability.so -cp /scratch/jamagent.war jamagent.jamrun MyFirstProgram
You can deploy JVMD Agents manually, using the deploy_jvmdagent.pl
script. You can run this script only in silent mode, that is, you must specify all the input details using a properties file.
To deploy JVMD Agents manually using deploy_jvmdagent.pl,
follow these steps:
Ensure that the latest version of javadiagnosticagent.ear
or jamagent.war
has been downloaded.
For information on how to download javadiagnosticagent.ear
or jamagent.war,
see Step 1 in Section 13.4.2.1.
Navigate to the following location on the OMS host:
$<MIDDLEWARE_HOME>/plugins/oracle.sysman.emas.oms.plugin_12.1.0.8.0/archives/jvmd/deployment_Scripts/agent/jvmd/
View the README.txt
file for information on how to use the deploy_jvmdagent.pl
script.
Specify all the inputs in a properties file, then use the following command:
perl deploy_jvmdagent.pl [-appserver <server_type>] [-file <name_of_properties_file>]
For example, perl deploy_jvmdagent.pl -appserver WLS -file wls_deploy.properties.
Deploying JVMD Agents using deploy_jvmdagent.pl
is supported only on WebLogic Server and GlassFish, and not on other application servers. The -appserver
parameter specifies the application server on which you want to deploy a JVMD Agent. If you are deploying a JVMD Agent on a WebLogic Managed Server, specify WLS
for -appserver.
If you are deploying a JVMD Agent on a GlassFish server, specify GF
for -appserver.
If you do not specify the -appserver
parameter, it is assigned the value WLS
by default.
The -file
parameter specifies the name of the properties file containing the deployment inputs. If you do not specify this parameter, and have specified WLS
for -appserver,
deploy_jvmdagent.pl
searches for a properties file named weblogic_deploy.properties
in the folder containing the script. If you do not specify the -file
parameter, and have specified GF
for -appserver,
deploy_jvmdagent.pl
looks for a properties file named glassfish_deploy.properties
in the folder containing the script. To learn how to specify the input details in a properties file, view the sample properties files sample_weblogic_deploy.properties
or sample_glassfish_deploy.properties.
If you have multiple JVMD Engines deployed in your setup, and have configured a load balancer for them, you can deploy JVMD Agents such that they connect to the load balancer, and not to any of the individual JVMD Engines. This increases the availability of the JVMD Agents, and creates a failover mechanism, that is, even if a particular JVMD Engine goes down, the JVMD Agents remain active.
You can deploy JVMD Agents for high availability using the Application Performance Management page, or manually.
Deploying JVMD Agents for High Availability Using the Application Performance Management Page
To deploy JVMD Agents for high availability using the Application Performance Management page, follow these steps:
Follow the steps mentioned in Oracle Enterprise Manager Cloud Control Basic Installation Guide to deploy a JVMD Agent.
On the JVMD Agents Configurations page, for Available JVMD Engines, select Other. Provide the load balancer host name and port.
Click Next.
On the Review page, review all the information, then click Deploy.
Note:
By default, the JVMD Agent connects to the load balancer using HTTP. If you want the JVMD Agent to connect to the load balancer using HTTPS, you must deploy the JVMD Agent manually, as described in Step 2 of Section 13.4.2.1.Deploying JVMD Agents for High Availability Manually
To deploy JVMD Agents for high availability manually, follow these steps:
Follow the steps mentioned in Step 1 of Section 13.4.2.1 to download javadiagnosticagent.ear
or jamagent.war.
When the JVM Diagnostics Agent web.xml
parameters dialog box is displayed, from the Available Engines menu, select Custom. Provide the load balancer host name and port.
Click Download.
Deploy the JVMD Agent as mentioned in Step 2 of Section 13.4.2.1.
Note:
By default, the JVMD Agent connects to the load balancer using HTTP. If you want the JVMD Agent to connect to the load balancer using HTTPS, you must use a certificate, as described in Section 13.4.2.5. Ensure that the common name of the certificate you use matches the host name of the load balancer.To deploy JVMD Database Agent, download JVMD Agent from Cloud Control, as it can serve as a JVMD Database Agent too. If JVMD Agent is downloaded and deployed on the same host as Oracle Database, then you do not require a separate JVMD Database Agent. JVMD Agent itself orchestrates between the database and JVMD Engine. However, if JVMD Agent and the database are on separate hosts, then you need a JVMD Database Agent to collect the database specific information, and transmit the collected data to JVMD Engine.
Note:
JVMD Database Agents are supported on the platforms on which JVMD Agents are supported, except for Microsoft Windows. JVMD Database Agent needs Java 1.4.X or higher to run.To download and deploy JVMD Database Agent, do the following:
Follow the steps listed in Step 1 of Section 13.4.2.1 to download the jamagent.war
file using Cloud Control.
To start the JVMD Database Agent, run the following command:
$JAVA_HOME/bin/java -Xms126M -Xmx512M -cp ./jamagent.war jamagent.Dbagent jamconshost=<Host on which engine is running> jamconsport=<Port of the server on which JVMD Engine is installed> For Example: /usr/local/packages/jdk14/bin/java -Xms126M -Xmx512M -cp ./jamagent.war jamagent.Dbagent jamconshost=adc2190661.us.example.com jamconsport=3900
Note:
If you encounter the error messageTIMEOUT from console JAM Agent: Error receiving data from console,
then restart the JVMD Database Agent with the option jamconsretr = 5.
To ensure secure communication with the JVMD Engine, the JVMD Agent must have access to a KeyStore in which the certificate of the Managed Server (on which the JVMD Engine is deployed) is added. The KeyStore of the Enterprise Manager Cloud Control domain (that is, the EMGC domain in which the JVMD Engine Managed Server is created) can be used for the same.
If the JVMD Engine and the JVMD Agent are running on the same host, the JVMD Agent will have access to the EMGC domain and the default KeyStore. In this case, follow these steps to ensure secure communication:
Locate the KeyStore. It is usually available in the following location:
<WEBLOGIC_HOME>/server/lib/DemoTrust.jks
WEBLOGIC_HOME
refers to the installation directory of the WebLogic Server software.
Log in to the WebLogic Server Administration Console.
From the Environment menu, select Servers.
Select the Managed Server on which the JVMD Agent is deployed, then select the Server Start tab.
For Arguments, specify the following arguments:
-Djavax.net.debug=ssl -Djavax.net.ssl.trustStore=<location_of_DemoTrust.jks>
-Djavax.net.ssl.trustStorePassword=<DemoTrust.jks_KeyStore_password>
Restart the Managed Server.
If the JVMD Engine and the JVMD Agent are running on different hosts, which is the case in most environments, you must download the SSL certificate from the JVMD Engine Managed Server, then add the certificate to a new or an existing KeyStore on the target Managed Server where the JVMD Agent is deployed. This enables the JVMD Agent to access the certificate and communicate with the JVMD Engine secure port. To do this, follow these steps:
Follow these steps to download the JVMD Engine Managed Server certificate:
Access the following URL using a browser:
https://<jamconshost>:<jamconsport(secure)>
From the Tools menu, select Options.
Select the Advanced tab, then select the Encryption tab.
Click View Certificates.
Select the Servers tab, search for the <jamconshost>:<jamconsport(secure)>
certificate, then select it. Click Export.
Save the certificate as JVMDCert.crt.
Add the certificate to an existing KeyStore (for example, DemoTrust.jks),
or create a new KeyStore (for example, keystore.jks)
and then add the certificate to it. To do this, run the following command:
keytool -import -trustcacerts -alias root -file JVMDCert.crt -keystore <name_of_existing_or_new_KeyStore>
If you specify an existing KeyStore name for the -keystore
parameter, you are prompted for the KeyStore password. If you specify a new KeyStore name for the -keystore
parameter, a new KeyStore is created with the default password changeit.
Log in to the WebLogic Server Administration Console.
From the Environment menu, select Servers.
Select the Managed Server on which the JVMD Agent is deployed, then select the Server Start tab.
For Arguments, specify the following arguments:
-Djavax.net.debug=ssl -Djavax.net.ssl.trustStore=<location_of_KeyStore>
-Djavax.net.ssl.trustStorePassword=<KeyStore_password>
Note:
The default password for the DemoTrust.jks KeyStore isDemoTrustKeyStorePassPhrase.
Restart the Managed Server.
Note:
When a WebLogic Managed Server running on a Sun or JRockit Java Virtual Machine (JVM) attempts to connect to an external resource using HTTPS, you may encounter the following exception:java.lang.ClassCastException: weblogic.net.http.SOAPHttpsURLConnection
This exception occurs because a HTTP API attempts to use an underlying WebLogic implementation, instead of using the Sun implementation. To avoid this exception, using the runtime argument, set the following flag:
-DUseSunHttpHandler=true
After installing JVMD Engine or JVMD Agent, follow the steps outlined in Oracle Enterprise Manager Cloud Control Basic Installation Guide.