You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hbase.apache.org by st...@apache.org on 2014/03/22 05:29:59 UTC
svn commit: r1580162 - in /hbase/branches/0.96/src/main/docbkx:
configuration.xml developer.xml tracing.xml
Author: stack
Date: Sat Mar 22 04:29:58 2014
New Revision: 1580162
URL: http://svn.apache.org/r1580162
Log:
Add missing tracing.xml
Added:
hbase/branches/0.96/src/main/docbkx/tracing.xml
Modified:
hbase/branches/0.96/src/main/docbkx/configuration.xml
hbase/branches/0.96/src/main/docbkx/developer.xml
Modified: hbase/branches/0.96/src/main/docbkx/configuration.xml
URL: http://svn.apache.org/viewvc/hbase/branches/0.96/src/main/docbkx/configuration.xml?rev=1580162&r1=1580161&r2=1580162&view=diff
==============================================================================
Binary files - no diff available.
Modified: hbase/branches/0.96/src/main/docbkx/developer.xml
URL: http://svn.apache.org/viewvc/hbase/branches/0.96/src/main/docbkx/developer.xml?rev=1580162&r1=1580161&r2=1580162&view=diff
==============================================================================
Binary files - no diff available.
Added: hbase/branches/0.96/src/main/docbkx/tracing.xml
URL: http://svn.apache.org/viewvc/hbase/branches/0.96/src/main/docbkx/tracing.xml?rev=1580162&view=auto
==============================================================================
--- hbase/branches/0.96/src/main/docbkx/tracing.xml (added)
+++ hbase/branches/0.96/src/main/docbkx/tracing.xml Sat Mar 22 04:29:58 2014
@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix xml:id="tracing"
+ version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook">
+ <!--/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.
+ */
+-->
+ <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><![CDATA[
+ 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 us
+ 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>
+ HTrace includes a <classname>LocalFileSpanReceiver</classname>
+ that writes all span information to local files in a JSON-based format.
+ The <classname>LocalFileSpanReceiver</classname>
+ looks in <filename>hbase-site.xml</filename>
+ for a <varname>hbase.local-file-span-receiver.path</varname>
+ property with a value describing the name of the file
+ to which nodes should write their span information.
+<programlisting><![CDATA[
+ <property>
+ <name>hbase.trace.spanreceiver.classes</name>
+ <value>org.htrace.impl.LocalFileSpanReceiver</value>
+ </property>
+ <property>
+ <name>hbase.local-file-span-receiver.path</name>
+ <value>/var/log/hbase/htrace.out</value>
+ </property>
+]]></programlisting>
+ </para>
+
+ <para>
+ HTrace also includes a <classname>ZipkinSpanReceiver</classname>
+ that converts all span information to
+ <link xlink:href="http://github.com/twitter/zipkin">Zipkin</link>
+ span format and send them to Zipkin server.
+ You need to install htrace-zipkin jar and add it to your HBase classpath
+ in order to use this receiver.
+ The <classname>ZipkinSpanReceiver</classname>
+ looks in <filename>hbase-site.xml</filename>
+ for a <varname>hbase.zipkin.collector-hostname</varname>
+ and <varname>hbase.zipkin.collector-port</varname>
+ property with a value describing the Zipkin server
+ to which span information are sent.
+<programlisting><![CDATA[
+ <property>
+ <name>hbase.trace.spanreceiver.classes</name>
+ <value>org.htrace.impl.ZipkinSpanReceiver</value>
+ </property>
+ <property>
+ <name>hbase.zipkin.collector-hostname</name>
+ <value>localhost</value>
+ </property>
+ <property>
+ <name>hbase.zipkin.collector-port</name>
+ <value>9410</value>
+ </property>
+]]></programlisting>
+ </para>
+
+ <para>
+ If you do not want to use the included span receivers,
+ you are encouraged to write your own receiver
+ (take a look at <classname>LocalFileSpanReceiver</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>
+ In order to turn on tracing in your client code,
+ you must initialize the module sending spans to receiver
+ once per client process.
+ (Because <classname>SpanReceiverHost</classname> is included in hbase-server jar,
+ you need it on the client classpath in order to run this example.)
+<programlisting><![CDATA[
+ private SpanReceiverHost spanReceiverHost;
+
+ ...
+
+ Configuration conf = HBaseConfiguration.create();
+ SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf);
+]]></programlisting>
+ Then you simply start tracing span before requests you think are interesting,
+ and close it when the request is done.
+ For example, if you wanted to trace all of your get operations,
+ you change this:
+<programlisting><![CDATA[
+ HTable table = new HTable(conf, "t1");
+ Get get = new Get(Bytes.toBytes("r1"));
+ Result res = table.get(get);
+]]></programlisting>
+ into:
+<programlisting><![CDATA[
+ TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS);
+ try {
+ HTable table = new HTable(conf, "t1");
+ Get get = new Get(Bytes.toBytes("r1"));
+ Result res = table.get(get);
+ } finally {
+ ts.close();
+ }
+]]></programlisting>
+ If you wanted to trace half of your 'get' operations, you would pass in:
+<programlisting><![CDATA[
+ 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>
+
+ <section xml:id="tracing.client.shell">
+ <title>Tracing from HBase Shell</title>
+ <para>
+ You can use <command>trace</command> command
+ for tracing requests from HBase Shell.
+ <command>trace 'start'</command> command turns on tracing and
+ <command>trace 'stop'</command> command turns off tracing.
+<programlisting><![CDATA[
+ hbase(main):001:0> trace 'start'
+ hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands
+ hbase(main):003:0> trace 'stop'
+]]></programlisting>
+ </para>
+ <para>
+ <command>trace 'start'</command> and
+ <command>trace 'stop'</command> always
+ returns boolean value representing
+ if or not there is ongoing tracing.
+ As a result, <command>trace 'stop'</command>
+ returns false on suceess.
+ <command>trace 'status'</command>
+ just returns if or not tracing is turned on.
+<programlisting><![CDATA[
+ hbase(main):001:0> trace 'start'
+ => true
+
+ hbase(main):002:0> trace 'status'
+ => true
+
+ hbase(main):003:0> trace 'stop'
+ => false
+
+ hbase(main):004:0> trace 'status'
+ => false
+]]></programlisting>
+ </para>
+ </section>
+
+</appendix>