Repository: incubator-htrace Updated Branches: refs/heads/master 59f4ca949 -> 10f2b8987
HTRACE-12. update README.md to describe SpanReceiver builder and Sampler builder (cmccabe) Project: http://git-wip-us.apache.org/repos/asf/incubator-htrace/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-htrace/commit/10f2b898 Tree: http://git-wip-us.apache.org/repos/asf/incubator-htrace/tree/10f2b898 Diff: http://git-wip-us.apache.org/repos/asf/incubator-htrace/diff/10f2b898 Branch: refs/heads/master Commit: 10f2b898716a59245e7a3cc1233211b1f93487d4 Parents: 59f4ca9 Author: Colin P. Mccabe <[email protected]> Authored: Thu Dec 11 19:16:58 2014 -0800 Committer: Colin P. Mccabe <[email protected]> Committed: Thu Dec 11 23:12:06 2014 -0800 ---------------------------------------------------------------------- README.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-htrace/blob/10f2b898/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 2e01807..5a4c496 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,16 @@ 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 @@ -172,27 +182,30 @@ that is a child of `this`. 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 `receiveSpan` method which +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 configure(HTraceConfiguration conf); public void receiveSpan(Span span); } ```` -Each application process using HTrace needs to -initialize the SpanReceiver implementation and register it first -by calling `Trace.addReceiver` method. +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 - // load and instanciate SpanReceiver impl. - // ... - impl.configure(conf); - Trace.addReceiver(impl); + HTraceConfiguration hconf = createMyHTraceConfiguration(); + SpanReceiverBuilder builder = new SpanReceiverBuilder(hconf); + SpanReceiver spanReceiver = builder.build(); + if (spanReceiver != null) { + Trace.addReceiver(spanReceiver); + } ```` ####Zipkin
