Using JConsole to access the Derby MBeans

JConsole is a graphical JMX-compliant tool that is available in recent versions of the Oracle JDKs. JConsole enables you to monitor and manage Java applications and virtual machines on a local or remote machine.

You may use JConsole from JDK 6 or later even if you are running Derby using an earlier version of the JDK (or just the JRE). (You could also use JConsole from JDK 5 if you are running Derby using JDK 6 or later.) It is recommended that you use the newest version possible. More information about JConsole is available in the OpenJDK project at http://openjdk.java.net/tools/svc/jconsole/index.html.

Starting JConsole and connecting to Derby

In the Oracle JDK, the JConsole binary is available in JDK_HOME/bin, where JDK_HOME is the directory in which the JDK is installed. To start JConsole, use the jconsole command, as in the following example on a UNIX system:

/usr/local/java/jdk1.7.0/bin/jconsole

If you did not disable SSL when booting the managed JVM, you probably have to provide a truststore containing the server's SSL certificate to be able to establish JMX connections. If SSL client authentication is enabled, a keystore must be configured as well (see Enabling remote JMX with password authentication and SSL for details). The following example shows how to start JConsole with SSL client and server authentication:

jconsole -J-Djavax.net.ssl.trustStore=/home/user/.truststoreForClient
-J-Djavax.net.ssl.trustStorePassword=myTruststorePassword
-J-Djavax.net.ssl.keyStore=/home/user/.keystoreForClient
-J-Djavax.net.ssl.keyStorePassword=myKeyStorePassword

A graphical user interface (GUI) appears. For additional startup options, refer to the JConsole documentation. Once the GUI starts, you are presented with a list of the JVMs that are accessible on the local host. Locate the JVM that is running Derby and connect to it.

To connect to a JVM on a remote host, you will need to supply the host name and port number, or a JMX service URL, instead.

If you cannot find the Derby JVM running on the local host, make sure you are running JConsole as the same user as the Derby JVM, or as a different user with sufficient file system permissions. If you are using Java SE 5, make sure you have enabled JMX. When you use Java SE 6 or later, local JMX access is enabled by default.

Accessing MBeans

Once you have connected to a JVM via JConsole, the JVM's MBeans should be available on a separate tab in the internal JConsole window. Under the domain org.apache.derby you should see a list of MBeans. Browse the MBeans and their attributes and operations by navigating the hierarchy presented.

Another useful JConsole feature is that you can view dynamic data represented as JMX attributes in graph form. To view these graphs, double-click an attribute value that is a number.

Related reference
Introduction to the Derby MBeans
Enabling and disabling JMX
Using custom Java code to access the Derby MBeans
Troubleshooting JMX connection issues