| //// |
| /** |
| * |
| * 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. |
| */ |
| //// |
| |
| |
| [appendix] |
| [[tracing]] |
| == Enabling Dapper-like Tracing in HBase |
| |
| :doctype: book |
| :numbered: |
| :toc: left |
| :icons: font |
| :experimental: |
| |
| link:https://issues.apache.org/jira/browse/HBASE-6449[HBASE-6449] added support for tracing requests through HBase, using the open source tracing library, link:http://htrace.incubator.apache.org/[HTrace]. |
| 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). |
| |
| [[tracing.spanreceivers]] |
| === SpanReceivers |
| |
| 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: |
| |
| [source] |
| ---- |
| |
| public void receiveSpan(Span span); |
| ---- |
| |
| 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. |
| |
| 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`. |
| |
| HTrace includes a `LocalFileSpanReceiver` that writes all span information to local files in a JSON-based format. |
| 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. |
| |
| [source] |
| ---- |
| |
| <property> |
| <name>hbase.trace.spanreceiver.classes</name> |
| <value>org.apache.htrace.impl.LocalFileSpanReceiver</value> |
| </property> |
| <property> |
| <name>hbase.htrace.local-file-span-receiver.path</name> |
| <value>/var/log/hbase/htrace.out</value> |
| </property> |
| ---- |
| |
| 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. |
| |
| _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:http://htrace.incubator.apache.org/[HTrace] homepage for information on how to do this) and then copy it out to all nodes. |
| |
| `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. |
| |
| [source,xml] |
| ---- |
| |
| <property> |
| <name>hbase.trace.spanreceiver.classes</name> |
| <value>org.apache.htrace.impl.ZipkinSpanReceiver</value> |
| </property> |
| <property> |
| <name>hbase.htrace.zipkin.collector-hostname</name> |
| <value>localhost</value> |
| </property> |
| <property> |
| <name>hbase.htrace.zipkin.collector-port</name> |
| <value>9410</value> |
| </property> |
| ---- |
| |
| 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. |
| |
| [[tracing.client.modifications]] |
| == Client Modifications |
| |
| In order to turn on tracing in your client code, you must initialize the module sending spans to receiver once per client process. |
| |
| [source,java] |
| ---- |
| |
| private SpanReceiverHost spanReceiverHost; |
| |
| ... |
| |
| Configuration conf = HBaseConfiguration.create(); |
| SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf); |
| ---- |
| |
| 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: |
| |
| [source,java] |
| ---- |
| Configuration config = HBaseConfiguration.create(); |
| Connection connection = ConnectionFactory.createConnection(config); |
| Table table = connection.getTable(TableName.valueOf("t1")); |
| Get get = new Get(Bytes.toBytes("r1")); |
| Result res = table.get(get); |
| ---- |
| |
| into: |
| |
| [source,java] |
| ---- |
| |
| TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS); |
| try { |
| Table table = connection.getTable(TableName.valueOf("t1")); |
| Get get = new Get(Bytes.toBytes("r1")); |
| Result res = table.get(get); |
| } finally { |
| ts.close(); |
| } |
| ---- |
| |
| If you wanted to trace half of your 'get' operations, you would pass in: |
| |
| [source,java] |
| ---- |
| |
| new ProbabilitySampler(0.5) |
| ---- |
| |
| in lieu of `Sampler.ALWAYS` to `Trace.startSpan()`. |
| See the HTrace _README_ for more information on Samplers. |
| |
| [[tracing.client.shell]] |
| == Tracing from HBase Shell |
| |
| You can use `trace` command for tracing requests from HBase Shell. `trace 'start'` command turns on tracing and `trace 'stop'` command turns off tracing. |
| |
| [source] |
| ---- |
| |
| hbase(main):001:0> trace 'start' |
| hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands |
| hbase(main):003:0> trace 'stop' |
| ---- |
| |
| `trace 'start'` and `trace 'stop'` always returns boolean value representing if or not there is ongoing tracing. |
| As a result, `trace 'stop'` returns false on success. `trace 'status'` just returns if or not tracing is turned on. |
| |
| [source] |
| ---- |
| |
| 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 |
| ---- |
| |
| :numbered: |