Merge branch 'GSOC_HTRACE' of https://github.com/nisalanirmana/incubator-htrace
diff --git a/BUILDING.txt b/BUILDING.txt
index ad8ef12..5407fa2 100644
--- a/BUILDING.txt
+++ b/BUILDING.txt
@@ -4,7 +4,7 @@
Building HTrace requires
* Java 1.7 at least.
-* Apache Maven 3.x
+* Apache Maven 3.0.4
* Go programming language, version 1.4 or higher (for htrace-htraced)
* The development package for leveldb (for htrace-htraced)
diff --git a/LICENSE.txt b/LICENSE.txt
index 0befae8..a45e331 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -206,37 +206,72 @@
The HTrace Owl logo is from http://www.clker.com/clipart-13653.html. It is
public domain.
-D3, a javascript library for manipulating data, used by htrace-hbase
-is Copyright 2010-2014, Michael Bostock and BSD licensed:
-https://github.com/mbostock/d3/blob/master/LICENSE
+D3 v3.4.11, a javascript library for manipulating data, used by htrace-hbase
+is available under the BSD License:
-Bootstrap, an html, css, and javascript framework, is
-Copyright (c) 2011-2015 Twitter, Inc and MIT licensed:
-https://github.com/twbs/bootstrap/blob/master/LICENSE
+ Copyright (c) 2010-2014, Michael Bostock
+ All rights reserved.
-underscore, a javascript library of functional programming helpers, is
-(c) 2009-2014 Jeremy Ashkenas, DocumentCloud and Investigative Reporters
-& Editors and an MIT license:
-https://github.com/jashkenas/underscore/blob/master/LICENSE
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
-jquery, a javascript library, is Copyright jQuery Foundation and other
-contributors, https://jquery.org/. The software consists of
-voluntary contributions made by many individuals. For exact
-contribution history, see the revision history
-available at https://github.com/jquery/jquery
-It is MIT licensed:
-https://github.com/jquery/jquery/blob/master/LICENSE.txt
+ * Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
-backbone, is a javascript library, that is Copyright (c) 2010-2014
-Jeremy Ashkenas, DocumentCloud. It is MIT licensed:
-https://github.com/jashkenas/backbone/blob/master/LICENSE
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
-moment.js is a front end time conversion project.
-It is (c) 2011-2014 Tim Wood, Iskren Chernev, Moment.js contributors
-and shared under the MIT license:
-https://github.com/moment/moment/blob/develop/LICENSE
+ * The name Michael Bostock may not be used to endorse or promote products
+ derived from this software without specific prior written permission.
-CMP is an implementation of the MessagePack serialization format in
-C. It is licensed under the MIT license:
-https://github.com/camgunz/cmp/blob/master/LICENSE
-See ./htrace-c/src/util/cmp.c and ./htrace-c/src/util/cmp.h.
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL MICHAEL BOSTOCK BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+ OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The following libraries are all available under these terms of the MIT license
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+
+Bootstrap v3.3.1, an html, css, and javascript framework.
+Copyright (c) 2011-2014 Twitter, Inc.
+
+underscore 1.7.0, a javascript library of functional programming helpers.
+Copyright (c) 2009-2014 Jeremy Ashkenas, DocumentCloud and Investigative
+Reporters & Editors
+
+jquery 2.1.4, a javascript library.
+Copyright 2014 jQuery Foundation and other contributors, https://jquery.org/
+
+backbone 1.1.2, a javascript library.
+Copyright (c) 2010-2014 Jeremy Ashkenas, DocumentCloud.
+
+moment.js 2.10.3, a front end time conversion project.
+Copyright (c) 2011-2015 Tim Wood, Iskren Chernev, Moment.js contributors.
+
+CMP v10 is an implementation of the MessagePack serialization format in C.
+Copyright (c) 2014 Charles Gunyon
+
diff --git a/NOTICE.txt b/NOTICE.txt
index 4c07950..3bceaaa 100644
--- a/NOTICE.txt
+++ b/NOTICE.txt
@@ -1,5 +1,5 @@
Apache HTrace
-Copyright 2016 The Apache Software Foundation
+Copyright 2017 The Apache Software Foundation
This product includes software developed at The Apache Software
Foundation (http://www.apache.org/).
diff --git a/README.md b/README.md
index 7b11dab..36f1db9 100644
--- a/README.md
+++ b/README.md
@@ -25,5 +25,12 @@
For details about integrating HTrace into an application, see the [developer
guide](./src/main/site/markdown/developer_guide.md)
+If you have an idea or a patch to improve HTrace, file a [JIRA issue at the bug
+tracker] (https://issues.apache.org/jira/browse/htrace) or post to our [mailing
+list] (http://htrace.incubator.apache.org/mail-lists.html).
+
+<b>NOTE</b>: Please create a JIRA issue for each pull request. If you just create a
+pull request but no JIRA, we might not notice your patch!
+
See the [release guide](./src/main/site/markdown/building.md) for
information about making an HTrace release.
diff --git a/htrace-c/pom.xml b/htrace-c/pom.xml
index d624ef8..f20489a 100644
--- a/htrace-c/pom.xml
+++ b/htrace-c/pom.xml
@@ -24,7 +24,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
@@ -104,6 +104,15 @@
</plugin>
</plugins>
</build>
+ <dependencies>
+ <!-- Module deps. -->
+ <dependency>
+ <groupId>org.apache.htrace</groupId>
+ <artifactId>htrace-htraced</artifactId>
+ <version>${project.version}</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
</profile>
</profiles>
</project>
diff --git a/htrace-c/src/core/htrace.h b/htrace-c/src/core/htrace.h
index 03c02bb..7357d4c 100644
--- a/htrace-c/src/core/htrace.h
+++ b/htrace-c/src/core/htrace.h
@@ -20,6 +20,7 @@
#define APACHE_HTRACE_HTRACE_H
#include <stdint.h> /* for uint64_t, etc. */
+#include <unistd.h> /* for size_t, etc. */
/**
* The public API for the HTrace C client.
@@ -169,6 +170,11 @@
*/
#define HTRACE_PROB_SAMPLER_FRACTION_KEY "prob.sampler.fraction"
+/**
+ * The length of an HTrace span ID in hexadecimal string form.
+ */
+#define HTRACE_SPAN_ID_STRING_LENGTH 32
+
// Forward declarations
struct htrace_conf;
struct htracer;
@@ -342,6 +348,83 @@
*/
void htrace_scope_close(struct htrace_scope *scope);
+ /**
+ * The HTrace span id.
+ */
+ struct htrace_span_id {
+ uint64_t high;
+ uint64_t low;
+ };
+
+ /**
+ * Set a span ID to the invalid span ID by clearing it.
+ *
+ * @param id The span ID to clear.
+ */
+ void htrace_span_id_clear(struct htrace_span_id *id);
+
+ /**
+ * Compare two span IDs.
+ *
+ * @param a The first span ID.
+ * @param b The second span ID.
+ *
+ * @return A number less than 0 if the first span ID is less;
+ * A number greater than 0 if the first span ID is greater;
+ * 0 if the span IDs are equal.
+ */
+ int htrace_span_id_compare(const struct htrace_span_id *a,
+ const struct htrace_span_id *b);
+
+ /**
+ * Parse a string containing an HTrace span ID.
+ *
+ * @param id The HTrace span ID to fill in.
+ * @param str The string to parse.
+ * @param err (out parameter) a buffer into which we will
+ * write an error message, if parsing fails.
+ * If this is unchanged, there was no error.
+ * @param err_len The length of the err buffer.
+ *
+ */
+ void htrace_span_id_parse(struct htrace_span_id *id, const char *str,
+ char *err, size_t err_len);
+
+ /**
+ * Write an HTrace span ID to a string.
+ *
+ * @param id The HTrace span ID.
+ * @param str Where to put the string.
+ * @param len The length of the string buffer.
+ *
+ * @return 1 on success; 0 if the length was not long enough, or
+ * there was an internal snprintf error.
+ */
+ int htrace_span_id_to_str(const struct htrace_span_id *id,
+ char *str, size_t len);
+
+ /**
+ * Copy an htrace span ID.
+ *
+ * dst and src can be the same.
+ *
+ * @param dst The destination span ID.
+ * @param src The source span ID.
+ */
+ void htrace_span_id_copy(struct htrace_span_id *dst,
+ const struct htrace_span_id *src);
+
+ /**
+ * Get the span id of an HTrace scope.
+ *
+ * @param scope The trace scope, or NULL.
+ * @param id (out param) The htrace span ID object to modify.
+ * It will be set to the invalid span ID if the scope
+ * is null or has no span.
+ */
+ void htrace_scope_get_span_id(const struct htrace_scope *scope,
+ struct htrace_span_id *id);
+
#pragma GCC visibility pop // End publicly visible symbols
#ifdef __cplusplus
diff --git a/htrace-c/src/core/htrace.hpp b/htrace-c/src/core/htrace.hpp
index 0378c57..6f6a398 100644
--- a/htrace-c/src/core/htrace.hpp
+++ b/htrace-c/src/core/htrace.hpp
@@ -49,6 +49,109 @@
class Scope;
class Tracer;
+ class SpanId {
+ public:
+ SpanId() {
+ id_.low = 0;
+ id_.high = 0;
+ }
+
+ SpanId(uint64_t high, uint64_t low) {
+ id_.high = high;
+ id_.low = low;
+ }
+
+ SpanId(const struct htrace_span_id *other) {
+ id_.high = other->high;
+ id_.low = other->low;
+ }
+
+ SpanId(const SpanId &other) {
+ id_.high = other.id_.high;
+ id_.low = other.id_.low;
+ }
+
+ /**
+ * Convert an input string into a span id.
+ *
+ * @param input The input string.
+ *
+ * @return The empty string, if parsing was successful. A
+ * failure error message, if parsing failed.
+ * If parsing is successful the current ID object
+ * will be modified.
+ */
+ std::string FromString(const std::string &input) {
+ char err[512];
+ err[0] = '\0';
+ htrace_span_id_parse(&id_, input.c_str(), err, sizeof(err));
+ if (err[0]) {
+ return std::string(err);
+ }
+ return "";
+ }
+
+ SpanId &operator=(const SpanId &other) {
+ id_.high = other.id_.high;
+ id_.low = other.id_.low;
+ return *this;
+ }
+
+ bool operator<(const SpanId &other) const {
+ return (htrace_span_id_compare(&id_, &other.id_) < 0);
+ }
+
+ bool operator==(const SpanId &other) const {
+ return ((id_.high == other.id_.high) &&
+ (id_.low == other.id_.low));
+ }
+
+ bool operator!=(const SpanId &other) const {
+ return (!((*this) == other));
+ }
+
+ uint64_t GetHigh() {
+ return id_.high;
+ }
+
+ void SetHigh(uint64_t high) {
+ id_.high = high;
+ }
+
+ uint64_t GetLow() {
+ return id_.low;
+ }
+
+ void SetLow(uint64_t low) {
+ id_.low = low;
+ }
+
+ void Clear() {
+ htrace_span_id_clear(&id_);
+ }
+
+ /**
+ * Convert the SpanId to a human-readable string.
+ */
+ std::string ToString() const {
+ char str[HTRACE_SPAN_ID_STRING_LENGTH + 1];
+ if (!htrace_span_id_to_str(&id_, str, sizeof(str))) {
+ // This should not happen, because the buffer we supplied is long
+ // enough.
+ return "(error converting ID to string)";
+ }
+ return std::string(str);
+ }
+
+ private:
+ struct htrace_span_id id_;
+ };
+
+ std::ostream &operator<<(std::ostream &oss, const SpanId &spanId) {
+ oss << spanId.ToString();
+ return oss;
+ }
+
/**
* An HTrace Configuration object.
*
@@ -221,6 +324,12 @@
scope_ = NULL;
}
+ SpanId GetSpanId() const {
+ htrace_span_id id;
+ htrace_scope_get_span_id(scope_, &id);
+ return SpanId(&id);
+ }
+
private:
friend class Tracer;
Scope(htrace::Scope &other); // Can't copy
diff --git a/htrace-c/src/core/scope.h b/htrace-c/src/core/scope.h
index 9f00b13..6d914b7 100644
--- a/htrace-c/src/core/scope.h
+++ b/htrace-c/src/core/scope.h
@@ -55,17 +55,6 @@
struct htrace_span *span;
};
-/**
- * Get the span id of an HTrace scope.
- *
- * @param scope The trace scope, or NULL.
- * @param id (out param) The htrace span ID object to modify.
- * It will be set to the invalid span ID if the scope
- * is null or has no span.
- */
-void htrace_scope_get_span_id(const struct htrace_scope *scope,
- struct htrace_span_id *id);
-
#endif
// vim: ts=4:sw=4:et
diff --git a/htrace-c/src/core/span.c b/htrace-c/src/core/span.c
index 44f4e6c..b7ca87a 100644
--- a/htrace-c/src/core/span.c
+++ b/htrace-c/src/core/span.c
@@ -16,6 +16,7 @@
* limitations under the License.
*/
+#include "core/htrace.h"
#include "core/span.h"
#include "receiver/receiver.h"
#include "sampler/sampler.h"
diff --git a/htrace-c/src/core/span.h b/htrace-c/src/core/span.h
index d6fbeb5..b3a79a0 100644
--- a/htrace-c/src/core/span.h
+++ b/htrace-c/src/core/span.h
@@ -27,6 +27,7 @@
* This is an internal header, not intended for external use.
*/
+#include "core/htrace.h" /* for struct span_id */
#include "core/span_id.h"
#include <stdint.h>
diff --git a/htrace-c/src/core/span_id.c b/htrace-c/src/core/span_id.c
index 7ea23eb..9c4acae 100644
--- a/htrace-c/src/core/span_id.c
+++ b/htrace-c/src/core/span_id.c
@@ -16,6 +16,7 @@
* limitations under the License.
*/
+#include "core/htrace.h"
#include "core/span_id.h"
#include "util/cmp.h"
#include "util/log.h"
diff --git a/htrace-c/src/core/span_id.h b/htrace-c/src/core/span_id.h
index af2e725..8f21bda 100644
--- a/htrace-c/src/core/span_id.h
+++ b/htrace-c/src/core/span_id.h
@@ -34,11 +34,6 @@
struct random_src;
/**
- * Length of an HTrace span ID in hexadecimal string form.
- */
-#define HTRACE_SPAN_ID_STRING_LENGTH 32
-
-/**
* The number of bytes in the HTrace span ID
*/
#define HTRACE_SPAN_ID_NUM_BYTES 16
@@ -49,50 +44,6 @@
extern const struct htrace_span_id INVALID_SPAN_ID;
/**
- * The HTrace span id.
- */
-struct htrace_span_id {
- uint64_t high;
- uint64_t low;
-};
-
-/**
- * Parse a string containing an HTrace span ID.
- *
- * @param id The HTrace span ID to fill in.
- * @param str The string to parse.
- *
- */
-void htrace_span_id_parse(struct htrace_span_id *id, const char *str,
- char *err, size_t err_len);
-
-/**
- * Write an HTrace span ID to a string.
- *
- * @param id The HTrace span ID.
- * @param str Where to put the string.
- * @param len The length of the string buffer.
- * @param err The error buffer to be set on failure.
- * @param err_len Length of the error buffer.
- *
- * @return 1 on success; 0 if the length was not long enough, or
- * there was an internal snprintf error.
- */
-int htrace_span_id_to_str(const struct htrace_span_id *id,
- char *str, size_t len);
-
-/**
- * Copy an htrace span ID.
- *
- * dst and src can be the same.
- *
- * @param dst The destination span ID.
- * @param src The source span ID.
- */
-void htrace_span_id_copy(struct htrace_span_id *dst,
- const struct htrace_span_id *src);
-
-/**
* Write this span ID to the provided CMP context.
*
* @param span The span.
@@ -124,26 +75,6 @@
void htrace_span_id_generate(struct htrace_span_id *id, struct random_src *rnd,
const struct htrace_span_id *parent);
-/**
- * Set a span ID to the invalid span ID by clearing it.
- *
- * @param id The span ID to clear.
- */
-void htrace_span_id_clear(struct htrace_span_id *id);
-
-/**
- * Compare two span IDs.
- *
- * @param a The first span ID.
- * @param b The second span ID.
- *
- * @return A number less than 0 if the first span ID is less;
- * A number greater than 0 if the first span ID is greater;
- * 0 if the span IDs are equal.
- */
-int htrace_span_id_compare(const struct htrace_span_id *a,
- const struct htrace_span_id *b);
-
#endif
// vim: ts=4:sw=4:et
diff --git a/htrace-c/src/test/linkage-unit.c b/htrace-c/src/test/linkage-unit.c
index bba73e1..f3e4caf 100644
--- a/htrace-c/src/test/linkage-unit.c
+++ b/htrace-c/src/test/linkage-unit.c
@@ -48,7 +48,13 @@
"htrace_start_span",
"htracer_create",
"htracer_free",
- "htracer_tname"
+ "htracer_tname",
+ "htrace_span_id_clear",
+ "htrace_span_id_compare",
+ "htrace_span_id_parse",
+ "htrace_span_id_to_str",
+ "htrace_span_id_copy",
+ "htrace_scope_get_span_id",
};
#define PUBLIC_SYMS_SIZE (sizeof(PUBLIC_SYMS) / sizeof(PUBLIC_SYMS[0]))
diff --git a/htrace-c/src/test/span_id-unit.c b/htrace-c/src/test/span_id-unit.c
index 06c0320..ecdebfb 100644
--- a/htrace-c/src/test/span_id-unit.c
+++ b/htrace-c/src/test/span_id-unit.c
@@ -16,6 +16,7 @@
* limitations under the License.
*/
+#include "core/htrace.h"
#include "core/span_id.h"
#include "test/span_util.h"
#include "test/test.h"
diff --git a/htrace-core4/pom.xml b/htrace-core4/pom.xml
index 46adfda..e3165ce 100644
--- a/htrace-core4/pom.xml
+++ b/htrace-core4/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/ScheduledTraceExecutorService.java b/htrace-core4/src/main/java/org/apache/htrace/core/ScheduledTraceExecutorService.java
new file mode 100644
index 0000000..e783561
--- /dev/null
+++ b/htrace-core4/src/main/java/org/apache/htrace/core/ScheduledTraceExecutorService.java
@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+package org.apache.htrace.core;
+
+import java.util.concurrent.Callable;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A convenience wrapper around a {@link ScheduledExecutorService} for
+ * automatically propagating trace scopes to executable tasks.
+ * <p>
+ * Recurring tasks will use independent scopes per execution, but will all be
+ * tied to the same parent scope (if any).
+ */
+public class ScheduledTraceExecutorService extends TraceExecutorService
+ implements ScheduledExecutorService {
+ final ScheduledExecutorService impl;
+
+ ScheduledTraceExecutorService(Tracer tracer, String scopeName,
+ ScheduledExecutorService impl) {
+ super(tracer, scopeName, impl);
+ this.impl = impl;
+ }
+
+ @Override
+ public ScheduledFuture<?> schedule(Runnable command, long delay,
+ TimeUnit unit) {
+ return impl.schedule(wrap(command), delay, unit);
+ }
+
+ @Override
+ public <V> ScheduledFuture<V> schedule(Callable<V> callable, long delay,
+ TimeUnit unit) {
+ return impl.schedule(wrap(callable), delay, unit);
+ }
+
+ @Override
+ public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
+ long initialDelay, long period, TimeUnit unit) {
+ return impl.scheduleAtFixedRate(wrap(command), initialDelay, period, unit);
+ }
+
+ @Override
+ public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
+ long initialDelay, long delay, TimeUnit unit) {
+ return impl.scheduleWithFixedDelay(wrap(command), initialDelay, delay,
+ unit);
+ }
+
+}
diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/Span.java b/htrace-core4/src/main/java/org/apache/htrace/core/Span.java
index 4399259..ddc5385 100644
--- a/htrace-core4/src/main/java/org/apache/htrace/core/Span.java
+++ b/htrace-core4/src/main/java/org/apache/htrace/core/Span.java
@@ -88,6 +88,7 @@
/**
* Create a child span of this span with the given description
* @deprecated Since 4.0.0. Use {@link MilliSpan.Builder}
+ * @param description The description to set on the child span.
* @return A new child span.
*/
@Deprecated
diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/TraceExecutorService.java b/htrace-core4/src/main/java/org/apache/htrace/core/TraceExecutorService.java
index 81e31ea..592f354 100644
--- a/htrace-core4/src/main/java/org/apache/htrace/core/TraceExecutorService.java
+++ b/htrace-core4/src/main/java/org/apache/htrace/core/TraceExecutorService.java
@@ -26,6 +26,10 @@
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
+/**
+ * A convenience wrapper around an {@link ExecutorService} for automatically
+ * propagating trace scopes to executable tasks.
+ */
public class TraceExecutorService implements ExecutorService {
private final Tracer tracer;
private final String scopeName;
@@ -40,7 +44,7 @@
@Override
public void execute(Runnable command) {
- impl.execute(tracer.wrap(command, scopeName));
+ impl.execute(wrap(command));
}
@Override
@@ -71,24 +75,38 @@
@Override
public <T> Future<T> submit(Callable<T> task) {
- return impl.submit(tracer.wrap(task, scopeName));
+ return impl.submit(wrap(task));
}
@Override
public <T> Future<T> submit(Runnable task, T result) {
- return impl.submit(tracer.wrap(task, scopeName), result);
+ return impl.submit(wrap(task), result);
}
@Override
public Future<?> submit(Runnable task) {
- return impl.submit(tracer.wrap(task, scopeName));
+ return impl.submit(wrap(task));
+ }
+
+ /*
+ * Intended for internal use only.
+ */
+ Runnable wrap(Runnable runnable) {
+ return tracer.wrap(runnable, scopeName);
+ }
+
+ /*
+ * Intended for internal use only.
+ */
+ <V> Callable<V> wrap(Callable<V> callable) {
+ return tracer.wrap(callable, scopeName);
}
private <T> Collection<? extends Callable<T>> wrapCollection(
Collection<? extends Callable<T>> tasks) {
List<Callable<T>> result = new ArrayList<Callable<T>>();
for (Callable<T> task : tasks) {
- result.add(tracer.wrap(task, scopeName));
+ result.add(wrap(task));
}
return result;
}
diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/TraceRunnable.java b/htrace-core4/src/main/java/org/apache/htrace/core/TraceRunnable.java
index ad5b36a..871d83b 100644
--- a/htrace-core4/src/main/java/org/apache/htrace/core/TraceRunnable.java
+++ b/htrace-core4/src/main/java/org/apache/htrace/core/TraceRunnable.java
@@ -26,6 +26,10 @@
private final String description;
/**
+ * @param tracer The Tracer to use for tracing.
+ * @param parent The TraceScope to read parent span ID from.
+ * @param runnable The Runnable that will be executed.
+ * @param description An optional description to set on the trace when executing.
* @deprecated Use {@link #TraceRunnable(Tracer, SpanId, Runnable, String)} instead.
*/
@Deprecated
diff --git a/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java b/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java
index f78e0a0..0ca4d1d 100644
--- a/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java
+++ b/htrace-core4/src/main/java/org/apache/htrace/core/Tracer.java
@@ -25,6 +25,7 @@
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutorService;
+import java.util.concurrent.ScheduledExecutorService;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
@@ -474,6 +475,16 @@
return new TraceExecutorService(this, scopeName, impl);
}
+ public ScheduledTraceExecutorService newTraceExecutorService(
+ ScheduledExecutorService impl) {
+ return newTraceExecutorService(impl, null);
+ }
+
+ public ScheduledTraceExecutorService newTraceExecutorService(
+ ScheduledExecutorService impl, String scopeName) {
+ return new ScheduledTraceExecutorService(this, scopeName, impl);
+ }
+
public TracerPool getTracerPool() {
if (tracerPool == null) {
throwClientError(toString() + " is closed.");
diff --git a/htrace-core4/src/test/java/org/apache/htrace/core/TestNewScopeWithParentID.java b/htrace-core4/src/test/java/org/apache/htrace/core/TestNewScopeWithParentID.java
new file mode 100644
index 0000000..50eda78
--- /dev/null
+++ b/htrace-core4/src/test/java/org/apache/htrace/core/TestNewScopeWithParentID.java
@@ -0,0 +1,60 @@
+/*
+ * 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.
+ */
+
+package org.apache.htrace.core;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.util.HashMap;
+
+public class TestNewScopeWithParentID {
+
+ @Test
+ public void testNewScopeWithParentID() throws Exception {
+
+ Tracer tracer = new Tracer.Builder().
+ name("testNewScopeWithParentID").
+ tracerPool(new TracerPool("testNewScopeWithParentID")).
+ conf(HTraceConfiguration.fromKeyValuePairs(
+ "sampler.classes", "AlwaysSampler")).build();
+ TraceScope activeScope = tracer.newScope("CurrentActiveScope");
+ HashMap<Integer,SpanId> spanIdHashMap = new HashMap<>();
+ SpanId parentID = new SpanId(100L, 200L);
+ spanIdHashMap.put(activeScope.getSpanId().hashCode(),activeScope.getSpanId());
+ spanIdHashMap.put(parentID.hashCode(),parentID);
+ TraceScope childScope = tracer.
+ newScope("ChildScope", parentID);
+ Assert.assertNotNull(childScope);
+ Assert.assertEquals(childScope.getSpan().getParents().length, 2);
+ //parent on index 0
+ Assert.assertNotNull(spanIdHashMap.get(childScope.getSpan().getParents()[0].hashCode()));
+ Assert.assertEquals(childScope.getSpan().getParents()[0].getHigh(),
+ spanIdHashMap.get(childScope.getSpan().getParents()[0].hashCode()).getHigh());
+ Assert.assertEquals(childScope.getSpan().getParents()[0].getLow(),
+ spanIdHashMap.get(childScope.getSpan().getParents()[0].hashCode()).getLow());
+ //parent on index 1
+ Assert.assertNotNull(spanIdHashMap.get(childScope.getSpan().getParents()[1].hashCode()));
+ Assert.assertEquals(childScope.getSpan().getParents()[1].getHigh(),
+ spanIdHashMap.get(childScope.getSpan().getParents()[1].hashCode()).getHigh());
+ Assert.assertEquals(childScope.getSpan().getParents()[1].getLow(),
+ spanIdHashMap.get(childScope.getSpan().getParents()[1].hashCode()).getLow());
+ childScope.close();
+ activeScope.close();
+
+ }
+}
diff --git a/htrace-core4/src/test/java/org/apache/htrace/core/TestTraceExecutor.java b/htrace-core4/src/test/java/org/apache/htrace/core/TestTraceExecutor.java
index dbdd27c..1bd18f7 100644
--- a/htrace-core4/src/test/java/org/apache/htrace/core/TestTraceExecutor.java
+++ b/htrace-core4/src/test/java/org/apache/htrace/core/TestTraceExecutor.java
@@ -17,15 +17,23 @@
package org.apache.htrace.core;
import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashSet;
import java.util.concurrent.Callable;
+import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicReference;
+import org.apache.htrace.core.Tracer.Builder;
import org.junit.Test;
public class TestTraceExecutor {
@@ -88,6 +96,64 @@
}
}
+ @Test
+ public void testScheduledExecutor() throws Exception {
+ final int TASK_COUNT = 3;
+ final int DELAY = 500;
+
+ HTraceConfiguration conf = HTraceConfiguration.fromKeyValuePairs(
+ Tracer.SAMPLER_CLASSES_KEY, AlwaysSampler.class.getName());
+
+ ScheduledExecutorService ses = null;
+ Builder builder = new Tracer.Builder("TestTraceExecutor").conf(conf);
+ try (Tracer tracer = builder.build()) {
+ final ThreadFactory tf = new NamingThreadFactory();
+ ses = Executors.newScheduledThreadPool(TASK_COUNT, tf);
+ ses = tracer.newTraceExecutorService(ses);
+
+ final CountDownLatch startLatch = new CountDownLatch(TASK_COUNT);
+ final CountDownLatch continueLatch = new CountDownLatch(1);
+ Callable<String> task = new Callable<String>() {
+ @Override
+ public String call() throws InterruptedException {
+ startLatch.countDown();
+ // Prevent any task from exiting until every task has started
+ assertTrue(continueLatch.await(WAIT_TIME_SECONDS, TimeUnit.SECONDS));
+ // Annotate on the presumed child trace
+ Tracer.getCurrentSpan().addTimelineAnnotation(
+ Thread.currentThread().getName());
+ return Tracer.getCurrentSpan().getDescription();
+ }
+ };
+
+ try (TraceScope scope = tracer.newScope("TestRunnable")) {
+ Collection<Future<String>> futures = new ArrayList<>();
+
+ for (int i = 0; i < TASK_COUNT; i++) {
+ futures.add(ses.schedule(task, DELAY, TimeUnit.MILLISECONDS));
+ }
+
+ // Wait for all tasks to start
+ assertTrue(startLatch.await(WAIT_TIME_SECONDS, TimeUnit.SECONDS));
+ continueLatch.countDown();
+ // Collect the expected results
+ Collection<String> results = new HashSet<>();
+ for (Future<String> future : futures) {
+ results.add(future.get(WAIT_TIME_SECONDS, TimeUnit.SECONDS));
+ }
+
+ assertTrue("Timeline Annotations should have gone to child traces.",
+ Tracer.getCurrentSpan().getTimelineAnnotations().isEmpty());
+ assertEquals("Duplicated child span descriptions.", TASK_COUNT,
+ results.size());
+ }
+ } finally {
+ if (ses != null) {
+ ses.shutdown();
+ }
+ }
+ }
+
/*
* Inspired by org.apache.solr.util.DefaultSolrThreadFactory
*/
diff --git a/htrace-flume/pom.xml b/htrace-flume/pom.xml
index f82c89d..8238410 100644
--- a/htrace-flume/pom.xml
+++ b/htrace-flume/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
diff --git a/htrace-hbase/pom.xml b/htrace-hbase/pom.xml
index 8af516c..fdce60f 100644
--- a/htrace-hbase/pom.xml
+++ b/htrace-hbase/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
@@ -130,6 +130,16 @@
<artifactId>htrace-core4</artifactId>
<version>${project.version}</version>
<classifier>tests</classifier>
+ <exclusions>
+ <exclusion>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-core</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ </exclusion>
+ </exclusions>
<scope>test</scope>
</dependency>
<dependency>
diff --git a/htrace-htraced/pom.xml b/htrace-htraced/pom.xml
index e7831fc..a981ca7 100644
--- a/htrace-htraced/pom.xml
+++ b/htrace-htraced/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
diff --git a/htrace-webapp/pom.xml b/htrace-webapp/pom.xml
index a7d156b..d868397 100644
--- a/htrace-webapp/pom.xml
+++ b/htrace-webapp/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
diff --git a/htrace-zipkin/pom.xml b/htrace-zipkin/pom.xml
index b7ce61e..f272e7e 100644
--- a/htrace-zipkin/pom.xml
+++ b/htrace-zipkin/pom.xml
@@ -18,7 +18,7 @@
<parent>
<artifactId>htrace</artifactId>
<groupId>org.apache.htrace</groupId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
@@ -219,7 +219,7 @@
<id>doclint-disable</id>
<activation><jdk>[1.8,)</jdk></activation>
<properties>
- <additionalparam>-Xdoclint:none</additionalparam>
+ <additionalparam>-Xdoclint:all,-Xdoclint:-missing</additionalparam>
</properties>
</profile>
</profiles>
diff --git a/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java b/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java
index 0fc7920..17886c5 100644
--- a/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java
+++ b/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java
@@ -103,11 +103,11 @@
* Here is a little ascii art which shows the above transformation:
* <pre>
* +------------+ +------------+ +------------+ +-----------------+
- * | HTrace Span|-->|Zipkin Span |-->| (LogEntry) | ===========> | Zipkin Collector|
+ * | HTrace Span|-->|Zipkin Span |-->| (LogEntry) | ===========> | Zipkin Collector|
* +------------+ +------------+ +------------+ (Scribe RPC) +-----------------+
* </pre>
* @param spans to be sent. The raw bytes are being sent.
- * @throws IOException
+ * @throws IOException if there is a problem sending the span entries
*/
@Override
public void send(List<byte[]> spans) throws IOException {
diff --git a/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java b/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java
index 2dfe5a6..da7027f 100644
--- a/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java
+++ b/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java
@@ -51,7 +51,7 @@
/**
* Zipkin is an open source tracing library. This span receiver acts as a bridge between HTrace and
* Zipkin, that converts HTrace Span objects into Zipkin Span objects.
- * <p/>
+ * <p>
* HTrace spans are queued into a blocking queue. From there background worker threads will
* batch the spans together and then send them through to a Zipkin collector.
*
@@ -338,10 +338,10 @@
/**
* Close the receiver.
- * <p/>
+ * <p>
* This tries to shut
*
- * @throws IOException
+ * @throws IOException This implementation will not throw an {@link IOException}.
*/
@Override
public void close() throws IOException {
diff --git a/htrace-zipkin/src/main/java/org/apache/htrace/zipkin/HTraceToZipkinConverter.java b/htrace-zipkin/src/main/java/org/apache/htrace/zipkin/HTraceToZipkinConverter.java
index dc4e9bc..5b23032 100644
--- a/htrace-zipkin/src/main/java/org/apache/htrace/zipkin/HTraceToZipkinConverter.java
+++ b/htrace-zipkin/src/main/java/org/apache/htrace/zipkin/HTraceToZipkinConverter.java
@@ -27,6 +27,7 @@
import org.apache.htrace.core.TimelineAnnotation;
import java.io.UnsupportedEncodingException;
+import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
@@ -36,15 +37,15 @@
* This class is responsible for converting a HTrace.Span to a Zipkin.Span object. To use the Zipkin
* infrastructure (collector, front end), we need to store the Span information in a zipkin specific
* format. This class transforms a HTrace:Span object to a Zipkin:Span object.
- * <p/>
+ * <p>
* This is how both Span objects are related:
- * <table>
- * <col width="50%"/> <col width="50%"/> <thead>
+ * <table summary="Mapping between HTrace and Zipkin Span opbjects.">
+ * <thead>
* <tr>
- * <th>HTrace:Span</th>
- * <th>Zipkin:Span</th>
+ * <th style="width: 50%">HTrace:Span</th>
+ * <th style="width: 50%">Zipkin:Span</th>
* </tr>
- * <thead> <tbody>
+ * </thead> <tbody>
* <tr>
* <td>TraceId</td>
* <td>TraceId</td>
@@ -71,7 +72,6 @@
* </tr>
* </tbody>
* </table>
- * <p/>
*/
public class HTraceToZipkinConverter {
private static final Log LOG = LogFactory.getLog(HTraceToZipkinConverter.class);
@@ -154,13 +154,9 @@
List<BinaryAnnotation> l = new ArrayList<BinaryAnnotation>();
for (Map.Entry<String, String> e : span.getKVAnnotations().entrySet()) {
BinaryAnnotation binaryAnn = new BinaryAnnotation();
- binaryAnn.setAnnotation_type(AnnotationType.BYTES);
+ binaryAnn.setAnnotation_type(AnnotationType.STRING);
binaryAnn.setKey(e.getKey());
- try {
- binaryAnn.setValue(e.getValue().getBytes("UTF-8"));
- } catch (UnsupportedEncodingException ex) {
- LOG.error("Error encoding string as UTF-8", ex);
- }
+ binaryAnn.setValue(e.getValue().getBytes(StandardCharsets.UTF_8));
binaryAnn.setHost(ep);
l.add(binaryAnn);
}
diff --git a/pom.xml b/pom.xml
index 879c8f1..86eab9a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -21,7 +21,7 @@
<groupId>org.apache.htrace</groupId>
<artifactId>htrace</artifactId>
- <version>4.2.0-incubating-SNAPSHOT</version>
+ <version>4.3.0-incubating-SNAPSHOT</version>
<packaging>pom</packaging>
<name>Apache HTrace</name>
<description>A distributed tracing framework.</description>
@@ -38,14 +38,6 @@
<module>htrace-kudu</module>
</modules>
- <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>
diff --git a/src/main/site/markdown/building.md b/src/main/site/markdown/building.md
index afa7e4e..d182b4e 100644
--- a/src/main/site/markdown/building.md
+++ b/src/main/site/markdown/building.md
@@ -55,9 +55,9 @@
git checkout -b 4.0
-Create the release tag via git
+Create an annotated (signed) release tag via git.
- git tag -s 4.0.0RC0 -m '4.0 release candidate 0' -u 9CD4D9D3
+ git tag -s 4.0.0RC0 -m '4.0.0 release candidate 0'
For some reason, I get a message about needing a password. But no password
is actually asked for. Perhaps it is supplied by the window manager via its
@@ -70,9 +70,15 @@
Upload the build to Sonatype's servers.
git clean -fdqx .
- mvn clean deploy -Psign,src,dist -DskipTests
+ mvn clean deploy -Pdist -DskipTests
+
+The above referenced profiles are not in the htrace profile but in the
+parent apache profile. Here is a pointer to the parent profile:
+[Apache-18.pom](https://repository.apache.org/service/local/repo_groups/public/content/org/apache/apache/18/apache-18.pom)
This will take a while because it needs to upload to the servers.
+It will ask you for your key password unless you set up a
+gpg-agent for your local session.
Log into repository.apache.org and go to
https://repository.apache.org/#stagingRepositories
@@ -85,15 +91,16 @@
Generate the side files.
- gpg --print-mds /home/cmccabe/src/htrace2d/target/htrace-4.0.0-incubating-src.tar.gz > \
- /home/cmccabe/src/htrace2d/target/htrace-4.0.0-incubating-src.tar.gz.mds
- gpg --armor --output /home/cmccabe/src/htrace2d/target/htrace-4.0.0-incubating-src.tar.gz.asc \
- --detach-sig /home/cmccabe/src/htrace2d/target/htrace-4.0.0-incubating-src.tar.gz
+ cd target
+ gpg --print-mds htrace-4.0.0-incubating-src.tar.gz htrace-4.0.0-incubating-src.tar.gz.mds
+ gpg --armor --output htrace-4.0.0-incubating-src.tar.gz.asc \
+ --detach-sign htrace-4.0.0-incubating-src.tar.gz
-rsync up to your public_html directory in people.apache.org.
+sftp up to your public_html directory in home.apache.org
- rsync -avi /home/cmccabe/src/htrace2d/target/htrace-4.0.0-incubating-src.tar.* \
- people.apache.org:~/public_html/htrace/releases/4.0.0
+ cd target
+ echo 'put htrace-4.0.0-incubating-src.tar.gz*' | \
+ sftp home.apache.org:public_html/htrace-4.2.0-incubating-rc0
Generate release notes via JIRA at
https://issues.apache.org/jira/browse/HTRACE/
diff --git a/src/main/site/markdown/configuration.md b/src/main/site/markdown/configuration.md
new file mode 100644
index 0000000..f501784
--- /dev/null
+++ b/src/main/site/markdown/configuration.md
@@ -0,0 +1,158 @@
+<!---
+ Licensed 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. See accompanying LICENSE file.
+-->
+
+# HTrace Configuration
+
+Clearly, HTrace requires configuration. We need to control which SpanReceiver
+is used, what the sampling rate is, and many other things besides. Luckily, as
+we discussed earlier, the Tracer objects maintain this configuration
+information for us. When we ask for a new trace scope, the Tracer knows what
+configuration to use.
+
+This configuration comes from the HTraceConfiguration object that we supplied
+to the Tracer#Builder earlier. In general, we want to configure HTrace the
+same way we configure anything else in our distributed system. So we normally
+create a subclass of HTraceConfiguration that accesses the appropriate
+information in our existing configuration system.
+
+To make this a little more concrete, let`s suppose we are writing Bob`s
+Distributed System. Being a pragmatic (not to mention lazy) guy, Bob has
+decided to just use Java configuration properties for configuration.
+So our Tracer#Builder invoation would look something like this:
+
+ this.tracer = new Tracer.Builder("Bob").
+ conf(new HTraceConfiguration() {
+ @Override
+ public String get(String key) {
+ return System.getProperty("htrace." + key);
+ }
+
+ @Override
+ public String get(String key, String defaultValue) {
+ String ret = get(key);
+ return (ret != null) ? ret : defaultValue;
+ }
+ }).
+ build();
+
+You can see that this configuration object maps every property starting in
+"htrace." to an htrace property. So, for example, you would set the Java
+system property value "htrace.span.receiver.classes" in order to control the
+HTrace configuration key "span.receiver.classes".
+
+Of course, Bob probably should have been less lazy, and used a real
+configuration system instead of using Java system properties. This is just a
+toy example to illustrate how to integrate with an existing configuration
+system.
+
+Bob might also have wanted to use different prefixes for different Tracer
+objects. For example, in Hadoop you can configure the FsShell Tracer
+separately from the NameNode Tracer, by setting
+"fs.shell.htrace.span.receiver.classes". This is easy to control by changing
+the HTraceConfiguration object that you pass to Tracer#Builder.
+
+Note that in C and C++, this system is a little different, based on explicitly
+creating a configuration object prior to creating a tracer, rather than using a
+callback-based system.
+
+##Configuration Keys
+In the tables below, programmatic Htrace Java configuration is split by module.
+
+###htrace-core4 configuration
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| span.receiver.classes | | A [SpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/SpanReceiver.java) is a collector within a process that is the destination of Spans when a trace is running. The value should be a comma separated list of classes which extend the abstract SpanReceiver class | yes | [org.apache.htrace.core.StandardOutSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/StandardOutSpanReceiver.java), [org.apache.htrace.core.LocalFileSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/LocalFileSpanReceiver.java), [org.apache.htrace.core.POJOSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/POJOSpanReceiver.java), [org.apache.htrace.impl.FlumeSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-flume/src/main/java/org/apache/htrace/impl/FlumeSpanReceiver.java), [org.apache.htrace.impl.HBaseSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-hbase/src/main/java/org/apache/htrace/impl/HBaseSpanReceiver.java), [org.apache.htrace.impl.HTracedSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-htraced/src/main/java/org/apache/htrace/impl/HTracedSpanReceiver.java), [org.apache.htrace.impl.ZipkinSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java)|
+| sampler.classes | | Samplers which extend the [Sampler](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/Sampler.java) class determine the frequency that an action should be performed.| yes | [org.apache.htrace.core.AlwaysSampler](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/AlwaysSampler.java), [org.apache.htrace.core.CountSampler](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/CountSampler.java), [org.apache.htrace.core.NeverSampler](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/NeverSampler.java), [org.apache.htrace.core.ProbabilitySampler](https://github.com/apache/incubator-htrace/blob/master/htrace-core4/src/main/java/org/apache/htrace/core/ProbabilitySampler.java) |
+
+###htrace-htraced configuration
+
+Configuration for the [org.apache.htrace.impl.HTracedSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-htraced/src/main/java/org/apache/htrace/impl/HTracedSpanReceiver.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| ---------- |:-------------:| :---------: | :-------: | :-------------: |
+| htraced.receiver.address | | Address of the htraced server | yes | an established server and port address |
+| htraced.receiver.io.timeout.ms | 60000 | The minimum number of milliseconds to wait for a read or write operation on the network. | no | single integer |
+| htraced.receiver.connect.timeout.ms | 60000 | The minimum number of milliseconds to wait for a network connection attempt. | no | single integer |
+| htraced.receiver.idle.timeout.ms | 60000 | The minimum number of milliseconds to keep alive a connection when it's not in use.| no | single integer |
+| htraced.flush.retry.delays.key | 1000,30000 | Configure the retry times to use when an attempt to flush spans to htraced fails. This is configured as a comma-separated list of delay times in milliseconds. If the configured value is empty, no retries will be made.| no | two comma separated integers |
+| htraced.receiver.max.flush.interval.ms | 60000 | The maximum length of time to go in between flush attempts. Once this time elapses, a flush will be triggered even if we don't have that many spans buffered. | no | single integer |
+| htraced.receiver.packed | true | Whether or not to use msgpack for span serialization. If this key is false, JSON over REST will be used. If this key is true, msgpack over custom RPC will be used.| no | true/false |
+| htraced.receiver.buffer.size | 16 * 1024 * 1024 | The size of the span buffers. | no | single integer no larger than 32 * 1024 * 1024 |
+| htraced.receiver.buffer.send.trigger.fraction | 0.5 | Set the fraction of the span buffer which needs to fill up before we will automatically trigger a flush. This is a fraction, not a percentage. It is between 0 and 1. | no | single double |
+| htraced.max.buffer.full.retry.ms.key | 5000 | The length of time which receiveSpan should wait for a free spot in a span buffer before giving up and dropping the span | no | single integer |
+| htraced.error.log.period.ms | 30000L | The length of time we should wait between displaying log messages on the rate-limited loggers. | no | single integer |
+| htraced.dropped.spans.log.path | Absolute path of System.getProperty("java.io.tmpdir", "/tmp") | Path to local disk at which spans should be writtent o disk | no | string path to local disk |
+| htraced.dropped.spans.log.max.size | 1024L * 1024L | The maximum size in bytes of a span log file on disk | no | single integer |
+
+###htrace-flume configuration
+
+Configuration for the [org.apache.htrace.impl.FlumeSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-flume/src/main/java/org/apache/htrace/impl/FlumeSpanReceiver.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| hadoop.htrace.flume.hostname | localhost | HTTP accessible host at which Flume is available | yes | single string |
+| hadoop.htrace.flume.port | 0 | Port on the host at which Flume is available | yes | single integer |
+| htrace.flume.num-threads | 1 | The number of threads used to write data from HTrace into Flume | no | single integer |
+| htrace.flume.batchsize | 100 | Number of HTrace spans to include in every batch sent to Flume | no | single integer |
+
+In addition, please also see the [htrace-flume documentation](https://github.com/apache/incubator-htrace/tree/master/htrace-flume)
+
+###htrace-hbase configuration
+
+Configuration for the [org.apache.htrace.impl.HBaseSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-hbase/src/main/java/org/apache/htrace/impl/HBaseSpanReceiver.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| hbase.htrace.hbase.collector-quorum | 127.0.0.1 | Host at which HBase Zookeeper server is running | no | string |
+| hbase.htrace.hbase.zookeeper.property.clientPort | 2181 | Port at which HBase Zookeeper server is running | no | single integer |
+| hbase.htrace.hbase.zookeeper.znode.parent | /hbase | The HBase root znode path | no | string |
+| htrace.hbase.num-threads | 1 | The number of threads used to write data from HTrace into HBase | no | single integer |
+| htrace.hbase.batch.size | 100 | Number of HTrace spans to include in every batch sent to HBase | no | single integer |
+| hbase.htrace.hbase.table | htrace | The HBase Table name | no | string |
+| hbase.htrace.hbase.columnfamily | s | The HBase column family name | no | string |
+| hbase.htrace.hbase.indexfamily | i | The Hbase index family name | no | string |
+
+In addition, please also see the [htrace-hbase documentation](https://github.com/apache/incubator-htrace/tree/master/htrace-hbase)
+
+###htrace-zipkin configuration
+
+Configuration for the [org.apache.htrace.impl.ZipkinSpanReceiver](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/ZipkinSpanReceiver.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| zipkin.transport.class | [org.apache.htrace.impl.ScribeTransport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java) | Implementation of [Transport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/Transport.java) to be used. | no | [org.apache.htrace.impl.ScribeTransport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java), [org.apache.htrace.impl.KafkaTransport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/KafkaTransport.java) |
+| zipkin.num-threads | 1 | The number of threads used to write data from HTrace into Zipkin | no | single integer |
+| zipkin.traced-service-hostname (Deprecated) | InetAddress.getLocalHost().getHostAddress() | the host on which Zipkin resides | no | string |
+| zipkin.traced-service-port (Deprecated) | -1 | The port on which the zipkin service is running | no | single integer |
+
+####Scribe (Thrift) Transport
+The following configuration relate to the [org.apache.htrace.impl.ScribeTransport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/ScribeTransport.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| zipkin.scribe.hostname | localhost | Host at which Scribe server is running | no | string |
+| zipkin.scribe.port | 9410 | Port at which Scribe server is running | no | single integer |
+
+####Kafka Transport
+The following configuration relate to the [org.apache.htrace.impl.KafkaTransport](https://github.com/apache/incubator-htrace/blob/master/htrace-zipkin/src/main/java/org/apache/htrace/impl/KafkaTransport.java)
+
+| Key | Default Value | Description | Mandatory | Possible Values |
+| --------------------- | :-----------: | :--------- : | :-------: | :-------------: |
+| zipkin.kafka.topic | zipkin | The Kafka [Topic](http://kafka.apache.org/documentation.html#intro_topics) to write HTrace data to | no | string |
+| zipkin.kafka.metadata.broker.list| localhost:9092 | Host and Port where the Kafka broker is running | no | Colon seperated Host:Port |
+| zipkin.kafka.request.required.acks | 0 | Number of acknowledgements required before a message has been written into Kafka | no | single integer |
+| zipkin.kafka.producer.type | async | Whether the Kafka [Producer](http://kafka.apache.org/documentation.html#theproducer) will send data in a [synchronous or asynchronous](http://kafka.apache.org/documentation.html#design_asyncsend) manner | no | async/sync |
+| zipkin.kafka.serializer.class | kafka.serializer.DefaultEncoder | Type of [Encoder](https://github.com/apache/kafka/blob/6eacc0de303e4d29e083b89c1f53615c1dfa291e/core/src/main/scala/kafka/serializer/Encoder.scala) to be used within the Producer | no | kafka.serializer.DefaultEncoder, kafka.serializer.NullEncoder, kafka.serializer.StringEncoder |
+| zipkin.kafka.compression.codec | 1 | Controls the [compression codec](https://cwiki.apache.org/confluence/display/KAFKA/Compression) to be used by the producer | no | O means no compression. 1 means GZIP compression. 2 means Snappy compression |
diff --git a/src/main/site/markdown/developer_guide.md b/src/main/site/markdown/developer_guide.md
index 20b832b..3eb04c7 100644
--- a/src/main/site/markdown/developer_guide.md
+++ b/src/main/site/markdown/developer_guide.md
@@ -236,57 +236,8 @@
libraries are needed.
## Configuration
-Clearly, HTrace requires configuration. We need to control which SpanReceiver
-is used, what the sampling rate is, and many other things besides. Luckily, as
-we discussed earlier, the Tracer objects maintain this configuration
-information for us. When we ask for a new trace scope, the Tracer knows what
-configuration to use.
-
-This configuration comes from the HTraceConfiguration object that we supplied
-to the Tracer#Builder earlier. In general, we want to configure HTrace the
-same way we configure anything else in our distributed system. So we normally
-create a subclass of HTraceConfiguration that accesses the appropriate
-information in our existing configuration system.
-
-To make this a little more concrete, let`s suppose we are writing Bob`s
-Distributed System. Being a pragmatic (not to mention lazy) guy, Bob has
-decided to just use Java configuration properties for configuration.
-So our Tracer#Builder invoation would look something like this:
-
- this.tracer = new Tracer.Builder("Bob").
- conf(new HTraceConfiguration() {
- @Override
- public String get(String key) {
- return System.getProperty("htrace." + key);
- }
-
- @Override
- public String get(String key, String defaultValue) {
- String ret = get(key);
- return (ret != null) ? ret : defaultValue;
- }
- }).
- build();
-
-You can see that this configuration object maps every property starting in
-"htrace." to an htrace property. So, for example, you would set the Java
-system property value "htrace.span.receiver.classes" in order to control the
-HTrace configuration key "span.receiver.classes".
-
-Of course, Bob probably should have been less lazy, and used a real
-configuration system instead of using Java system properties. This is just a
-toy example to illustrate how to integrate with an existing configuration
-system.
-
-Bob might also have wanted to use different prefixes for different Tracer
-objects. For example, in Hadoop you can configure the FsShell Tracer
-separately from the NameNode Tracer, by setting
-"fs.shell.htrace.span.receiver.classes". This is easy to control by changing
-the HTraceConfiguration object that you pass to Tracer#Builder.
-
-Note that in C and C++, this system is a little different, based on explicitly
-creating a configuration object prior to creating a tracer, rather than using a
-callback-based system.
+Please see the [configuration documentation](configuration.html),
+which also includes an entire table of key, value configuration options.
## TracerPool
SpanReceiver objects often need to make a network connection to a remote
diff --git a/src/main/site/markdown/index.md b/src/main/site/markdown/index.md
index d48008e..75bc2a6 100644
--- a/src/main/site/markdown/index.md
+++ b/src/main/site/markdown/index.md
@@ -34,3 +34,6 @@
The API documentation for htrace-core is online.
* [htrace-4.1.0-incubating JavaDoc](http://htrace.incubator.apache.org/javadoc/4.1/htrace-core/index.html)
+
+# Incubation Status
+Apache HTrace is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
