HBASE-5264 Add 0.92.0 upgrade guide

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

src/docbkx/performance.xml

@@ -105,7 +105,7 @@
       <section xml:id="gcpause">
         <title>Long GC pauses</title>
 
-        <para>In his presentation, <link
+        <para xml:id="mslab">In his presentation, <link
         xlink:href="http://www.slideshare.net/cloudera/hbase-hug-presentation">Avoiding
         Full GCs with MemStore-Local Allocation Buffers</link>, Todd Lipcon
         describes two cases of stop-the-world garbage collections common in
@@ -115,7 +115,8 @@
         <code>-XX:CMSInitiatingOccupancyFraction</code> and setting it down
         from defaults. Start at 60 or 70 percent (The lower you bring down the
         threshold, the more GCing is done, the more CPU used). To address the
-        second fragmentation issue, Todd added an experimental facility that
+        second fragmentation issue, Todd added an experimental facility,
+        <indexterm><primary>MSLAB</primary></indexterm>, that
         must be explicitly enabled in HBase 0.90.x (Its defaulted to be on in
         0.92.x HBase). See <code>hbase.hregion.memstore.mslab.enabled</code>
         to true in your <classname>Configuration</classname>. See the cited

src/docbkx/upgrading.xml

@@ -70,4 +70,132 @@
 
           </para>
           </section>
