Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-10590 Update contents about tracing in the Reference Guide 

git-svn-id: https://svn.apache.org/repos/asf/hbase/trunk@1571464 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Michael Stack 2014-02-24 22:16:00 +00:00
parent b024de156c
commit 1ec190a792
2 changed files with 164 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
src/main/docbkx/book.xml
View File

@ -3547,67 +3547,7 @@ Comparator class used for Bloom filter keys, a UTF>8 encoded string stored usi
</section> </section>
</appendix> </appendix>
<appendix xml:id="tracing" ><title>Enabling Dapper-like Tracing in HBase</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tracing.xml" />
<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>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="rpc.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="rpc.xml" />
<index xml:id="book_index"> <index xml:id="book_index">

163
src/main/docbkx/tracing.xml Normal file
View File

@ -0,0 +1,163 @@
<?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>
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>
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>
In order to turn on tracing in your client code,
you must initialize the module sending spans to receiver
once per client process.
<programlisting>
private SpanReceiverHost 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>
HTable table = new HTable(...);
Get get = new Get(...);
</programlisting>
into:
<programlisting>
TraceScope traceScope = Trace.startSpan("doing get", Sampler.ALWAYS);
try {
HTable table = new HTable(...);
Get get = new Get(...);
...
} finally {
traceScope.close();
}
</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>
<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>
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>
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>