Berkeley DB Java Edition
JConsole Plugin

Overview

The BDB JE JConsole plugins let you monitor running JE applications using the jconsole utility which is distributed with the JDK. Two plugins are provided: one for monitoring non-HA JE applications (JE_HOME/lib/JEJConsole.jar), and another for monitoring JE HA applications (JE_HOME/lib/RepJEJConsole.jar). The former allows jconsole to monitor and display EnvironmentStats and the latter shows both EnvironmentStats and ReplicatedEnvironmentStats.

The plugins can:

• Display stats from a running JE application,
• Optionally log those stats into a log file in csv format,
• Graph those stats so that you can directly see the changes,
• Change mutable parameters, and
• Invoke certain operations (e.g. force a checkpoint, run the cleaner cleaner, etc.) on the running Environment.

The JEJConsole.jar can be used to monitor both JE non-HA and JE HA applications. In the latter case it will not show the "JE Replicated Statistics" tab shown in the second screen shot above. See the javadoc for EnvironmentStats and ReplicatedEnvironmentStats for more information about the meaning of the statistics.

Here are two sample screen shots of jconsole running the two plugins.

With the JEJConsole.jar plugin:



With the RepJEJConsole.jar plugin:

Using The Plugins

jconsole can only monitor applications that have registered a DynamicMBean. Both JE and JE HA will automatically register an appropriate DynamicMBean when an Environment or ReplicatedEnvironment is created, if the JEMonitor system property is set to true (e.g. using -DJEMonitor=true on the command line).

To use the JE and JE Replication plugins, invoke jconsole with the -pluginpath option to specify one of the libraries. For example:

    jconsole -pluginpath JE_HOME/lib/JEJConsole.jar

or

    jconsole -pluginpath JE_HOME/lib/RepJEJConsole.jar

When the plugin starts up, a menu will appear which lets you choose the process to monitor. Your JE application should appear if you have set -DJEMonitor=true. There is a known problem with discovering Java processes on Windows platforms when the temporary directory is on a FAT type file system. In that case, a Java application may need to set -XX:+PerfBypassFileSystemCheck on the Java command line in order for the process to appear on the connection menu.

After connecting to the process, a "JE Statistics" tab will be shown in jconsole. The tab will be named "JE Replicated Statistics" when using the RepJEJConsole.jar plugin. The tab provides various options:

• Choose JE MBean

  A JE application may have more than one Environment, and therefore multiple DynamicMBeans. The plugin lets you select which Environment you want to look at with the "Choose JE MBean" box:
  
  

  

• Clear Stats

  Press the "Clear Stats" button to clear all the stats for the current DynamicMBean:
  
  

  

• Limit the Display to Non-Zero values

  JE provides numerous stats. Depending on your application, some of them may be 0 and therefore irrelevant for analyzing performance. You can hide these stats by clicking the "Only display non-zero values" checkbox:
  
  

  

• Graph Settings

  The default graphing interval is 10 seconds. You can change this by entering a new value in the "Graphing interval (secs):" field and then pressing the Enter key:
  
  

  

• Set Recording Interval

  The default recording interval is 10 seconds. You can change this by entering a new recording interval in the text field labeled "Recording Interval (secs):" and then pressing the "Start Recording" button:
  
  

  

• Choose a File for Logging Stats

  You may specify the file to write selected stats to with the "Record Statistics To..." button. Currently, only CSV format is supported:
  
  

  

• Start Recording

  You can begin recording stats to the selected file by pressing the "Start Recording" button. While recording is enabled, you can not change the recording interval, log file, or the specific stats being logged:
  
  

  

• Stop Recording

  You can stop recording stats by pressing the "Stop Recording" button. You can only change the recording interval, log file, or the specific stats being logged when recording is stopped:
  
  

  

• Choose Stats Group to Display

  JE Environment stats are divided into several groups. You can specify which groups to display by checking the appropriate groups:
  
  

  

• Stop Logging a Stat

  All stats are logged by default. If you don't want to log a particular stat, you can right click on that stat, and uncheck "Log This Stat":
  
  

  

• Graph a Stat

  You may graph a particular stat by right clicking on the stat and selecting "Graph This Stat". For example if you right-click on nMarkLNsProcessed and select Graph This Stat...
  
  

  
  
  
  ... then a new window with the dynamic graph will be displayed:
  
  
  

• Show tips

  Each stat has a mouse-over which describes its meaning. For example:
  
  

  

• Change mutable parameters

  Under the normal "MBeans" tab (you do not need to specify the -pluginpath argument to jconsole to see this tab), there is a JE MBean for each registered Environment which starts with "com.sleepycat.je.jmx". If you click Attributes, you will get a list of mutable parameters and you can change their value:
  
  

  

• Invoke Utility Operations

  Clicking on Operations under an MBean will display a set of utility operations (e.g. cleanLog, evictMemory, etc.) which can be invoked on the Environment:
  
  

  

Please report bugs to the Berkeley DB Java Edition OTN forum.