hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject svn commit: r1580162 - in /hbase/branches/0.96/src/main/docbkx: configuration.xml developer.xml tracing.xml
Date Sat, 22 Mar 2014 04:29:59 GMT
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>



Mime
View raw message