hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r1388337 - /hbase/trunk/src/docbkx/book.xml
Date Fri, 21 Sep 2012 06:23:03 GMT
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>



Mime
View raw message