HBASE-949 Add an HBase Manual

git-svn-id: https://svn.apache.org/repos/asf/hadoop/hbase/trunk@709033 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -80,6 +80,7 @@ Release 0.19.0 - Unreleased
    HBASE-960   REST interface: more generic column family configure and also
                get Rows using offset and limit (Sishen Freecity via Stack)
    HBASE-817   Hbase/Shell Truncate
+   HBASE-949   Add an HBase Manual
     
   NEW FEATURES
    HBASE-875   Use MurmurHash instead of JenkinsHash [in bloomfilters]

build.xml

@@ -338,7 +338,9 @@
   <!-- Doc                                                                -->
   <!-- ================================================================== -->
   <target name="docs" depends="forrest.check" description="Generate forrest-based documentation. To use, specify -Dforrest.home=&lt;base of Apache Forrest installation&gt; on the command line." if="forrest.home">
-    <exec dir="${docs.src}" executable="${forrest.home}/bin/forrest" failonerror="true" />
+    <exec dir="${docs.src}" executable="${forrest.home}/bin/forrest" failonerror="true" >
+      <env key="JAVA_HOME" value="${java5.home}"/>
+    </exec>
     <copy todir="${docs.dir}">
       <fileset dir="${docs.src}/build/site/" />
     </copy>
@@ -346,10 +348,14 @@
            includes="hadoop-default.xml" style="conf/configuration.xsl"/>
   </target>
 
-  <target name="forrest.check" unless="forrest.home">
+  <target name="forrest.check" unless="forrest.home" depends="java5.check">
     <fail message="'forrest.home' is not defined. Please pass -Dforrest.home=&lt;base of Apache Forrest installation&gt; to Ant on the command-line." />
   </target>
 
+  <target name="java5.check" unless="java5.home">
+    <fail message="'java5.home' is not defined.  Forrest requires Java 5.  Please pass -Djava5.home=&lt;base of Java 5 distribution&gt; to Ant on the command-line." />
+  </target>
+
   <!-- Javadoc -->
   <target name="javadoc" description="Generate javadoc">
     <mkdir dir="${build.javadoc}"/>

docs/index.html

@@ -114,6 +114,9 @@ document.write("Last Published: " + document.lastModified);
 <a href="api/index.html">API Docs</a>
 </div>
 <div class="menuitem">
+<a href="metrics.html">HBase Metrics</a>
+</div>
+<div class="menuitem">
 <a href="http://wiki.apache.org/hadoop/Hbase">Wiki</a>
 </div>
 <div class="menuitem">

docs/linkmap.html

@@ -114,6 +114,9 @@ document.write("Last Published: " + document.lastModified);
 <a href="api/index.html">API Docs</a>
 </div>
 <div class="menuitem">
+<a href="metrics.html">HBase Metrics</a>
+</div>
+<div class="menuitem">
 <a href="http://wiki.apache.org/hadoop/Hbase">Wiki</a>
 </div>
 <div class="menuitem">
@@ -177,6 +180,12 @@ document.write("Last Published: " + document.lastModified);
 </li>
 </ul>
     
+<ul>
+<li>
+<a href="metrics.html">HBase Metrics</a>&nbsp;&nbsp;___________________&nbsp;&nbsp;<em>api</em>
+</li>
+</ul>
+    
 <ul>
 <li>
 <a href="http://wiki.apache.org/hadoop/Hbase">Wiki</a>&nbsp;&nbsp;___________________&nbsp;&nbsp;<em>wiki</em>

docs/linkmap.pdf

@@ -5,10 +5,10 @@
 /Producer (FOP 0.20.5) >>
 endobj
 5 0 obj
-<< /Length 666 /Filter [ /ASCII85Decode /FlateDecode ]
+<< /Length 695 /Filter [ /ASCII85Decode /FlateDecode ]
  >>
 stream
