[2/9] accumulo git commit: ACCUMULO-3971 Add more tracing doc to user manual

[el...@apache.org]

ACCUMULO-3971 Add more tracing doc to user manual


Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/cf5ef46f
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/cf5ef46f
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/cf5ef46f

Branch: refs/heads/master
Commit: cf5ef46f3a450c50aa804445d4a82fbabb18dacd
Parents: da484a8
Author: Dylan Hutchison <dh...@mit.edu>
Authored: Sun Aug 23 19:50:24 2015 -0400
Committer: Dylan Hutchison <dh...@mit.edu>
Committed: Sun Aug 23 21:25:10 2015 -0400

----------------------------------------------------------------------
 .../main/asciidoc/chapters/administration.txt   | 52 +++++++++++++++++++-
 1 file changed, 50 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/accumulo/blob/cf5ef46f/docs/src/main/asciidoc/chapters/administration.txt
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/chapters/administration.txt b/docs/src/main/asciidoc/chapters/administration.txt
index f5f16bb..1373f89 100644
--- a/docs/src/main/asciidoc/chapters/administration.txt
+++ b/docs/src/main/asciidoc/chapters/administration.txt
@@ -306,6 +306,7 @@ A KeyStore can also be stored in HDFS, which will make the KeyStore readily avai
 all Accumulo servers. If the local filesystem is used, be aware that each Accumulo server
 will expect the KeyStore in the same location.
 
+[[ClientConfiguration]]
 ==== Client Configuration
 
 In version 1.6.0, Accumulo includes a new type of configuration file known as a client
@@ -536,6 +537,7 @@ To collect traces, Accumulo needs at least one server listed in
 from clients and writes them to the +trace+ table. The Accumulo
 user that the tracer connects to Accumulo with can be configured with
 the following properties
+(see the <<configuration,Configuration>> section for setting Accumulo server properties)
 
   trace.user
   trace.token.property.password
@@ -610,6 +612,47 @@ Hadoop to send traces to ZooTraceClient is
 The accumulo-core, accumulo-tracer, accumulo-fate and libthrift
 jars must also be placed on Hadoop's classpath.
 
+===== Adding additional SpanReceivers
+https://github.com/openzipkin/zipkin[Zipkin]
+has a SpanReceiver supported by HTrace and popularized by Twitter
+that users looking for a more graphical trace display may opt to use.
+The following steps configure Accumulo to use org.apache.htrace.impl.ZipkinSpanReceiver
+in addition to the Accumulo's default ZooTraceClient, and they serve as a template
+for adding any SpanReceiver to Accumulo:
+
+1. Add the Jar containing the ZipkinSpanReceiver class file to the
++$ACCUMULO_HOME/lib/+.  It is critical that the Jar is placed in
++lib/+ and NOT in +lib/ext/+ so that the new SpanReceiver class
+is visible to the same class loader of htrace-core.
+
+2. Add the following to +$ACCUMULO_HOME/conf/accumulo-site.xml+:
+
+  <property>
+    <name>trace.span.receivers</name>
+    <value>org.apache.accumulo.tracer.ZooTraceClient,org.apache.htrace.impl.ZipkinSpanReceiver</value>
+  </property>
+
+3. Restart your Accumulo tablet servers.
+
+In order to use ZipkinSpanReceiver from a client as well as the Accumulo server,
+
+1. Ensure your client can see the ZipkinSpanReceiver class at runtime. For Maven projects,
+this is easily done by adding to your client's pom.xml (taking care to specify a good version)
+
+  <dependency>
+    <groupId>org.apache.htrace</groupId>
+    <artifactId>htrace-zipkin</artifactId>
+    <version>3.1.0-incubating</version>
+    <scope>runtime</scope>
+  </dependency>
+
+2. Add the following to your ClientConfiguration
+(see the <<ClientConfiguration>> section)
+
+  trace.span.receivers=org.apache.accumulo.tracer.ZooTraceClient,org.apache.htrace.impl.ZipkinSpanReceiver
+
+3. Instrument your client as in the next section.
+
 ==== Instrumenting a Client
 Tracing can be used to measure a client operation, such as a scan, as
 the operation traverses the distributed system. To enable tracing for
@@ -637,8 +680,13 @@ for (Entry entry : scanner) {
 }
 scope.close();
 
-Additionally, the user can create additional Spans within a Trace.
-The sampler for the trace should only be specified with the first span, and subsequent spans will be collected depending on whether that first span was sampled.
+The user can create additional Spans within a Trace.
+
+The sampler (such as +Sampler.ALWAYS+) for the trace should only be specified with a top-level span,
+and subsequent spans will be collected depending on whether that first span was sampled.
+Don't forget to specify a Sampler at the top-level span
+because the default Sampler only samples when part of a pre-existing trace,
+which will never occur in a client that never specifies a Sampler.
 
 [source,java]
 TraceScope scope = Trace.startSpan("Client Update", Sampler.ALWAYS);