From a high-level Mission Control perspective, the monitored JRockit JVM consists of:

As of JRockit Mission Control 2.0, the JRMC client is based on Eclipse RCP (Rich Client Platform) Technology. This provides a series of architectural advantages, such as an OSGi-based component model and being able to run JRockit Mission Control both as a standalone application and inside the Eclipse IDE.

The client-side of JRockit Mission Control is highly modular—new tools can easily be plugged in, and the tools themselves can be extended.

From a high-level Mission Control perspective, the Mission Control Client consists of:

The following figure shows a simplified breakdown of the plug-ins in the 4.0.0 version of JRockit Mission Control:

The rest of this chapter will focus on how to get JRockit Mission Control up and running and how to troubleshoot JRockit Mission Control. The different tools in JRockit Mission Control will be explained in detail in the chapters that follow.

In order to efficiently communicate about the JRockit Mission Control client, a common terminology is needed. The terms discussed here apply when running Mission Control standalone as well as inside Eclipse.

In an Eclipse RCP application, the main window is called the workbench. Inside the workbench there are two types of windows—views and editors. The editors occupy the center of the workbench—the editor area. The views are normally located around the editor area.

As shown in the following screenshot, the JVM Browser is the view to the left:

Views are normally used to show a specialized presentation of the contents of the selected editor, to manipulate the contents of an editor, or to launch new editors. Several views can be docked on each other by dragging a view on top of another view into the same view folder.

A certain configuration of which views to show, along with how they should be located, is called a perspective. In the screenshot, the Mission Control perspective is used, that shows the JVM Browser view and the Event Types view co-located in the same view folder to the left. Should you ever lose a view or mistakenly rearrange the views in a way you are not satisfied with, the perspective can easily be reset from the workbench menu (Window | Reset Perspective).

The editor currently opened in the editor area in the screenshot above is a JRockit Mission Control Console. It is being used to monitor a locally running application where the main class is called LoadAndDeadlock.

In Eclipse parlance, the JRockit tools are built as editors—any tool that is started will open up in the editor area. Several editors can be open at the same time. They will show as multiple tabs in the editor area. Several editors can also be viewed side-by-side by dragging an editor by the tab and docking it at any side of another editor. Views, such as the JVM Browser, cannot be docked into the editor area. They can, however, be docked to any side of the editor area.

To the left in the Management Console (in the editor area) is the tab group toolbar that selects tabs that are currently visible in the tab container at the bottom of the editor. A tab group toolbar is available in other JRockit Mission Control tools as well. In JRockit Mission Control 3.1, the General tab group, which is automatically selected when a Management Console is started, contains only a single tab—the Overview tab.

JRockit Mission Control exists both as a standalone executable and as a plug-in for the Eclipse IDE. The version of JRockit Mission Control included in the JRockit JDK is the standalone version.

Starting Mission Control in standalone mode is simple. Just run the executable named jrmc (or jrmc.exe on Windows) in the bin directory of the JRockit distribution.

For example:

JROCKIT_HOME/bin/jrmc

On Windows systems, JRockit Mission Control, when installed, will also be available in the start menu.

Once JRockit Mission Control has been started, an empty workspace (JRockit Mission Control 3.x), or a welcome screen (JRockit Mission Control 4.0) is displayed. If everything is correctly set up, JRockit Mission Control will automatically discover JVMs running on the local system. Even if there are no other Java applications running, the JRockit JVM used to execute the JRockit Mission Control client will be discovered and displayed as This Mission Control in the JVM Browser.

From the JVM Browser, the different JRockit Mission Control tools can be launched against a selected JVM.

Finding and monitoring locally running JVMs is simple and convenient—no additional setup is required. However, having the Mission Control client running on the same machine as the monitored JVM is usually a bad idea, especially in an enterprise configuration. The resources required by the client will be taken from whatever mission critical application executing on the JVM that is to be profiled. Of course, in a testing or development environment, this may be acceptable. Also, changes made to the settings, for instance the addition of an attribute to a graph in the JRockit Management Console, are stored on a per-connection basis. They are, however, not stored at all for local connections.

To add a user-defined connection, simply click on the Connectors folder and click on the Create Connection button.

The Connection Wizard, as shown in the previous screenshot, will open. Here, the details of the connection can be specified. It is usually enough to enter the Host and Port, but the following is worth noting:

