HBASE-13582: Update docs for HTrace Signed-off-by: stack <[email protected]>
Project: http://git-wip-us.apache.org/repos/asf/hbase/repo Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/02fa2200 Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/02fa2200 Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/02fa2200 Branch: refs/heads/hbase-12439 Commit: 02fa2200be4ead37094efbac74cb3431fa0ead55 Parents: ed5ac65 Author: Lars Francke <[email protected]> Authored: Tue May 19 22:31:26 2015 +0200 Committer: stack <[email protected]> Committed: Tue May 19 16:04:39 2015 -0700 ---------------------------------------------------------------------- src/main/asciidoc/_chapters/tracing.adoc | 43 +++++++++------------------ 1 file changed, 14 insertions(+), 29 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hbase/blob/02fa2200/src/main/asciidoc/_chapters/tracing.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/tracing.adoc b/src/main/asciidoc/_chapters/tracing.adoc index 6bb8065..9b3711e 100644 --- a/src/main/asciidoc/_chapters/tracing.adoc +++ b/src/main/asciidoc/_chapters/tracing.adoc @@ -30,13 +30,13 @@ :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://github.com/cloudera/htrace[HTrace]. +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 structs 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: +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] ---- @@ -57,51 +57,38 @@ The `LocalFileSpanReceiver` looks in _hbase-site.xml_ for a `hbase.local-fi <property> <name>hbase.trace.spanreceiver.classes</name> - <value>org.htrace.impl.LocalFileSpanReceiver</value> + <value>org.apache.htrace.impl.LocalFileSpanReceiver</value> </property> <property> - <name>hbase.local-file-span-receiver.path</name> + <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 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 maven central repository. -You could get the latest version from there or just build it locally and then copy it out to all nodes, change your config to use zipkin receiver, distribute the new configuration and then (rolling) restart. +_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. -Here is the example of manual setup procedure. - ----- - -$ git clone https://github.com/cloudera/htrace -$ cd htrace/htrace-zipkin -$ mvn compile assembly:single -$ cp target/htrace-zipkin-*-jar-with-dependencies.jar $HBASE_HOME/lib/ - # copy jar to all nodes... ----- - -The `ZipkinSpanReceiver` looks in _hbase-site.xml_ for a `hbase.zipkin.collector-hostname` and `hbase.zipkin.collector-port` property with a value describing the Zipkin collector server to which span information are sent. +`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.htrace.impl.ZipkinSpanReceiver</value> + <value>org.apache.htrace.impl.ZipkinSpanReceiver</value> </property> <property> - <name>hbase.zipkin.collector-hostname</name> + <name>hbase.htrace.zipkin.collector-hostname</name> <value>localhost</value> </property> <property> - <name>hbase.zipkin.collector-port</name> + <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 or send a pull request to link:http://github.com/cloudera/htrace[HTrace]. +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 @@ -160,8 +147,7 @@ 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. +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] ---- @@ -171,9 +157,8 @@ 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 suceess. +trace 'status'+ just returns if or not tracing is turned on. +`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] ----