-GatUq?#Q2d'Sc)P'u!?plIj08E1+/X51F;IK%,^$W]Vtl<IuYZNV;h]7h_@k'T"/7ic?[-pGr$/>fGQtPn+.S#fN-dg:tQn@,k[GRP+kBS)Y2KT8+QGJ_uBn1@bKOOs"RQ(:U;gg546)@duC$k&k:Vf=EZA0_GVE"6/d/1BX$:c3$-D"HXk^gVmAs[h>d5=h%sMLT^i/cs-3RZ^!F>oWHE7EAFqB,>k7sPB![=;sb7)Y9Z68it6GM_'j\BIisEX;_1E*CLJ2KHE?h@8@<>N@Aku2I/>o1ni).G^bCYe:pR9E*.mYqJmq9t!;dDh^A&Y<m!$^c$);Ss(X8k,O6.@W3dGX"@,<4IBmrS!I_Nng7ENG`.cs)?o:^q'M,'0V!lGVU0@C\;D!Vp@)c7K@c6dCg:_`GnB78:"!2ZB-&(DK\o%,f.H.+@dgil?$'cra!;GGV[C3St]h7\,4Z[mLGY(#TqVKaL.4U\=Ph$7q)nOu&@e$S:ZK]\%dq-]EBWnP[(^nA7".31J3]jg`_kLb.LRR;;J@2-M-!STOY8/S9NaLjV'Wbj5]R6NTpO9Ce.4U!VG,L/R86Pf;Pf=Ll]WQj#HDXft/[LkeRFILG)Bede/,]:9GR5p)GafP-K8A"0q3fiC5%6Et3M.PLJ!]#J<o`*a8X@3~>
+GatUqd;I\]'Sc)T'O7LOAUjg9QV"fjRp'Z//G3JC.V=kIeM4$t)XZp)lmCXiDQ4tE&e<"_ruK#99[_kB1^&Iu"O_RGlsCMNYQupJbnl#Nc>e_LaCC=7_!fZE)0l688JF*6UK^_^YJf-hUuH=OXm<M:?g6"[daT)k%nM1,c4"+/3VVlB'L@amB9t5ND'bQT)>Re$L2R3#crkO%Z]m)`oP.Z&j3?)rO$oC_:<'W?9sr*eVNPoENX+3>!gED=rK.Zb6*_?\f>9M!FI2BSaL/Ie0[q"*^&RF&q)^kT@@/=90A5GH$phCWTGS<k_nO(!9E&+-RoQe5_C/]]MAFXE6h?:XSUGSs0Xh^S1qs-+5@8!pWoWka.Mfl4o=g":M]O*1"NCOShkW!,>du"81SQW[5FJl-Td8TFc[)L7"I-p"/#WQsnZVBko"*Y=;r8m8GIV94f'548Vs^o5d+qA`m8`A@1mL*(d9\A_oGp/M8D.Br4K)n81/Nc:e[M[90cjQ+"$G'&rL#XZpftHOVa5^7%do!"H?F2-C3.B!2N<O@^15P>[L[d\K9s#r[?iU;&W@R"XYYQ^JP(N>E$%bih]pDBY4'=TU<ID"QnatI#*KP'W3a%_l[P1'/<+FYO+^pX&VOVs%kbOJ3*qNeO(WcV[\E>)VKu2'm0sH:a,7_;X`s0OZ>T(ZR7!>;IqK&8'E~>
 endstream
 endobj
 6 0 obj
@@ -72,17 +72,17 @@ endobj
 xref
 0 12
 0000000000 65535 f 
-0000001489 00000 n 
-0000001547 00000 n 
-0000001597 00000 n 
+0000001518 00000 n 
+0000001576 00000 n 
+0000001626 00000 n 
 0000000015 00000 n 
 0000000071 00000 n 
-0000000828 00000 n 
-0000000934 00000 n 
-0000001046 00000 n 
-0000001155 00000 n 
-0000001265 00000 n 
-0000001373 00000 n 
+0000000857 00000 n 
+0000000963 00000 n 
+0000001075 00000 n 
+0000001184 00000 n 
+0000001294 00000 n 
+0000001402 00000 n 
 trailer
 <<
 /Size 12
@@ -90,5 +90,5 @@ trailer
 /Info 4 0 R
 >>
 startxref
-1717
+1746
 %%EOF

src/docs/src/documentation/content/xdocs/metrics.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<!--
+  Copyright 2002-2008 The Apache Software Foundation
+
+  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.
+-->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+          "http://forrest.apache.org/dtd/document-v20.dtd">
+
+
+<document>
+
+  <header>
+    <title> 
+      HBase Metrics
+    </title>
+  </header>
+
+  <body>
+    <section>
+      <title> Introduction </title>
+      <p>
+      HBase emits Hadoop <a href="http://hadoop.apache.org/core/docs/current/api/org/apache/hadoop/metrics/package-summary.html">metrics</a>.
+      </p>
+      </section>
+      <section>
+        <title>HOWTO</title>
+      <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 memcache 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>
+  </body>
+</document>

src/docs/src/documentation/content/xdocs/site.xml

@@ -35,6 +35,7 @@ See http://forrest.apache.org/docs/linking.html for more info.
     <overview  label="Overview"           href="index.html" />
     <started   label="Getting Started"    href="ext:api/started" />
     <api       label="API Docs"           href="ext:api/index" />
+    <api       label="HBase Metrics"      href="metrics.html" />
     <wiki      label="Wiki"               href="ext:wiki" />
     <faq       label="FAQ"                href="ext:faq" />
     <lists     label="Mailing Lists"      href="ext:lists" />