There are some advantages to running JRockit Mission Control inside the Eclipse IDE, there are however no fundamental differences in functionality. One advantage, if the source code for the application being monitored is in the Eclipse workspace, is that it is possible to jump directly to the corresponding source whenever a class, method, or stack frame is shown in the JRockit Mission Control client.

If you are unfamiliar with Eclipse, or if you do not plan to use it for Java development, you can safely skip this section, as it assumes some familiarity with the Eclipse IDE.

In order to start JRockit Mission Control inside Eclipse, the JRockit Mission Control plug-ins from the JRockit Mission Control update site must first be installed. The latest version of the update site will be available from the JRockit Mission Control home page on Oracle Technology Network. At the time of writing, the JRockit Mission Control homepage is located at http://www.oracle.com/technology/products/jrockit/missioncontrol/index.html.

As that's a handful to remember, it can also be reached at http://www.tinyurl.com/missioncontrol.

Installation instructions can be found at the update site and will not be discussed in detail here. To fully take advantage of all of the features in the JRockit Mission Control plug-ins, Eclipse should be run on a JRockit JVM. Most of the functionality is available, even if Mission Control is running in an Eclipse instance executing on another JVM, but features such as local JVM discovery and some JRockit specific functionality in the Management Console will not work.

There are additional benefits of running Eclipse on JRockit. JRockit Real Time, discussed in Chapter 3, Adaptive Memory Management can be used to make any interactive application more responsive.

In the Eclipse home folder, there is a configuration file, eclipse.ini, that can be altered to change the command-line flags of the JVM running Eclipse. Here is an example eclipse.ini file that the authors use:

-showsplash
org.eclipse.platform
-framework
pluginsorg.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar
-vm
d:jrockitsR27.6.3_R27.6.3-16_1.5.0in
-vmargs
-Xms512m
-Xmx512m
-XgcPrio:deterministic
-XpauseTarget:20

The previous example is for Eclipse 3.4 and JRockit R27, but it is very similar in Eclipse 3.5 and JRockit R28. To make it work with R28, simply specify the path to the R28 JVM after the -vm argument, and keep everything after the -vmargs.

To start JRockit Mission Control once it is installed in Eclipse, the Mission Control perspective must be opened. There are two Mission Control perspectives available in 3.x—the Mission Control main perspective and the Mission Control Latency perspective. The latter is used to study JRA recordings containing latency data. In the 4.0 version of JRockit Mission Control, there is only one perspective optimized to work with all the tools.

As shown in the following screenshot, the Mission Control perspectives can be found in the Window | Open Perspective | Other... menu:

Once the Mission Control perspective has been opened, things will look pretty much the same as when using the standalone version of JRockit Mission Control. As mentioned, one benefit of running JRockit Mission Control from within Eclipse is the ability to open up the corresponding application source code from most places where JRockit Mission Control shows a class or method, as shown in the following screenshot:

To enable a JRockit JVM for remote management, the external management agent must be started. It can either be started with the -Xmanagement command-line switch, or JRCMD can be used. JRCMD is discussed in detail in Chapter 11.

The following example starts up a JRockit JVM with a simple test program and enables it for remote monitoring on port 4712. Authentication and SSL support for the connection are turned off.

JROCKIT_HOME/bin/java -Xmanagement:ssl=false,authenticate=false,port=4712 -cp . HelloJRMC

For now, let's ignore the security flags and focus on the port. Examples of how to set up JRockit Mission Control with security turned on will be shown in the section Running in a Secure Environment, later in this chapter.

As mentioned, the default management agent uses the JMX over RMI protocol for communication. This has been a source of some grief to people trying to establish connections through firewalls as RMI usually requires communication over an anonymous port. A full discussion on RMI is outside the scope of the book, but this is how it used to work in versions prior to R28:

In R28, things have improved. The RMI registry and the RMI server ports are the same by default, making firewall configuration much easier.

JROCKIT_HOME/bin/java -Xmanagement:ssl=false,authenticate=false,port=4712, autodiscovery=true -cp . HelloJRMC

-Dcom.oracle.management.autodiscovery.period=2500

The best way to ensure a secure environment with JRockit Mission Control is to first use standard networking techniques, such as firewalls, to ensure that only a very limited set of machines are allowed to even attempt a connection to the management agent. Setting up routers and firewalls is beyond the scope of this book.

