<?xml version="1.0" encoding="UTF-8"?>
<!--

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
  <properties>
    <title> 
      Apache HBase (TM) Metrics
    </title>
  </properties>

  <body>
    <section name="Introduction">
      <p>
      Apache HBase (TM) emits Hadoop <a href="http://hadoop.apache.org/core/docs/current/api/org/apache/hadoop/metrics/package-summary.html">metrics</a>.
      </p>
      </section>
      <section name="Setup">
      <p>First read up on Hadoop <a href="http://hadoop.apache.org/core/docs/current/api/org/apache/hadoop/metrics/package-summary.html">metrics</a>.
      If you are using ganglia, the <a href="http://wiki.apache.org/hadoop/GangliaMetrics">GangliaMetrics</a>
      wiki page is useful read.</p>
      <p>To have HBase emit metrics, edit <code>$HBASE_HOME/conf/hadoop-metrics.properties</code>
      and enable metric 'contexts' per plugin.  As of this writing, hadoop supports
      <strong>file</strong> and <strong>ganglia</strong> plugins.
      Yes, the hbase metrics files is named hadoop-metrics rather than
      <em>hbase-metrics</em> because currently at least the hadoop metrics system has the
      properties filename hardcoded. Per metrics <em>context</em>,
      comment out the NullContext and enable one or more plugins instead.
      </p>
      <p>
      If you enable the <em>hbase</em> context, on regionservers you'll see total requests since last
      metric emission, count of regions and storefiles as well as a count of memstore size.
      On the master, you'll see a count of the cluster's requests.
      </p>
      <p>
      Enabling the <em>rpc</em> context is good if you are interested in seeing
      metrics on each hbase rpc method invocation (counts and time taken).
      </p>
      <p>
      The <em>jvm</em> context is
      useful for long-term stats on running hbase jvms -- memory used, thread counts, etc.
      As of this writing, if more than one jvm is running emitting metrics, at least
      in ganglia, the stats are aggregated rather than reported per instance.
      </p>
    </section>

    <section name="Using with JMX">
      <p>
      In addition to the standard output contexts supported by the Hadoop 
      metrics package, you can also export HBase metrics via Java Management 
      Extensions (JMX).  This will allow viewing HBase stats in JConsole or 
      any other JMX client.
      </p>
      <section name="Enable HBase stats collection">
      <p>
      To enable JMX support in HBase, first edit 
      <code>$HBASE_HOME/conf/hadoop-metrics.properties</code> to support 
      metrics refreshing. (If you've running 0.94.1 and above, or have already configured 
      <code>hadoop-metrics.properties</code> for another output context,
      you can skip this step).
      </p>
      <source>
# Configuration of the "hbase" context for null
hbase.class=org.apache.hadoop.metrics.spi.NullContextWithUpdateThread
hbase.period=60

# Configuration of the "jvm" context for null
jvm.class=org.apache.hadoop.metrics.spi.NullContextWithUpdateThread
jvm.period=60

# Configuration of the "rpc" context for null
rpc.class=org.apache.hadoop.metrics.spi.NullContextWithUpdateThread
rpc.period=60
      </source>
      </section>
      <section name="Setup JMX remote access">
      <p>
      For remote access, you will need to configure JMX remote passwords 
      and access profiles.  Create the files:
      </p>
      <dl>
        <dt><code>$HBASE_HOME/conf/jmxremote.passwd</code> (set permissions 
        to 600)</dt>
        <dd>
        <source>
monitorRole monitorpass
controlRole controlpass
        </source>
        </dd>
        
        <dt><code>$HBASE_HOME/conf/jmxremote.access</code></dt>
        <dd>
        <source>
monitorRole readonly
controlRole readwrite
        </source>
        </dd>
      </dl>
      </section>
      <section name="Configure JMX in HBase startup">
      <p>
      Finally, edit the <code>$HBASE_HOME/conf/hbase-env.sh</code>
      script to add JMX support: 
      </p>
      <dl>
        <dt><code>$HBASE_HOME/conf/hbase-env.sh</code></dt>
        <dd>
        <p>Add the lines:</p>
        <source>
HBASE_JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.ssl=false"
HBASE_JMX_OPTS="$HBASE_JMX_OPTS -Dcom.sun.management.jmxremote.password.file=$HBASE_HOME/conf/jmxremote.passwd"
HBASE_JMX_OPTS="$HBASE_JMX_OPTS -Dcom.sun.management.jmxremote.access.file=$HBASE_HOME/conf/jmxremote.access"

export HBASE_MASTER_OPTS="$HBASE_JMX_OPTS -Dcom.sun.management.jmxremote.port=10101"
export HBASE_REGIONSERVER_OPTS="$HBASE_JMX_OPTS -Dcom.sun.management.jmxremote.port=10102"
        </source>
        </dd>
      </dl>
      <p>
      After restarting the processes you want to monitor, you should now be 
      able to run JConsole (included with the JDK since JDK 5.0) to view 
      the statistics via JMX.  HBase MBeans are exported under the 
      <strong><code>hadoop</code></strong> domain in JMX.
      </p>
      </section>
      <section name="Understanding HBase Metrics">
      <p>
      For more information on understanding HBase metrics, see the <a href="book.html#hbase_metrics">metrics section</a> in the Apache HBase Reference Guide. 
      </p>
      </section>
    </section>
  </body>
</document>
