src/main/asciidoc/_chapters/tracing.adoc

   1 ////
   2 /**
   3  *
   4  * Licensed to the Apache Software Foundation (ASF) under one
   5  * or more contributor license agreements.  See the NOTICE file
   6  * distributed with this work for additional information
   7  * regarding copyright ownership.  The ASF licenses this file
   8  * to you under the Apache License, Version 2.0 (the
   9  * "License"); you may not use this file except in compliance
  10  * with the License.  You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20 ////
  21
  22
  23 [appendix]
  24 [[tracing]]
  25 == Enabling Dapper-like Tracing in HBase
  26
  27 :doctype: book
  28 :numbered:
  29 :toc: left
  30 :icons: font
  31 :experimental:
  32
  33 HBase includes facilities for tracing requests using the open source tracing library, link:https://htrace.incubator.apache.org/[Apache HTrace].
  34 Setting up tracing is quite simple, however it currently requires some very minor changes to your client code (this requirement may be removed in the future).
  35
  36 Support for this feature using HTrace 3 in HBase was added in link:https://issues.apache.org/jira/browse/HBASE-6449[HBASE-6449]. Starting with HBase 2.0, there was a non-compatible update to HTrace 4 via link:https://issues.apache.org/jira/browse/HBASE-18601[HBASE-18601]. The examples provided in this section will be using HTrace 4 package names, syntax, and conventions. For older examples, please consult previous versions of this guide.
  37
  38 [[tracing.spanreceivers]]
  39 === SpanReceivers
  40
  41 The tracing system works by collecting information in structures called 'Spans'. It is up to you to choose how you want to receive this information by implementing the `SpanReceiver` interface, which defines one method:
  42
  43 [source]
  44 ----
  45
  46 public void receiveSpan(Span span);
  47 ----
  48
  49 This method serves as a callback whenever a span is completed.
  50 HTrace allows you to use as many SpanReceivers as you want so you can easily send trace information to multiple destinations.
  51
  52 Configure what SpanReceivers you'd like to us by putting a comma separated list of the fully-qualified class name of classes implementing `SpanReceiver` in _hbase-site.xml_ property: `hbase.trace.spanreceiver.classes`.
  53
  54 HTrace includes a `LocalFileSpanReceiver` that writes all span information to local files in a JSON-based format.
  55 The `LocalFileSpanReceiver` looks in _hbase-site.xml_      for a `hbase.local-file-span-receiver.path` property with a value describing the name of the file to which nodes should write their span information.
  56
  57 [source]
  58 ----
  59
  60 <property>
  61   <name>hbase.trace.spanreceiver.classes</name>
  62   <value>org.apache.htrace.core.LocalFileSpanReceiver</value>
  63 </property>
  64 <property>
  65   <name>hbase.htrace.local-file-span-receiver.path</name>
  66   <value>/var/log/hbase/htrace.out</value>
  67 </property>
  68 ----
  69
  70 HTrace also provides `ZipkinSpanReceiver` which converts spans to link:http://github.com/twitter/zipkin[Zipkin] span format and send them to Zipkin server. In order to use this span receiver, you need to install the jar of htrace-zipkin to your HBase's classpath on all of the nodes in your cluster.
  71
  72 _htrace-zipkin_ is published to the link:http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.apache.htrace%22%20AND%20a%3A%22htrace-zipkin%22[Maven central repository]. You could get the latest version from there or just build it locally (see the link:https://htrace.incubator.apache.org/[HTrace] homepage for information on how to do this) and then copy it out to all nodes.
  73
  74 `ZipkinSpanReceiver` for properties called `hbase.htrace.zipkin.collector-hostname` and `hbase.htrace.zipkin.collector-port` in _hbase-site.xml_ with values describing the Zipkin collector server to which span information are sent.
  75
  76 [source,xml]
  77 ----
  78
  79 <property>
  80   <name>hbase.trace.spanreceiver.classes</name>
  81   <value>org.apache.htrace.core.ZipkinSpanReceiver</value>
  82 </property>
  83 <property>
  84   <name>hbase.htrace.zipkin.collector-hostname</name>
  85   <value>localhost</value>
  86 </property>
  87 <property>
  88   <name>hbase.htrace.zipkin.collector-port</name>
  89   <value>9410</value>
  90 </property>
  91 ----
  92
  93 If you do not want to use the included span receivers, you are encouraged to write your own receiver (take a look at `LocalFileSpanReceiver` for an example). If you think others would benefit from your receiver, file a JIRA with the HTrace project.
  94
  95 [[tracing.client.modifications]]
  96 == Client Modifications
  97
  98 In order to turn on tracing in your client code, you must initialize the module sending spans to receiver once per client process.
  99
 100 [source,java]
 101 ----
 102
 103 private SpanReceiverHost spanReceiverHost;
 104
 105 ...
 106
 107   Configuration conf = HBaseConfiguration.create();
 108   SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf);
 109 ----
 110
 111 Then you simply start tracing span before requests you think are interesting, and close it when the request is done.
 112 For example, if you wanted to trace all of your get operations, you change this:
 113
 114 [source,java]
 115 ----
 116 Configuration config = HBaseConfiguration.create();
 117 Connection connection = ConnectionFactory.createConnection(config);
 118 Table table = connection.getTable(TableName.valueOf("t1"));
 119 Get get = new Get(Bytes.toBytes("r1"));
 120 Result res = table.get(get);
 121 ----
 122
 123 into:
 124
 125 [source,java]
 126 ----
 127
 128 TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS);
 129 try {
 130   Table table = connection.getTable(TableName.valueOf("t1"));
 131   Get get = new Get(Bytes.toBytes("r1"));
 132   Result res = table.get(get);
 133 } finally {
 134   ts.close();
 135 }
 136 ----
 137
 138 If you wanted to trace half of your 'get' operations, you would pass in:
 139
 140 [source,java]
 141 ----
 142
 143 new ProbabilitySampler(0.5)
 144 ----
 145
 146 in lieu of `Sampler.ALWAYS` to `Trace.startSpan()`.
 147 See the HTrace _README_ for more information on Samplers.
 148
 149 [[tracing.client.shell]]
 150 == Tracing from HBase Shell
 151
 152 You can use `trace` command for tracing requests from HBase Shell. `trace 'start'` command turns on tracing and `trace 'stop'` command turns off tracing.
 153
 154 [source]
 155 ----
 156
 157 hbase(main):001:0> trace 'start'
 158 hbase(main):002:0> put 'test', 'row1', 'f:', 'val1'   # traced commands
 159 hbase(main):003:0> trace 'stop'
 160 ----
 161
 162 `trace 'start'` and `trace 'stop'` always returns boolean value representing if or not there is ongoing tracing.
 163 As a result, `trace 'stop'` returns false on success. `trace 'status'` just returns if or not tracing is turned on.
 164
 165 [source]
 166 ----
 167
 168 hbase(main):001:0> trace 'start'
 169 => true
 170
 171 hbase(main):002:0> trace 'status'
 172 => true
 173
 174 hbase(main):003:0> trace 'stop'
 175 => false
 176
 177 hbase(main):004:0> trace 'status'
 178 => false
 179 ----
 180
 181 :numbered: