HTRACE-254 Minor compatible API cleanup: Take name on Tracer construction, deprecate Span#getChild
diff --git a/htrace-core/src/main/java/org/apache/htrace/core/Span.java b/htrace-core/src/main/java/org/apache/htrace/core/Span.java
index 4971983..e63d414 100644
--- a/htrace-core/src/main/java/org/apache/htrace/core/Span.java
+++ b/htrace-core/src/main/java/org/apache/htrace/core/Span.java
@@ -78,7 +78,9 @@
/**
* Create a child span of this span with the given description
+ * @deprecated Since 4.0.0. Use {@link MilliSpan.Builder}
*/
+ @Deprecated
Span child(String description);
@Override
diff --git a/htrace-core/src/main/java/org/apache/htrace/core/TraceScope.java b/htrace-core/src/main/java/org/apache/htrace/core/TraceScope.java
index b04d785..05a053e 100644
--- a/htrace-core/src/main/java/org/apache/htrace/core/TraceScope.java
+++ b/htrace-core/src/main/java/org/apache/htrace/core/TraceScope.java
@@ -17,14 +17,11 @@
package org.apache.htrace.core;
import java.io.Closeable;
-import java.lang.Thread;
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
+/**
+ * Create a new TraceScope at major transitions. Hosts current tracing context.
+ */
public class TraceScope implements Closeable {
- private static final Log LOG = LogFactory.getLog(TraceScope.class);
-
/**
* The tracer to use for this scope.
*/
@@ -112,7 +109,6 @@
@Override
public void close() {
tracer.closeScope(this);
-
}
public void addKVAnnotation(String key, String value) {
diff --git a/htrace-core/src/main/java/org/apache/htrace/core/Tracer.java b/htrace-core/src/main/java/org/apache/htrace/core/Tracer.java
index 7c4cc82..2a6d31e 100644
--- a/htrace-core/src/main/java/org/apache/htrace/core/Tracer.java
+++ b/htrace-core/src/main/java/org/apache/htrace/core/Tracer.java
@@ -17,7 +17,6 @@
package org.apache.htrace.core;
import java.io.Closeable;
-import java.lang.System;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
@@ -26,22 +25,22 @@
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutorService;
-import java.util.concurrent.ThreadLocalRandom;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
- * A Tracer provides the implementation for collecting and distributing Spans
- * within a process.
+ * Use a Tracer instance inside a 'process' to collect and distribute its trace Spans.
+ * Example processes are an HDFS DataNode or an HBase RegionServer. A Tracer instance is your
+ * one-stop shop for all things tracing.
+ *
+ * <p>
*/
public class Tracer implements Closeable {
private static final Log LOG = LogFactory.getLog(Tracer.class);
- public final static String SPAN_RECEIVER_CLASSES_KEY =
- "span.receiver.classes";
- public final static String SAMPLER_CLASSES_KEY =
- "sampler.classes";
+ public final static String SPAN_RECEIVER_CLASSES_KEY = "span.receiver.classes";
+ public final static String SAMPLER_CLASSES_KEY = "sampler.classes";
public static class Builder {
private String name;
@@ -50,9 +49,23 @@
Builder.class.getClassLoader();
private TracerPool tracerPool = TracerPool.GLOBAL;
+ /**
+ * @deprecated Since 4.0.0. Use Constructor that takes a <code>name</code> argument instead
+ */
+ @Deprecated
public Builder() {
}
+ public Builder(final String name) {
+ name(name);
+ }
+
+ /**
+ * @param name
+ * @return This
+ * @deprecated Since 4.0.0. Use Constructor that takes a <code>name</code> argument instead.
+ */
+ @Deprecated
public Builder name(String name) {
this.name = name;
return this;
@@ -141,7 +154,6 @@
if (name == null) {
throw new RuntimeException("You must specify a name for this Tracer.");
}
- LinkedList<SpanReceiver> spanReceivers = new LinkedList<SpanReceiver>();
LinkedList<Sampler> samplers = new LinkedList<Sampler>();
loadSamplers(samplers);
String tracerId = new TracerId(conf, name).get();
@@ -263,7 +275,7 @@
}
/**
- * If the current thread is tracing, this function returns the Tracer that is
+ * @return If the current thread is tracing, this function returns the Tracer that is
* being used; otherwise, it returns null.
*/
public static Tracer curThreadTracer() {
@@ -339,7 +351,7 @@
* Create a new trace scope.
*
* If there are no scopes above the current scope, we will apply our
- * configured samplers. Otherwise, we will create a span only if this thread
+ * configured samplers. Otherwise, we will create a trace Span only if this thread
* is already tracing, or if the passed parentID was valid.
*
* @param description The description of the new span to create.
@@ -375,8 +387,10 @@
* Create a new trace scope.
*
* If there are no scopes above the current scope, we will apply our
- * configured samplers. Otherwise, we will create a span only if this thread
+ * configured samplers. Otherwise, we will create a trace Span only if this thread
* is already tracing.
+ * @param description The description of the new span to create.
+ * @return The new trace scope.
*/
public TraceScope newScope(String description) {
TraceScope parentScope = threadLocalScope.get();
@@ -508,7 +522,6 @@
throwClientError(toString() + " is closed.");
}
Sampler[] samplers = curSamplers;
- int j = 0;
for (int i = 0; i < samplers.length; i++) {
if (samplers[i] == sampler) {
return false;
@@ -531,7 +544,6 @@
throwClientError(toString() + " is closed.");
}
Sampler[] samplers = curSamplers;
- int j = 0;
for (int i = 0; i < samplers.length; i++) {
if (samplers[i] == sampler) {
Sampler[] newSamplers = new Sampler[samplers.length - 1];
diff --git a/htrace-core/src/main/java/org/apache/htrace/core/TracerPool.java b/htrace-core/src/main/java/org/apache/htrace/core/TracerPool.java
index ea4d145..26e39f5 100644
--- a/htrace-core/src/main/java/org/apache/htrace/core/TracerPool.java
+++ b/htrace-core/src/main/java/org/apache/htrace/core/TracerPool.java
@@ -16,16 +16,20 @@
*/
package org.apache.htrace.core;
+import java.util.Arrays;
+import java.util.HashSet;
+
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.HashSet;
-import java.util.Iterator;
-
/**
* A pool of Tracer objects.
+ *
+ * There may be more than one {@link Tracer} running inside a single 'process'; for example,
+ * unit tests may spin up a DataNode, a NameNode, and HDFS clients all running in a single JVM
+ * instance, each with its own Tracer. TracerPool is where all Tracer instances register
+ * on creation so Tracers can coordinate around shared resources such as {@link SpanReceiver}
+ * instances. TracerPool takes care of properly cleaning up registered Tracer instances on shutdown.
*/
public class TracerPool {
private static final Log LOG = LogFactory.getLog(TracerPool.class);
@@ -118,7 +122,6 @@
*/
public synchronized boolean addReceiver(SpanReceiver receiver) {
SpanReceiver[] receivers = curReceivers;
- int j = 0;
for (int i = 0; i < receivers.length; i++) {
if (receivers[i] == receiver) {
LOG.trace(toString() + ": can't add receiver " + receiver.toString() +
@@ -157,7 +160,6 @@
*/
public synchronized boolean removeReceiver(SpanReceiver receiver) {
SpanReceiver[] receivers = curReceivers;
- int j = 0;
for (int i = 0; i < receivers.length; i++) {
if (receivers[i] == receiver) {
SpanReceiver[] newReceivers = new SpanReceiver[receivers.length - 1];
@@ -280,4 +282,4 @@
public String toString() {
return "TracerPool(" + name + ")";
}
-}
+}
\ No newline at end of file