For secure communication, the management agent should be configured to only allow SSL encrypted connections. The management agent can be configured to use SSL both for the RMI registry and the RMI server. For a secure environment, both should use SSL. By default, secure server authentication over SSL is enabled, but client authentication is not.

Following is an example of the options used to enable SSL on the server and the registry, as well as for enabling secure client authentication:

JROCKIT_HOMEinjava -Xmanagement:ssl=true,registry.ssl=true,port=4711 -Dcom.oracle.management.jmxremote.ssl.need.client.auth=true MyApp

For SSL to work, certificates must be set up. In most Java environments, a keystore is used to store the private keys, and a truststore to store the trusted certificates.

Next, authentication and roles need to be configured to ensure that only authorized entities have access to sensitive functionality. Access rights are controlled by the jmxremote.password and jmxremote.access files. These are normally placed in the directory JROCKIT_HOME/jre/lib/management/. The password file contains the passwords for the different roles, and the access file specifies the access rights of each role. A role must have an entry in both files in order to work.

To facilitate easy setup, there is a jmxremote.password template file included with the JRockit JRE. To get started with this template, copy the file JROCKIT_HOME/jre/lib/management/jmxremote.password.template to JROCKIT_HOME/jre/lib/management/jmxremote.password.

Following is an example of granting permission to create the JRockitConsole MBean to the control role (see the jmxremote.access file):

controlRole readwrite 
create oracle.jrockit.management.JRockitConsole

The JRockitConsole MBean will in turn initiate the rest of JMXMAPI.

In a multi-user environment, that is, in an environment where different users will use the same Java installation, the custom is to copy the jmxremote.password file to each user's home directory and use the com.sun.management.jmxremote.password.file system property to specify the location of the file.

As the password file contains unencrypted passwords, Java will rely on the file permissions of the underlying operating system to ensure that the file can only be read by the user executing the JVM. If an error is shown about the password file not being restricted, steps must be taken to ensure that the password file is only readable by the user that is executing the Java process. On a *NIX system, this can be done by executing something like chmod 600 <password file name> from a shell. On a Windows system, the process is slightly more complicated.

To top things off, all communication can be done over an encrypted SSH tunnel, instead of by opening an additional port in the firewall. Access to the SSH tunnel is commonly enabled through a port on localhost. The stub transmitted when a connection to the JMX agent is established normally contains the address of the computer to connect to. We want to trick the computer running the agent into transmitting a stub containing the loopback address or localhost instead. This can either be done by editing the hosts file, or by setting the java.rmi.server.hostname system property on startup. Both these techniques should be used with caution, as they may cause problems for other software running in the system and/or on the same JVM.

If you are having problems connecting to locally discovered JRockit JVMs, you should check:

If you are having problems connecting to an external management agent (usually, but not necessarily, one running on a remote machine) you should check:

While troubleshooting connections to the remote management agent, first make sure that the connection works with SSL and that authentication is turned off. If that works, make sure that all the steps in the Running in a Secure Environment section have been followed, that the certificate is valid, that the keystore password is correct, and that the password.properties file has been properly configured.

If the Management Console tells you that a certain MBean, for instance the Profiling MBean, cannot be found, it may be due to a misconfigured jmxremote.access file. To be able to initialize JMXMAPI, the user must have authorization to create the JRockitConsole MBean that, in turn, will initialize the rest of the JMXMAPI. See the Running in a Secure Environment section for more information.

Could not open Management Console for sthx6454:7094. java.rmi.ConnectException: Connection refused to host: 127.0.0.1; nested exception is: java.net.ConnectException: Connection refused: connect at sun.rmi.transport.tcp.TCPEndpoint.newSocket(TCPEndpoint.java:574) at sun.rmi.transport.tcp.TCPChannel.createConnection (TCPChannel.java:185)
at sun.rmi.transport.tcp.TCPChannel.newConnection(TCPChannel.java:171)
at sun.rmi.server.UnicastRef.invoke(UnicastRef.java:94)
at javax.management.remote.rmi.RMIServerImpl_Stub.newClient (Unknown Source)
at javax.management.remote.rmi.RMIConnector.getConnection (RMIConnector.java:2239)
at javax.management.remote.rmi.RMIConnector.connect (RMIConnector.java:271)
at javax.management.remote.rmi.RMIConnector.connect (RMIConnector.java:229)
at com.jrockit.console.rjmx.RJMXConnection.setupServer (RJMXConnection.java:504)