mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
408 lines
13 KiB
HTML
408 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
|
|
<head>
|
|
<title>Berkeley DB Java Edition MBeans and JConsole Plugin</title>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="docMain">
|
|
|
|
<center>
|
|
<h1>Monitoring and Debugging Berkeley DB Java Edition with JMX</h1>
|
|
</center>
|
|
|
|
<a href="#mbeans">Monitoring and Diagnostic MBeans</a><br>
|
|
<a href="#jconsole">Displaying Statistics Graphically With the JE
|
|
JConsole Plugin</a><br>
|
|
|
|
<!-- MBEANS --------------------------------------------- -->
|
|
<hr>
|
|
<h2><a name="mbeans">Monitoring and Diagnostic MBeans</a></h2>
|
|
|
|
<h3>Overview</h3>
|
|
<p>
|
|
Berkeley DB Java Edition provides monitoring and debugging support
|
|
through four JMX Dynamic MBeans. JEMonitor and RepJEMonitor make JE
|
|
statistics and basic administrative operations available, and are
|
|
mainly used for monitoring a JE application. JEDiagnostics and
|
|
RepJEDiagnostics makes JE logging output configurable dynamically, and
|
|
are mainly used for debugging.
|
|
</p>
|
|
<p>
|
|
A non-replicated (non-HA) JE Environment can only be accessed via
|
|
JEMonitor and JEDiagnostics, while a replicated JE Environment can
|
|
only be accessed via RepJEMonitor and RepJEDiagnostics.
|
|
</p>
|
|
<p>
|
|
The functionality provided by the JE MBeans can be accessed through
|
|
the standard MBean attribute/operation interface available through
|
|
JConsole or another management console. In addition, environment
|
|
statistics can be viewed and exported through the
|
|
<a href="#jconsole">JE JConsole Plugin</a>
|
|
|
|
|
|
<h3>Enabling MBeans in your JE Application</h3>
|
|
<p>To register and enable the MBeans for a JE application, set the
|
|
JEMonitor system property to true. For example:<br><br>
|
|
|
|
<code>
|
|
java -DJEMonitor=true -cp <je.jar> <JE application> </code>
|
|
|
|
|
|
<p>
|
|
Setting <code>-DJEMonitor=true</code> will register both the monitoring
|
|
and diagnostic MBeans for the application. For example, a non-HA
|
|
environment will register both JEMonitor and JEDiagnostics, while a
|
|
a replicated environment will register both RepJEMonitor and RepJEDiagnostics.
|
|
</p>
|
|
<h3>Attributes and Operations available through JEMonitor and RepJEMonitor</h3>
|
|
<p>
|
|
JEMonitor monitors a non-replicated JE application. RepJEMonitor
|
|
monitors a replicated JE application and provides all the attributes
|
|
and operations of JEMonitor, along with additional operations only
|
|
applicable for replicated environments.
|
|
</p>
|
|
<h4>Monitoring Attributes</h4>
|
|
<p>
|
|
JEMonitor and RepJEMonitor have the following attributes list:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img src="JEMonitor-attributes.JPG" alt="Monitor attributes"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<p>
|
|
Attributes names and values are listed in the area outlined in
|
|
<font color="red"><b>red</b></font>. Most of the attributes are
|
|
immutable and cannot be changed through JEMonitor, with the exception
|
|
of <code>cachePercent</code> and <code>cacheSize</code>. Detailed
|
|
information about the attributes can be obtained by clicking on the
|
|
attribute name in the list outlined in
|
|
<font color="blue"><b>blue</b></font>.
|
|
</p>
|
|
<h4>Monitoring Operations</h4>
|
|
<p>
|
|
JEMonitor provides the following operations, which can be invoked on
|
|
the monitored, running JE application:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="Monitor operations" src="JEMonitor-operations.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<p>
|
|
These operations mimic functionality available through the
|
|
com.sleepycat.je.Environment class. <code>getEnvConfig</code>
|
|
and <code>getEnvironmentStats</code> are of particular value for
|
|
obtaining information about the environment configuration, and current
|
|
statistics. More information about each operation is available through
|
|
a tool tip that displays when the mouse hovers over the operation button.
|
|
<p>
|
|
As stated above, RepJEMonitor provides two additional operations to monitor a
|
|
replicated JE application:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="Monitor operations" src="RepJEMonitor-operations.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<p>
|
|
The additional operations are outlined
|
|
in <font color="red"><b>red</b></font>.
|
|
<code>getReplicationStats</code> displays replication specific
|
|
statistics, while <code>dumpReplicationState</code> displays
|
|
information about the replication group composition, current node
|
|
state, etc.
|
|
|
|
<h3>JEDiagnostics and RepJEDiagnostics</h3>
|
|
<p>
|
|
JEDiagnostics and RepJEDiagnostics, currently have the same attributes
|
|
and operations list.
|
|
</p>
|
|
|
|
<h4>Diagnostic Attributes</h4>
|
|
<p>
|
|
JEDiagnostics and RepJEDiagnostics attribute are:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="Diagnostic attributes" src="JEDiagnostics-attributes.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<p>
|
|
Attributes names and values are listed in the area outlined in
|
|
<font color="red"><b>red</b></font>. These attributes manage the
|
|
output levels for ConsoleHandler, FileHandler and MemoryHandler and
|
|
let you change logging output for a running JE application. This is
|
|
useful when doing detailed debugging, as described
|
|
in <a href="../GettingStartedGuide/managelogging.html">Chapter 12 of
|
|
the Getting Started Guide.</a> Detailed information for each
|
|
attribute is listed in the
|
|
<font color="blue"><b>blue</b></font> area and can be displayed by
|
|
clicking on the attribute.
|
|
</p>
|
|
<h4>Diagnostic Operations</h4>
|
|
<p>
|
|
JEDiagnostics and RepJEDiagnostics currently support the same operations:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="Diagnostic operations" src="JEDiagnostics-operations.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
</p>
|
|
<p>
|
|
<code>resetLoggerLevel</code> allows you reset the level for a JE
|
|
logger, while
|
|
<code>pushMemoryHandler</code> lets you flush any logging output which
|
|
has been buffered in memory. Both are used only in debugging situations.
|
|
</p>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<!-- JConsole --------------------------------------------- -->
|
|
<hr>
|
|
<h2><a name="jconsole">Berkeley DB Java Edition JConsole Plugin</a></h2>
|
|
|
|
|
|
<h3><a name="overview">Overview</a></h3>
|
|
<p>
|
|
The BDB JE JConsole plugins let you monitor and graphically display
|
|
information from running JE applications using
|
|
the <code>jconsole</code> utility which is distributed with the
|
|
JDK. Two plugins jars are provided: one for monitoring non-HA JE
|
|
applications (<code>JE_HOME/lib/JEJConsole.jar</code>), and another
|
|
for monitoring JE HA applications
|
|
(<code>JE_HOME/lib/RepJEJConsole.jar</code>). The former
|
|
lets <code>jconsole</code> monitor and display <code>
|
|
EnvironmentStats</code> while the latter shows both
|
|
<code>EnvironmentStats</code>
|
|
and <code>ReplicatedEnvironmentStats</code>.
|
|
</p>
|
|
<p>
|
|
The plugins can:
|
|
<ul>
|
|
<li> Display stats from a running JE application,
|
|
<li> Optionally log those stats into a log file in csv format,
|
|
<li> Graph those stats so that you can directly see the changes,
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
The plugins are based on the JE MBeans described above and use the
|
|
MBean operations to periodically obtain statistics which are displayed
|
|
in a table or graph.
|
|
<code>JEJConsole</code> invokes
|
|
<code>JEMonitor.getEnvironmentStats</code>
|
|
while <code>RepJEJConsole</code> invokes
|
|
both <code>RepJEMonitor.getEnvironmentStats</code> and
|
|
<code>RepJEMonitor.getReplicationStats</code>.
|
|
Note that <code>JEJConsole</code> can be used to monitor both JE
|
|
non-replicated and replicated applications, but in the latter case
|
|
will not display the "JE Replicated Statistics" tab shown in the
|
|
second screen shot below.
|
|
</p>
|
|
<p>
|
|
See the javadoc
|
|
for <a
|
|
href="../java/com/sleepycat/je/EnvironmentStats.html">EnvironmentStats</a>
|
|
and <a
|
|
href="../java/com/sleepycat/je/rep/ReplicatedEnvironmentStats.html">ReplicatedEnvironmentStats</a>
|
|
for more information about the meaning of the statistics.
|
|
</p>
|
|
<p>
|
|
<br>
|
|
A screenshot of the <code>JEJConsole</code> plugin:
|
|
<br>
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="JEStats" src="JEStats-plugin.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
The <code>RepJEJConsole</code> plugin:
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center"><img alt="RepJEStats" src="RepJEStats-plugin.JPG"></td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
<h3>Using The Plugins</h3>
|
|
<p>
|
|
<code>jconsole</code> can only monitor applications that have
|
|
registered a <code>DynamicMBean</code>.
|
|
Both JE and JE HA will automatically register an appropriate
|
|
<code>DynamicMBean</code> when an <code>Environment</code> or
|
|
<code>ReplicatedEnvironment</code> is created, if the <code>JEMonitor</code>
|
|
system property is set to true (e.g. using <code>-DJEMonitor=true</code>
|
|
on the command line).
|
|
<p>
|
|
To use the JE and JE Replication plugins, invoke <code>jconsole</code>
|
|
with the <code>-pluginpath</code> option to specify one of the libraries.
|
|
For example:
|
|
<br><br>
|
|
<code>jconsole -pluginpath JE_HOME/lib/JEJConsole.jar</code><br><br>
|
|
or
|
|
<br><br>
|
|
<code>jconsole -pluginpath JE_HOME/lib/RepJEJConsole.jar</code><br><br>
|
|
</p>
|
|
<p>
|
|
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.
|
|
<p>
|
|
Note: There is a <a href="http://java.sun.com/performance/jvmstat/faq.html#4">known problem</a> 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.
|
|
<p> After connecting to the process, a <code>"JE Statistics"</code> tab will
|
|
be shown in <code>jconsole</code>. The tab will be named <code>"JE
|
|
Replicated Statistics"</code> when using the
|
|
<code>RepJEJConsole.jar</code> plugin. The tab provides various
|
|
options:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<i>Choose JE MBean</i>
|
|
<p>
|
|
A JE application may have more than one <code>Environment</code>, and
|
|
therefore multiple <code>DynamicMBeans</code>. The plugin lets you
|
|
select which <code>Environment</code> you want to look at with
|
|
the <code>"Choose JE MBean"</code> box:
|
|
<br><br>
|
|
<div align="center"><img alt="Choose MBean" src="Choose-MBean.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Set Collection Interval</i>
|
|
<p>
|
|
The default interval for collecting environment stats is 10 seconds.
|
|
You can change this by entering a new value in the
|
|
<code>"Collection interval (secs):"</code> field and then pressing the
|
|
Enter key:
|
|
<br><br>
|
|
<div align="center"><img alt="Graph" src="Interval-setting.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Display cumulative stats</i>
|
|
<p>
|
|
By default, statistics are reset after each collection period, and the
|
|
value displayed pertains only to the collection interval. For example,
|
|
if the collection interval is 10 seconds, the plugin will display
|
|
values for the first 10 seconds, the second 10 seconds, etc. You may
|
|
choose instead to display statistics in a cumulative way, so that the
|
|
displayed values accumulate as the application runs, instead of
|
|
resetting in each interval. To do so, click the
|
|
<code>"Display cumulative stats"</code> checkbox:
|
|
<br><br>
|
|
<div align="center"><img alt="Clear stats" src="Display-cumulative-stats.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Limit the Display to Non-Zero values</i>
|
|
<p>
|
|
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 <code>"Hide zero values"</code> checkbox:
|
|
<br><br>
|
|
<div align="center"><img alt="Non-zero" src="Non-zero.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Choose a File for Logging Stats</i>
|
|
<p>
|
|
You may specify the file to write selected stats to with
|
|
the <code>"Record Statistics To..."</code> button. Currently, only
|
|
CSV format is supported:
|
|
<br><br>
|
|
<div align="center"><img alt="save log" src="Save-log.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Start Recording</i>
|
|
<p>
|
|
You can begin recording stats to the selected file by pressing
|
|
the <code>"Start Recording"</code> button. While recording is enabled,
|
|
you can not change the recording interval, log file, or the specific
|
|
stats being logged:<br><br>
|
|
<div align="center"><img alt="start recording" src="Start-record.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Stop Recording</i>
|
|
<p>
|
|
You can stop recording stats by pressing the <code>"Stop
|
|
Recording"</code> button. You can only change the recording interval,
|
|
log file, or the specific stats being logged when recording is
|
|
stopped:
|
|
<br><br>
|
|
<div align="center"><img alt="stop recording" src="Stop-record.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Choose Stats Group to Display</i>
|
|
<p>
|
|
JE Environment stats are divided into several groups. You can specify
|
|
which groups to display by checking the appropriate groups:
|
|
<br><br>
|
|
<div align="center"><img alt="choose group" src="Choose-group.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Stop Logging a Stat</i>
|
|
<p>
|
|
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 <code>"Log This
|
|
Stat"</code>:
|
|
<br><br>
|
|
<div align="center"><img alt="unlog" src="Unlog-stat.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Graph a Stat</i>
|
|
<p>
|
|
You may graph a particular stat by right clicking on the stat and
|
|
selecting <code>"Graph This Stat"</code>. For example if you right-click
|
|
on <code>nMarkLNsProcessed</code> and select <code>Graph This Stat</code>...
|
|
<br><br>
|
|
<div align="center"><img alt="graph" src="Graph-stat.JPG"></div><br><br>
|
|
... then a new window with the dynamic graph will be displayed:
|
|
<br><br>
|
|
<div align="center"><img alt="show graph" src="Show-graph.JPG"></div>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Show tips</i>
|
|
<p>
|
|
Each stat has a mouse-over which describes its meaning. For example:
|
|
<br><br>
|
|
<div align="center"><img alt="show tips" src="Show-tips.JPG"></div>
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Please report bugs to the <a href="http://forums.oracle.com/forums/forum.jspa?forumID=273">Berkeley DB Java Edition OTN forum</a>.
|
|
</p>
|
|
</div></html>
|