Require all span and trace creation through Tracer
MODIFY
dd-trace-ext/src/main/java/datadog/trace/tracer/ext/Scope.java
dd-trace-ext/src/main/java/datadog/trace/tracer/ext/Scope.java
@@ -4,13 +4,13 @@ import datadog.trace.tracer.Span;
import datadog.trace.tracer.Trace;
/**
- * A scope holds a single span or trace continuation and may optionally close out its span or
+ * A scope holds a single span or trace continuation and may optionally finish its span or
* continuation.
*
* <p>To create a scope, see {@link TracerContext#pushScope(Span, boolean)} and {@link
* TracerContext#pushScope(Trace.Continuation, boolean)}.
*
- * <p>All created scopes must be closed with {@link }
+ * <p>All created scopes must be closed with {@link Scope#close()}
*/
public interface Scope {
/** Get the span held by this scope. */

MODIFY
dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java
dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java
@@ -81,8 +81,8 @@ public final class TracerContext {
*/
public void popScope(Scope scope) {}
- /** @return The scope on the top of this scope stack or null if there is no active scope. */
- public Scope topOfScopeStack() {
+ /** @return The scope on the top of this scope-stack or null if there is no active scope. */
+ public Scope peekScope() {
return null;
}
}

MODIFY
dd-trace/src/main/java/datadog/trace/tracer/Span.java
dd-trace/src/main/java/datadog/trace/tracer/Span.java
@@ -5,7 +5,7 @@ package datadog.trace.tracer;
*
* <p>All spans are thread safe.
*
- * <p>Spans may not be constructed individually, but created through a {@link Trace}
+ * <p>To create a Span, see {@link Tracer#buildTrace()}
*/
public interface Span {

RENAME
dd-trace/src/main/java/datadog/trace/tracer/impl/SpanImpl.java
dd-trace/src/main/java/datadog/trace/tracer/SpanImpl.java
-package datadog.trace.tracer.impl;
+package datadog.trace.tracer;
-import datadog.trace.tracer.Clock;
-import datadog.trace.tracer.Span;
-import datadog.trace.tracer.SpanContext;
-import datadog.trace.tracer.Trace;
import java.util.Map;
public class SpanImpl implements Span {
@@ -33,17 +29,19 @@ public class SpanImpl implements Span {
/**
* Create a span with a start time of the current timestamp.
*
+ * @param parentContext identifies the parent of this span. May be null.
* @param clock The clock to use to measure the span's duration.
*/
- SpanImpl(final Clock clock) {}
+ SpanImpl(final SpanContext parentContext, final Clock clock) {}
/**
* Create a span with the a specific start timestamp.
*
+ * @param parentContext identifies the parent of this span. May be null.
* @param clock The clock to use to measure the span's duration.
- * @param startTimeNanoseconds Epoch time in nanoseconds when this span started.
+ * @param startTimestampNanoseconds Epoch time in nanoseconds when this span started.
*/
- SpanImpl(final Clock clock, final long startTimeNanoseconds) {}
+ SpanImpl(final SpanContext parentContext, final Clock clock, final long startTimestampNanoseconds) {}
@Override
public Trace getTrace() {

MODIFY
dd-trace/src/main/java/datadog/trace/tracer/Trace.java
dd-trace/src/main/java/datadog/trace/tracer/Trace.java
@@ -6,6 +6,8 @@ package datadog.trace.tracer;
*
* <p>A trace will be written when all of its spans are finished and all trace continuations are
* closed.
+ *
+ * <p>To create a Trace, see {@link Tracer#buildTrace()}
*/
public interface Trace {
/** Get the tracer which created this trace. */

RENAME
dd-trace/src/main/java/datadog/trace/tracer/impl/TraceImpl.java
dd-trace/src/main/java/datadog/trace/tracer/TraceImpl.java
-package datadog.trace.tracer.impl;
+package datadog.trace.tracer;
-import datadog.trace.tracer.Span;
import datadog.trace.tracer.writer.Writer;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;
@@ -27,4 +26,11 @@ public class TraceImpl {
* relying on getRootSpan() will break.
*/
private final List<Span> spans = null;
+
+ /**
+ * Create a new Trace.
+ *
+ * @param tracer the Tracer to apply settings from.
+ */
+ TraceImpl(Tracer tracer) {}
}

MODIFY
dd-trace/src/main/java/datadog/trace/tracer/Tracer.java
dd-trace/src/main/java/datadog/trace/tracer/Tracer.java
@@ -7,13 +7,34 @@ import datadog.trace.tracer.writer.Writer;
/** A Tracer creates {@link Trace}s and holds common settings across traces. */
public class Tracer {
/** Default service name if none provided on the trace or span */
- final String serviceName = null;
+ private final String serviceName = null;
/** Writer is an charge of reporting traces and spans to the desired endpoint */
- final Writer writer = null;
+ private final Writer writer = null;
/** Sampler defines the sampling policy in order to reduce the number of traces for instance */
- final Sampler sampler = null;
+ private final Sampler sampler = null;
/** Settings for this tracer. */
- final Config config = null;
+ private final Config config = null;
+ /** The clock to use for tracing. */
+ private final Clock clock = null;
+
+ /**
+ * Construct a new trace using this tracer's settings and return the root span.
+ *
+ * @return The root span of the new trace.
+ */
+ public Span buildTrace() {
+ return null;
+ }
+
+ /**
+ * Construct a new trace using this tracer's settings and return the root span.
+ *
+ * @param rootSpanStartTimestampNanoseconds Epoch time in nanoseconds when the root span started.
+ * @return The root span of the new trace.
+ */
+ public Span buildTrace(final long rootSpanStartTimestampNanoseconds) {
+ return null;
+ }
// TODO: doc inject and extract

Require all span and trace creation through Tracer