You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@htrace.apache.org by st...@apache.org on 2014/12/16 21:47:51 UTC
incubator-htrace git commit: HTRACE-19 First cut at website
Repository: incubator-htrace
Updated Branches:
refs/heads/master 5abf6b8e3 -> 16eca8ee0
HTRACE-19 First cut at website
Project: http://git-wip-us.apache.org/repos/asf/incubator-htrace/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-htrace/commit/16eca8ee
Tree: http://git-wip-us.apache.org/repos/asf/incubator-htrace/tree/16eca8ee
Diff: http://git-wip-us.apache.org/repos/asf/incubator-htrace/diff/16eca8ee
Branch: refs/heads/master
Commit: 16eca8ee0d2d1e2c1f34b31029d47c3d1b45a9c0
Parents: 5abf6b8
Author: stack <st...@duboce.net>
Authored: Mon Dec 15 18:23:04 2014 -0800
Committer: stack <st...@duboce.net>
Committed: Tue Dec 16 12:46:15 2014 -0800
----------------------------------------------------------------------
README.md | 240 +-------------------------------------------
pom.xml | 108 ++++++++++++++++----
site/markdown/index.md | 238 +++++++++++++++++++++++++++++++++++++++++++
site/site.xml | 70 +++++++++++++
4 files changed, 398 insertions(+), 258 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/16eca8ee/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 5a4c496..e5fd84f 100644
--- a/README.md
+++ b/README.md
@@ -1,241 +1,5 @@
HTrace
======
-HTrace is a tracing framework intended for use with distributed systems written in java.
+HTrace is a tracing framework for use with distributed systems written in java.
-The project is hosted at http://htrace.incubator.apache.org
-The project is available in Maven Central with groupId: org.apache.htrace,
-and name: htrace (It was formally groupId: org.cloudera.htrace, and
-groundId: org.htrace).
-
-API
----
-Using HTrace requires adding some instrumentation to your application.
-Before we get into the details, lets review our terminology. HTrace
-borrows [Dapper's](http://research.google.com/pubs/pub36356.html)
-terminology.
-
-<b>Span:</b> The basic unit of work. For example, sending an RPC is a
-new span, as is sending a response to an RPC.
-Span's are identified by a unique 64-bit ID for the span and another
-64-bit ID for the trace the span is a part of. Spans also have other
-data, such as descriptions, key-value annotations, the ID of the span
-that caused them, and process ID's (normally IP address).
-<br>
-Spans are started and stopped, and they keep track of their timing
-information. Once you create a span, you must stop it at some point
-in the future.
-
-<b>Trace:</b> A set of spans forming a tree-like structure. For
-example, if you are running a distributed big-data store, a trace
-might be formed by a put request.
-
-### How to add tracing to your application
-To instrument your system you must:
-<br>
-<b>1. Attach additional information to your RPC's.</b>
-In order to create the causal links necessary for a trace, HTrace
-needs to know about the causal
-relationships between spans. The only information you need to add to
-your RPC's is two 64-bit longs. If tracing is enabled (Trace.isTracing()
-returns true) when you send an RPC, attach the ID of the current span
-and the ID of the current trace to the message.
-On the receiving end of the RPC, check to see if the message has the
-additional tracing information above. If it does, start a new span
-with the information given (more on that in a bit).
-<br>
-<b>2. Wrap your thread changes.</b>
-HTrace stores span information in java's ThreadLocals, which causes
-the trace to be "lost" on thread changes. The only way to prevent
-this is to "wrap" your thread changes. For example, if your code looks
-like this:
-
-````java
- Thread t1 = new Thread(new MyRunnable());
- ...
-````
-
-Just change it to look this:
-
-````java
- Thread t1 = new Thread(Trace.wrap(new MyRunnable()));
-````
-
-That's it! `Trace.wrap()` takes a single argument (a runnable or a
-callable) and if the current thread is a part of a trace, returns a
-wrapped version of the argument. The wrapped version of a callable
-and runnable just knows about the span that created it and will start
-a new span in the new thread that is the child of the span that
-created the runnable/callable. There may be situations in which a
-simple `Trace.wrap()` does not suffice. In these cases all you need
-to do is keep a reference to the "parent span" (the span before the
-thread change) and once you're in the new thread start a new span that
-is the "child" of the parent span you stored.
-<br>
-For example:
-<br>
-Say you have some object representing a "put" operation. When the
-client does a "put," the put is first added to a list so another
-thread can batch together the puts. In this situation, you
-might want to add another field to the Put class that could store the
-current span at the time the put was created. Then when the put is
-pulled out of the list to be processed, you can start a new span as
-the child of the span stored in the Put.
-<br>
-<b>3. Add custom spans and annotations.</b>
-Once you've augmented your RPC's and wrapped the necessary thread
-changes, you can add more spans and annotations wherever you want.
-For example, you might do some expensive computation that you want to
-see on your traces. In this case, you could start a new span before
-the computation that you then stop after the computation has
-finished. It might look like this:
-
-````java
- Span computationSpan = Trace.startSpan("Expensive computation.");
- try {
- //expensive computation here
- } finally {
- computationSpan.stop();
- }
-````
-
-HTrace also supports key-value annotations on a per-trace basis.
-<br>
-Example:
-
-````java
- Trace.currentTrace().addAnnotation("faultyRecordCounter".getBytes(), "1".getBytes());
-````
-
-`Trace.currentTrace()` will not return `null` if the current thread is
-not tracing, but instead it will return a `NullSpan`, which does
-nothing on any of its method calls. The takeaway here is you can call
-methods on the `currentTrace()` without fear of NullPointerExceptions.
-
-###Samplers
-`Sampler` is an interface that defines one function:
-
-````java
- boolean next(T info);
-````
-
-All of the `Trace.startSpan()` methods can take an optional sampler.
-A new span is only created if the sampler's next function returns
-true. If the Sampler returns false, the `NullSpan` is returned from
-`startSpan()`, so it's safe to call `stop()` or `addAnnotation()` on it.
-As you may have noticed from the `next()` method signature, Sampler is
-parameterized. The argument to `next()` is whatever piece of
-information you might need for sampling. See `Sampler.java` for an
-example of this. If you do not require any additional information,
-then just ignore the parameter.
-HTrace includes a sampler that always returns true, a
-sampler that always returns false and a sampler returns true some
-percentage of the time (you pass in the percentage as a decimal at construction).
-
-HTrace comes with several standard samplers, including `AlwaysSampler`,
-`NeverSampler`, `ProbabilitySampler`, and `CountSampler`. An application can
-use the `SamplerBuilder` to create one of these standard samplers based on the
-current configuration.
-
-````java
- HTraceConfiguration hconf = createMyHTraceConfiguration();
- Sampler sampler = new SamplerBuilder(hconf).build();
-````
-
-####Trace.startSpan()
-There is a single method to create and start spans: `startSpan()`.
-For the `startSpan()` methods that do not take an explicit Sampler, the
-default Sampler is used. The default sampler returns true if and only
-if tracing is already on in the current thread. That means that
-calling `startSpan()` with no explicit Sampler is a good idea when you
-have information that you would like to add to a trace if it's already
-occurring, but is not something you would want to start a whole new
-trace for.
-<br>
-If you are using a sampler that makes use of the `T info` parameter to
-`next()`, just pass in the object as the last argument. If you leave it
-out, HTrace will pass `null` for you (so make sure your Samplers can
-handle `null`).
-<br>
-Aside from whether or not you pass in an explicit `Sampler`, there are
-other options you have when calling `startSpan()`.
-For the next section I am assuming you are familiar with the options
-for passing in `Samplers` and `info` parameters, so when I say "no
-arguments," I mean no additional arguments other than whatever
-`Sampler`/`info` parameters you deem necessary.
-<br>
-You can call `startSpan()` with no additional arguments.
-In this case, `Trace.java` will start a span if the sampler (explicit
-or default) returns true. If the current span is not the `NullSpan`, the span
-returned will be a child of the current span, otherwise it will start
-a new trace in the current thread (it will be a
-`ProcessRootMilliSpan`). All of the other `startSpan()` methods take some
-parameter describing the parent span of the span to be created. The
-versions that take a `TraceInfo` or a `long traceId` and `long
-parentId` will mostly be used when continuing a trace over RPC. The
-receiver of the RPC will check the message for the additional two
-`longs` and will call `startSpan()` if they are attached. The last
-`startSpan()` takes a `Span parent`. The result of `parent.child()`
-will be used for the new span. `Span.child()` simply returns a span
-that is a child of `this`.
-
-###Span Receivers
-In order to use the tracing information consisting of spans,
-you need an implementation of `SpanReceiver` interface which collects spans
-and typically writes it to files or databases or collector services.
-The `SpanReceiver` implementation must provide a `receiveSpan` method which
-is called from `Trace.deliver` method.
-You do not need to explicitly call `Trace.deliver`
-because it is internally called by the implementation of `Span`.
-
-````java
- public interface SpanReceiver extends Closeable {
- public void receiveSpan(Span span);
- }
-````
-
-HTrace comes with several standard span receivers, such as
-`LocalFileSpanReceiver`. An application can use the `SpanReceiverBuilder` to
-create a particular type of standard `SpanReceiver` based on the current
-configuration. Once a SpanReceiver has been created, it should be registered
-with the HTrace framework by calling `Trace.addReceiver`.
-
-````java
- HTraceConfiguration hconf = createMyHTraceConfiguration();
- SpanReceiverBuilder builder = new SpanReceiverBuilder(hconf);
- SpanReceiver spanReceiver = builder.build();
- if (spanReceiver != null) {
- Trace.addReceiver(spanReceiver);
- }
-````
-
-####Zipkin
-htrace-zipkin provides the `SpanReceiver` implementation
-which sends spans to [Zipkin](https://github.com/twitter/zipkin) collector.
-You can build the uber-jar (htrace-zipkin-*-jar-withdependency.jar) for manual
-setup as shown below. This uber-jar contains all dependencies except
-htrace-core and its dependencies.
-
- $ cd htrace-zipkin
- $ mvn compile assembly:single
-
-####HBase Receiver
-See htrace-hbase for an Span Receiver implementation that writes HBase.
-Also bundled is a simple Span Viewer.
-
-Testing Information
--------------------------------
-
-The test that creates a sample trace (TestHTrace) takes a command line
-argument telling it where to write span information. Run
-`mvn test -DargLine="-DspanFile=FILE\_PATH"` to write span
-information to FILE_PATH. If no file is specified, span information
-will be written to standard out. If span information is written to a
-file, you can use the included graphDrawer python script in tools/
-to create a simple visualization of the trace. Or you could write
-some javascript to make a better visualization, and send a pull
-request if you do :).
-
-Publishing to Maven Central
--------------------------------
-See [OSSRH-8896](https://issues.sonatype.org/browse/OSSRH-8896)
-for repository vitals.
+See documentation at site/markdown/index.md or at http://htrace.incubator.apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/16eca8ee/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index a64d2f8..10bf552 100644
--- a/pom.xml
+++ b/pom.xml
@@ -16,9 +16,9 @@ language governing permissions and limitations under the License. -->
<artifactId>htrace</artifactId>
<version>3.1.0-SNAPSHOT</version>
<packaging>pom</packaging>
-
- <name>htrace</name>
- <description>Tracing library</description>
+ <name>Apache HTrace</name>
+ <description>A tracing framework for use with distributed systems written in java</description>
+ <url>http://htrace.incubator.apache.org</url>
<modules>
<module>htrace-core</module>
@@ -32,6 +32,49 @@ language governing permissions and limitations under the License. -->
<version>7</version>
</parent>
+
+ <licenses>
+ <license>
+ <name>The Apache Software License, Version 2.0</name>
+ <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+ <distribution>repo</distribution>
+ <comments>A business-friendly OSS license</comments>
+ </license>
+ </licenses>
+ <scm>
+ <connection>scm:git:http://git-wip-us.apache.org/repos/asf/incubator-htrace.git</connection>
+ <developerConnection>scm:git:https://git-wip-us.apache.org/repos/asf/incubator-htrace.git</developerConnection>
+ <url>https://git-wip-us.apache.org/repos/asf?p=incubator-htrace.git</url>
+ </scm>
+ <issueManagement>
+ <system>JIRA</system>
+ <url>http://issues.apache.org/jira/browse/HTRACE</url>
+ </issueManagement>
+ <ciManagement>
+ <system>hudson</system>
+ <url>https://builds.apache.org/view/H-L/view/HTrace/</url>
+ </ciManagement>
+ <mailingLists>
+ <mailingList>
+ <name>Developer List</name>
+ <subscribe>dev-subscribe@htrace.incubator.apache.org</subscribe>
+ <unsubscribe>dev-unsubscribe@htrace.incubator.apache.org</unsubscribe>
+ <post>dev@htrace.incubator.apache.org</post>
+ <archive>http://mail-archives.apache.org/mod_mbox/incubator-htrace-dev/</archive>
+ </mailingList>
+ <mailingList>
+ <name>Commits List</name>
+ <subscribe>commits-subscribe@htrace.incubator.apache.org</subscribe>
+ <unsubscribe>commits-unsubscribe@htrace.incubator.apache.org</unsubscribe>
+ <archive>http://mail-archives.apache.org/mod_mbox/incubator-htrace-commits/</archive>
+ </mailingList>
+ <mailingList>
+ <name>Issues List</name>
+ <subscribe>issues-subscribe@htrace.incubator.apache.org</subscribe>
+ <unsubscribe>issues-unsubscribe@htrace.incubator.apache.org</unsubscribe>
+ <archive>http://mail-archives.apache.org/mod_mbox/incubator-htrace-issues/</archive>
+ </mailingList>
+ </mailingLists>
<developers>
<developer>
<id>jon</id>
@@ -50,21 +93,6 @@ language governing permissions and limitations under the License. -->
<organizationUrl>http://www.cloudera.com</organizationUrl>
</developer>
</developers>
-
- <url>http://incubator.apache.org/projects/htrace.html</url>
- <licenses>
- <license>
- <name>The Apache Software License, Version 2.0</name>
- <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
- <distribution>repo</distribution>
- <comments>A business-friendly OSS license</comments>
- </license>
- </licenses>
- <scm>
- <connection>scm:git:https://incubator.apache.org/projects/htrace.html</connection>
- <developerConnection>scm:git:https://incubator.apache.org/projects/htrace.html</developerConnection>
- <url>scm:git:https://incubator.apache.org/projects/htrace.html</url>
- </scm>
<build>
<pluginManagement>
<plugins>
@@ -193,8 +221,38 @@ language governing permissions and limitations under the License. -->
<artifactId>maven-deploy-plugin</artifactId>
</plugin>
<plugin>
- <groupId>org.apache.rat</groupId>
- <artifactId>apache-rat-plugin</artifactId>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>3.4</version>
+ <dependencies>
+ <dependency>
+ <!-- add support for ssh/scp -->
+ <groupId>org.apache.maven.wagon</groupId>
+ <artifactId>wagon-ssh</artifactId>
+ <version>2.2</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-module-markdown</artifactId>
+ <version>1.6</version>
+ </dependency>
+ <dependency>
+ <groupId>lt.velykis.maven.skins</groupId>
+ <artifactId>reflow-velocity-tools</artifactId>
+ <version>1.1.1</version>
+ </dependency>
+ <!-- Reflow skin requires Velocity >= 1.7 -->
+ <dependency>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>velocity</artifactId>
+ <version>1.7</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <siteDirectory>${basedir}/site</siteDirectory>
+ <inputEncoding>UTF-8</inputEncoding>
+ <outputEncoding>UTF-8</outputEncoding>
+ </configuration>
</plugin>
</plugins>
</build>
@@ -222,4 +280,14 @@ language governing permissions and limitations under the License. -->
</dependency>
</dependencies>
</dependencyManagement>
+ <distributionManagement>
+ <site>
+ <id>htrace.incubator.apache.org</id>
+ <name>HTrace Website at incubator.apache.org</name>
+ <!-- On why this is the tmp dir and not hbase.apache.org, see
+ https://issues.apache.org/jira/browse/HBASE-7593?focusedCommentId=13555866&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13555866
+ -->
+ <url>file:///tmp</url>
+ </site>
+ </distributionManagement>
</project>
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/16eca8ee/site/markdown/index.md
----------------------------------------------------------------------
diff --git a/site/markdown/index.md b/site/markdown/index.md
new file mode 100644
index 0000000..09b71a9
--- /dev/null
+++ b/site/markdown/index.md
@@ -0,0 +1,238 @@
+Apache HTrace is an <a href="http://htrace.incubator.apache.org">Apache Incubator</a>
+project. To add HTrace to your project, see detail on how to add it as a
+<a href="dependency-info.html">dependency</a>.
+
+Formally, HTrace was available at org.htrace.
+
+API
+---
+Using HTrace requires adding some instrumentation to your application.
+Before we get into the details, lets review our terminology. HTrace
+borrows [Dapper's](http://research.google.com/pubs/pub36356.html)
+terminology.
+
+<b>Span:</b> The basic unit of work. For example, sending an RPC is a
+new span, as is sending a response to an RPC.
+Span's are identified by a unique 64-bit ID for the span and another
+64-bit ID for the trace the span is a part of. Spans also have other
+data, such as descriptions, key-value annotations, the ID of the span
+that caused them, and process ID's (normally IP address).
+
+Spans are started and stopped, and they keep track of their timing
+information. Once you create a span, you must stop it at some point
+in the future.
+
+<b>Trace:</b> A set of spans forming a tree-like structure. For
+example, if you are running a distributed big-data store, a trace
+might be formed by a put request.
+
+### How to add tracing to your application
+To instrument your system you must:
+
+<b>1. Attach additional information to your RPC's.</b>
+In order to create the causal links necessary for a trace, HTrace
+needs to know about the causal
+relationships between spans. The only information you need to add to
+your RPC's is two 64-bit longs. If tracing is enabled (Trace.isTracing()
+returns true) when you send an RPC, attach the ID of the current span
+and the ID of the current trace to the message.
+On the receiving end of the RPC, check to see if the message has the
+additional tracing information above. If it does, start a new span
+with the information given (more on that in a bit).
+
+<b>2. Wrap your thread changes.</b>
+HTrace stores span information in java's ThreadLocals, which causes
+the trace to be "lost" on thread changes. The only way to prevent
+this is to "wrap" your thread changes. For example, if your code looks
+like this:
+
+````java
+ Thread t1 = new Thread(new MyRunnable());
+ ...
+````
+
+Just change it to look this:
+
+````java
+ Thread t1 = new Thread(Trace.wrap(new MyRunnable()));
+````
+
+That's it! `Trace.wrap()` takes a single argument (a runnable or a
+callable) and if the current thread is a part of a trace, returns a
+wrapped version of the argument. The wrapped version of a callable
+and runnable just knows about the span that created it and will start
+a new span in the new thread that is the child of the span that
+created the runnable/callable. There may be situations in which a
+simple `Trace.wrap()` does not suffice. In these cases all you need
+to do is keep a reference to the "parent span" (the span before the
+thread change) and once you're in the new thread start a new span that
+is the "child" of the parent span you stored.
+
+For example:
+
+Say you have some object representing a "put" operation. When the
+client does a "put," the put is first added to a list so another
+thread can batch together the puts. In this situation, you
+might want to add another field to the Put class that could store the
+current span at the time the put was created. Then when the put is
+pulled out of the list to be processed, you can start a new span as
+the child of the span stored in the Put.
+
+<b>3. Add custom spans and annotations.</b>
+Once you've augmented your RPC's and wrapped the necessary thread
+changes, you can add more spans and annotations wherever you want.
+For example, you might do some expensive computation that you want to
+see on your traces. In this case, you could start a new span before
+the computation that you then stop after the computation has
+finished. It might look like this:
+
+````java
+ Span computationSpan = Trace.startSpan("Expensive computation.");
+ try {
+ //expensive computation here
+ } finally {
+ computationSpan.stop();
+ }
+````
+
+HTrace also supports key-value annotations on a per-trace basis.
+
+Example:
+
+````java
+ Trace.currentTrace().addAnnotation("faultyRecordCounter".getBytes(), "1".getBytes());
+````
+
+`Trace.currentTrace()` will not return `null` if the current thread is
+not tracing, but instead it will return a `NullSpan`, which does
+nothing on any of its method calls. The takeaway here is you can call
+methods on the `currentTrace()` without fear of NullPointerExceptions.
+
+###Samplers
+`Sampler` is an interface that defines one function:
+
+````java
+ boolean next(T info);
+````
+
+All of the `Trace.startSpan()` methods can take an optional sampler.
+A new span is only created if the sampler's next function returns
+true. If the Sampler returns false, the `NullSpan` is returned from
+`startSpan()`, so it's safe to call `stop()` or `addAnnotation()` on it.
+As you may have noticed from the `next()` method signature, Sampler is
+parameterized. The argument to `next()` is whatever piece of
+information you might need for sampling. See `Sampler.java` for an
+example of this. If you do not require any additional information,
+then just ignore the parameter.
+HTrace includes a sampler that always returns true, a
+sampler that always returns false and a sampler returns true some
+percentage of the time (you pass in the percentage as a decimal at construction).
+
+HTrace comes with several standard samplers, including `AlwaysSampler`,
+`NeverSampler`, `ProbabilitySampler`, and `CountSampler`. An application can
+use the `SamplerBuilder` to create one of these standard samplers based on the
+current configuration.
+
+````java
+ HTraceConfiguration hconf = createMyHTraceConfiguration();
+ Sampler sampler = new SamplerBuilder(hconf).build();
+````
+
+####Trace.startSpan()
+There is a single method to create and start spans: `startSpan()`.
+For the `startSpan()` methods that do not take an explicit Sampler, the
+default Sampler is used. The default sampler returns true if and only
+if tracing is already on in the current thread. That means that
+calling `startSpan()` with no explicit Sampler is a good idea when you
+have information that you would like to add to a trace if it's already
+occurring, but is not something you would want to start a whole new
+trace for.
+
+If you are using a sampler that makes use of the `T info` parameter to
+`next()`, just pass in the object as the last argument. If you leave it
+out, HTrace will pass `null` for you (so make sure your Samplers can
+handle `null`).
+
+Aside from whether or not you pass in an explicit `Sampler`, there are
+other options you have when calling `startSpan()`.
+For the next section I am assuming you are familiar with the options
+for passing in `Samplers` and `info` parameters, so when I say "no
+arguments," I mean no additional arguments other than whatever
+`Sampler`/`info` parameters you deem necessary.
+
+You can call `startSpan()` with no additional arguments.
+In this case, `Trace.java` will start a span if the sampler (explicit
+or default) returns true. If the current span is not the `NullSpan`, the span
+returned will be a child of the current span, otherwise it will start
+a new trace in the current thread (it will be a
+`ProcessRootMilliSpan`). All of the other `startSpan()` methods take some
+parameter describing the parent span of the span to be created. The
+versions that take a `TraceInfo` or a `long traceId` and `long
+parentId` will mostly be used when continuing a trace over RPC. The
+receiver of the RPC will check the message for the additional two
+`longs` and will call `startSpan()` if they are attached. The last
+`startSpan()` takes a `Span parent`. The result of `parent.child()`
+will be used for the new span. `Span.child()` simply returns a span
+that is a child of `this`.
+
+###Span Receivers
+In order to use the tracing information consisting of spans,
+you need an implementation of `SpanReceiver` interface which collects spans
+and typically writes it to files or databases or collector services.
+The `SpanReceiver` implementation must provide a `receiveSpan` method which
+is called from `Trace.deliver` method.
+You do not need to explicitly call `Trace.deliver`
+because it is internally called by the implementation of `Span`.
+
+````java
+ public interface SpanReceiver extends Closeable {
+ public void receiveSpan(Span span);
+ }
+````
+
+HTrace comes with several standard span receivers, such as
+`LocalFileSpanReceiver`. An application can use the `SpanReceiverBuilder` to
+create a particular type of standard `SpanReceiver` based on the current
+configuration. Once a SpanReceiver has been created, it should be registered
+with the HTrace framework by calling `Trace.addReceiver`.
+
+````java
+ HTraceConfiguration hconf = createMyHTraceConfiguration();
+ SpanReceiverBuilder builder = new SpanReceiverBuilder(hconf);
+ SpanReceiver spanReceiver = builder.build();
+ if (spanReceiver != null) {
+ Trace.addReceiver(spanReceiver);
+ }
+````
+
+####Zipkin
+htrace-zipkin provides the `SpanReceiver` implementation
+which sends spans to [Zipkin](https://github.com/twitter/zipkin) collector.
+You can build the uber-jar (htrace-zipkin-*-jar-withdependency.jar) for manual
+setup as shown below. This uber-jar contains all dependencies except
+htrace-core and its dependencies.
+
+ $ cd htrace-zipkin
+ $ mvn compile assembly:single
+
+####HBase Receiver
+See htrace-hbase for an Span Receiver implementation that writes HBase.
+Also bundled is a simple Span Viewer.
+
+Testing Information
+-------------------------------
+
+The test that creates a sample trace (TestHTrace) takes a command line
+argument telling it where to write span information. Run
+`mvn test -DargLine="-DspanFile=FILE\_PATH"` to write span
+information to FILE_PATH. If no file is specified, span information
+will be written to standard out. If span information is written to a
+file, you can use the included graphDrawer python script in tools/
+to create a simple visualization of the trace. Or you could write
+some javascript to make a better visualization, and send a pull
+request if you do :).
+
+Publishing to Maven Central
+-------------------------------
+See [OSSRH-8896](https://issues.sonatype.org/browse/OSSRH-8896)
+for repository vitals.
http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/16eca8ee/site/site.xml
----------------------------------------------------------------------
diff --git a/site/site.xml b/site/site.xml
new file mode 100644
index 0000000..0c22c17
--- /dev/null
+++ b/site/site.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+/**
+ * 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.
+ */
+-->
+
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+ <bannerLeft>
+ <name>Apache HTrace</name>
+ <href>http://htrace.incubator.apache.org/</href>
+ </bannerLeft>
+ <bannerRight>
+ <name />
+ </bannerRight>
+ <body>
+ <menu name="Apache HTrace Project">
+ <item name="Overview" href="index.html"/>
+ <item name="License" href="license.html" />
+ <item name="Downloads" href="http://www.apache.org/dyn/closer.cgi/htrace/" />
+ <item name="Distribution" href="dependency-management.html" />
+ <item name="Dependency" href="dependency-info.html" />
+ <item name="Issue Tracking" href="issue-tracking.html" />
+ <item name="CI" href="integration.html" />
+ <item name="Mailing Lists" href="mail-lists.html" />
+ <item name="Source Repository" href="source-repository.html" />
+ <item name="Modules" href="modules.html" />
+ <item name="Project Info" href="project-info.html" />
+ <item name="Team" href="team-list.html" />
+ </menu>
+ <menu name="ASF">
+ <item name="Apache Software Foundation" href="http://www.apache.org/foundation/" />
+ <item name="How Apache Works" href="http://www.apache.org/foundation/how-it-works.html" />
+ <item name="Sponsoring Apache" href="http://www.apache.org/foundation/sponsorship.html" />
+ </menu>
+ </body>
+ <custom>
+ <reflowSkin>
+ <theme>bootswatch-flatly</theme>
+ <toc>top</toc>
+ <highlightJs>true</highlightJs>
+ <slogan position="bannerRight">A tracing framework for use with distributed systems written in java</slogan>
+ <bottomNav>
+ <column>Home</column>
+ </bottomNav>
+ </reflowSkin>
+ </custom>
+ <skin>
+ <groupId>lt.velykis.maven.skins</groupId>
+ <artifactId>reflow-maven-skin</artifactId>
+ <version>1.1.1</version>
+ </skin>
+</project>