svn commit: r1388337 - /hbase/trunk/src/docbkx/book.xml

[st...@apache.org]

Author: stack
Date: Fri Sep 21 06:23:03 2012
New Revision: 1388337

URL: http://svn.apache.org/viewvc?rev=1388337&view=rev
Log:
HBASE-6524 Hooks for hbase tracing; add documentation as an appendix

Modified:
    hbase/trunk/src/docbkx/book.xml

Modified: hbase/trunk/src/docbkx/book.xml
URL: http://svn.apache.org/viewvc/hbase/trunk/src/docbkx/book.xml?rev=1388337&r1=1388336&r2=1388337&view=diff
==============================================================================
--- hbase/trunk/src/docbkx/book.xml (original)
+++ hbase/trunk/src/docbkx/book.xml Fri Sep 21 06:23:03 2012
@@ -3583,6 +3583,67 @@ Comparator class used for Bloom filter k
        </section>
   </appendix>
 
+  <appendix xml:id="tracing" ><title>Enabling Dapper-like Tracing in HBase</title>
+<para><link xlink:href="https://issues.apache.org/jira/browse/HBASE-6449">HBASE-6449</link> added support
+for tracing requests through HBase, using the open source tracing library,
+<link xlink:href="http://github.com/cloudera/htrace">HTrace</link>. Setting up tracing is quite simple,
+however it currently requires some very minor changes to your client code (it would not be very difficult to remove this requirement). 
+</para>
+<section xml:id="tracing.spanreceivers"><title>SpanReceivers</title>
+<para>The tracing system works by collecting information in structs called ‘Spans’.
+It is up to you to choose how you want to receive this information by implementing the
+<classname>SpanReceiver</classname> interface, which defines one method: 
+<programlisting>public void receiveSpan(Span span);</programlisting>
+This method serves as a callback whenever a span is completed. HTrace allows you to use
+as many SpanReceivers as you want so you can easily send trace information to multiple destinations. 
+</para>
+
+<para>Configure what SpanReceivers you’d like to use by putting a comma separated list of the
+fully-qualified class name of classes implementing <classname>SpanReceiver</classname> in
+<filename>hbase-site.xml</filename> property: <varname>hbase.trace.spanreceiver.classes</varname>. 
+</para>
+
+<para>HBase includes a <classname>HBaseLocalFileSpanReceiver</classname> that writes all span
+information to local files in a JSON-based format. The <classname>HBaseLocalFileSpanReceiver</classname>
+looks in <filename>hbase-site.xml</filename> for a <varname>hbase.trace.spanreceiver.localfilespanreceiver.filename</varname>
+property with a value describing the name of the file to which nodes should write their span information. 
+</para>
+
+<para>If you do not want to use the included <classname>HBaseLocalFileSpanReceiver</classname>,
+you are encouraged to write your own receiver (take a look at <classname>HBaseLocalFileSpanReceiver</classname>
+for an example). If you think others would benefit from your receiver, file a JIRA or send a pull request to
+<link xlink:href="http://github.com/cloudera/htrace">HTrace</link>. 
+</para>
+</section>
+<section xml:id="tracing.client.modifications">
+<title>Client Modifications</title>
+<para>Currently, you must turn on tracing in your client code. To do this, you simply turn on tracing for
+requests you think are interesting, and turn it off when the request is done. 
+</para>
+
+<para>For example, if you wanted to trace all of your get operations, you change this: 
+<programlisting>HTable table = new HTable(...);
+Get get = new Get(...);</programlisting>
+
+into: 
+
+<programlisting>Span getSpan = Trace.startSpan(“doing get”, Sampler.ALWAYS);
+try {
+  HTable table = new HTable(...);
+  Get get = new Get(...);
+...
+} finally {
+  getSpan.stop();
+}</programlisting>
+
+If you wanted to trace half of your ‘get’ operations, you would pass in:
+<programlisting>new ProbabilitySampler(0.5)</programlisting> in lieu of <varname>Sampler.ALWAYS</varname> to <classname>Trace.startSpan()</classname>.
+See the HTrace <filename>README</filename> for more information on Samplers.
+</para>
+</section>
+
+  </appendix>
+
   <index xml:id="book_index">
   <title>Index</title>
   </index>