+    <section xml:id="upgrade0.92">
+      <title>Upgrading from 0.90.x to 0.92.x</title>
+      <subtitle>Upgrade Guide</subtitle>
+<para>You will find that 0.92.0 runs a little differently to 0.90.x releases.  Here are a few things to watch out for upgrading from 0.90.x to 0.92.0.
+<note><title>tl;dr</title>
+<para>
+If you've not patience, here are the important things to know upgrading.
+<orderedlist>
+<listitem>Once you upgrade, you can’t go back.
+</listitem>
+<listitem>
+MSLAB is on by default. Watch that heap usage if you have a lot of regions.
+</listitem>
+<listitem>
+Distributed splitting is on by defaul.  It should make region server failover faster.
+</listitem>
+<listitem>
+There’s a separate tarball for security.
+</listitem>
+<listitem>
+If -XX:MaxDirectMemorySize is set in your hbase-env.sh, it’s going to enable the experimental off-heap cache (You may not want this).
+</listitem>
+</orderedlist>
+</para>
+</note>
+</para>
+
+<section>
+<title>You can’t go back!
+</title>
+<para>To move to 0.92.0, all you need to do is shutdown your cluster, replace your hbase 0.90.x with hbase 0.92.0 binaries (be sure you clear out all 0.90.x instances) and restart (You cannot do a rolling restart from 0.90.x to 0.92.x -- you must restart).
+On startup, the <varname>.META.</varname> table content is rewritten removing the table schema from the <varname>info:regioninfo</varname> column.
+Also, any flushes done post first startup will write out data in the new 0.92.0 file format, <link xlink:href="http://hbase.apache.org/book.html#hfilev2">HFile V2</link>.
+This means you cannot go back to 0.90.x once you’ve started HBase 0.92.0 over your HBase data directory.
+</para>
+</section>
+
+<section>
+<title>MSLAB is ON by default
+</title>
+<para>In 0.92.0, the <link xlink:href="http://hbase.apache.org/book.html#hbase.hregion.memstore.mslab.enabled">hbase.hregion.memstore.mslab.enabled</link> flag is set to true
+(See <xref linkend="mslab" />).  In 0.90.x it was <constant>false</constant>.  When it is enabled, memstores will step allocate memory in MSLAB 2MB chunks even if the
+memstore has zero or just a few small elements.  This is fine usually but if you had lots of regions per regionserver in a 0.90.x cluster (and MSLAB was off),
+you may find yourself OOME'ing on upgrade because the <mathphrase>thousands of regions * number of column families * 2MB MSLAB (at a minimum)</mathphrase>
+puts your heap over the top.  Set <varname>hbase.hregion.memstore.mslab.enabled</varname> to
+<constant>false</constant> or set the MSLAB size down from 2MB by setting <varname>hbase.hregion.memstore.mslab.chunksize</varname> to something less.
+</para>
+</section>
+
+<section><title>Distributed splitting is on by default
+</title>
+<para>Previous, WAL logs on crash were split by the Master alone.  In 0.92.0, log splitting is done by the cluster (See See “HBASE-1364 [performance] Distributed splitting of regionserver commit logs”).  This should cut down significantly on the amount of time it takes splitting logs and getting regions back online again.
+</para>
+</section>
+
+<section><title>Memory accounting is different now
+</title>
+<para>In 0.92.0, <xref linkend="hfilev2" /> indices and bloom filters take up residence in the same LRU used caching blocks that come from the filesystem.
+In 0.90.x, the HFile v1 indices lived outside of the LRU so they took up space even if the index was on a ‘cold’ file, one that wasn’t being actively used.  With the indices now in the LRU, you may find you
+have less space for block caching.  Adjust your block cache accordingly.  See the <xref linkend="block.cache" /> for more detail.
+The block size default size has been changed in 0.92.0 from 0.2 (20 percent of heap) to 0.25.
+</para>
+</section>
+
+
+<section><title>On the Hadoop version to use
+</title>
+<para>Run 0.92.0 on Hadoop 1.0.x (or CDH3u3 when it ships).  The performance benefits are worth making the move.  Otherwise, our Hadoop prescription is as it has been; you need an Hadoop that supports a working sync.  See <xref linkend="hadoop" />.
+</para>
+
+<para>If running on Hadoop 1.0.x (or CDH3u3), enable local read.  See <link xlink:href="http://files.meetup.com/1350427/hug_ebay_jdcryans.pdf">Practical Caching</link> presentation for ruminations on the performance benefits ‘going local’ (and for how to enable local reads).
+</para>
+</section>
+<section><title>HBase 0.92.0 ships with ZooKeeper 3.4.2
+</title>
+<para>If you can, upgrade your zookeeper.  If you can’t, 3.4.2 clients should work against 3.3.X ensembles (HBase makes use of 3.4.2 API).
+</para>
+</section>
+<section>
+<title>Online alter is off by default
+</title>
+<para>In 0.92.0, we’ve added an experimental online schema alter facility  (See <xref linkend="hbase.online.schema.update.enable" />).  Its off by default.  Enable it at your own risk.  Online alter and splitting tables do not play well together so be sure your cluster quiescent using this feature (for now).
+</para>
+</section>
+<section>
+<title>WebUI
+</title>
+<para>The webui has had a few additions made in 0.92.0.  It now shows a list of the regions currently transitioning, recent compactions/flushes, and a process list of running processes (usually empty if all is well and requests are being handled promptly).  Other additions including requests by region, a debugging servlet dump, etc.
+</para>
+</section>
+<section>
+<title>Security tarball
+</title>
+<para>We now ship with two tarballs; secure and insecure HBase.  Documentation on how to setup a secure HBase is on the way.
+</para>
+</section>
+
+<section><title>Experimental off-heap cache
+</title>
+<para>
+A new cache was contributed to 0.92.0 to act as a solution between using the “on-heap” cache which is the current LRU cache the region servers have and the operating system cache which is out of our control. 
+To enable, set “-XX:MaxDirectMemorySize” in hbase-env.sh to the value that you want to dedicate to that cache. This should only be set for servers and not for clients; in fact, if you already had to add that configuration on for any reason and still use it today it’s going to enable this feature. Use at your own risk.
+See this blog post for additional information on this new experimental feature: http://www.cloudera.com/blog/2012/01/caching-in-hbase-slabcache/
+</para>
+</section>
+
+<section><title>Changes in HBase replication
+</title>
+<para>0.92.0 adds two new features: multi-slave and multi-master replication. The way to enable this is the same as adding a new peer, so in order to have multi-master you would just run add_peer for each cluster that acts as a master to the other slave clusters. Collisions are handled at the timestamp level which may or may not be what you want, this needs to be evaluated on a per use case basis. Replication is still experimental in 0.92 and is disabled by default, run it at your own risk.
+</para>
+</section>
+
+
+<section><title>RegionServer now aborts if OOME
+</title>
+<para>If an OOME, we now have the JVM kill -9 the regionserver process so it goes down fast.  Previous, a RegionServer might stick around after incurring an OOME limping along in some wounded state.  To disable this facility, and recommend you leave it in place, you’d need to edit the bin/hbase file.  Look for the addition of the -XX:OnOutOfMemoryError="kill -9 %p" arguments (See [HBASE-4769] - ‘Abort RegionServer Immediately on OOME’)
+</para>
+</section>
+
+
+<section><title>HFile V2 and the “Bigger, Fewer” Tendency
+</title>
+<para>0.92.0 stores data in a new format, <xref linkend="hfilev2" />.   As HBase runs, it will move all your data from HFile v1 to HFile v2 format.  This auto-migration will run in the background as flushes and compactions run.
+HFile V2 allows HBase run with larger regions/files.  In fact, we encourage that all HBasers going forward tend toward Facebook axiom #1, run with larger, fewer regions.
+If you have lots of regions now -- more than 100s per host -- you should look into setting your region size up after you move to 0.92.0 (In 0.92.0, default size is not 1G, up from 256M), and then running online merge tool (See “HBASE-1621 merge tool should work on online cluster, but disabled table”).
+</para>
+</section>
+    </section>
     </chapter>